/spec-splitter

name: spec-splitter
description: >
  Split a bound project manual PDF into individual spec section PDFs and
  extract searchable text. Triggers: 'split specs', 'break up the project
  manual', 'separate spec sections', 'extract spec text'. Prerequisite
  for /submittal-log-generator.
argument-hint: "<project_manual.pdf> [--output-dir <path>]"

Spec Splitter

Two functions for specification processing:

1. **Split**: Break a bound project manual PDF into individual spec section PDFs — navigable files the project team can use directly 2. **Extract**: Pull searchable text from each section PDF into persistent `.txt` files — enables downstream skills (submittal-log-generator, submittal-review, bid-evaluator) to work from text without re-extracting from PDFs

Pipeline Position

Run after `/project-setup` identifies bound spec manuals. Produces split PDFs, `spec_index.yaml`, and extracted text consumed by `/submittal-log-generator` and `/code-researcher`.

Either function can run independently. For example, specs may already be split but text has not yet been extracted.

In an AgentCM project, AgentCM has already read the manuals: each section's text is in `.construction/specs/`, listed in `.construction/INDEX.md`. There this skill does only what AgentCM could not (Step 1).

Workflow

Spec Split Progress:
- [ ] Step 1: Check the mode, then the current state (split? text extracted?)
- [ ] Step 2: Discover Specifications directory
- [ ] Step 3: Find ALL spec PDFs (bound manuals)
- [ ] Step 4-5: Split PDF into individual section files
- [ ] Step 6: Write spec index
- [ ] Step 7: Extract text from all sections
- [ ] Step 8: Repair degraded/poor text quality

Step 1: Check the Mode, Then the Current State

Read `.construction/project.yaml` first.

**AgentCM mode** (the file exists). AgentCM has read the project manuals' text layer: every section it found has its text in `.construction/specs/<section>.txt` (`08-71-00.txt` for 08 71 00), each line prefixed with its page. Never split or extract a manual AgentCM has read; the other skills read `specs/` here. Read `.construction/INDEX.md`; if it is missing, say that AgentCM has not written its index for this folder, and stop.

1. **`## Specification sections (N)`**, a table of Section | Title | Division | Agent file | PDF | Pages: report how many sections AgentCM holds, by division and manual, and that their text is in `.construction/specs/`. 2. **`## Spec manuals not read (N)`**, when present, a table of PDF | Pages | Why (a scan with no text layer, or no SECTION headings): for each manual listed there, and only those, run Steps 2–8 for that manual alone, and say so: "AgentCM could not read {PDF} ({Why}), so I am splitting and extracting it here. Its section PDFs go to the specs folder, which AgentCM's Rescan will index; its text goes to `.construction/skills/spec_text/`." Its boundaries come from [Boundaries without SECTION headings](#boundaries-without-section-headings): what AgentCM reports means the split script cannot find them itself. 3. **Section PDFs of a manual AgentCM has read**, only when the PE asks for those files: build them from AgentCM's list, as [Section PDFs from AgentCM's list](#section-pdfs-from-agentcms-list) says. No text extraction: the text is AgentCM's.

Then stop. Nothing else in this skill runs in AgentCM mode.

**Flat-file mode** (no `.construction/project.yaml`). Check what already exists:

**Split PDFs present?**

• Look for individual spec section PDFs with CSI section numbers in filenames (e.g., `03 30 00 - Cast-in-Place Concrete.pdf`)
• Check for `spec_index.yaml`
• If found, report count and skip to Step 7 (text extraction)

**Text already extracted?**

• Check `.construction/skills/spec_text/manifest.json`. Older versions wrote it to `.construction/spec_text/`: if only that exists, copy the folder to `.construction/skills/spec_text/` and leave the old one as it is
• If manifest exists and covers all sections, report and skip Step 7

Step 2: Discover Specifications Directory

Determine where split spec PDFs should go. Search for an existing Specifications directory (case-insensitive): 1. `02 - Specifications/` (numbered project folder convention) 2. `Specifications/` 3. Any folder with "specification" in the name

**Output directory resolution:**

• If Specifications directory found → output to `{specs_dir}/Specification Sections/`
• If not found → output to `Specification Sections/` in project root

Step 3: Find ALL Spec PDFs

Search the project directory for ALL PDFs that are specifications. Many projects have multiple spec PDFs:

• **Multi-volume**: Volume 1.pdf, Volume 2.pdf (split by CSI division range)
• **Single bound manual**: one large PDF with all sections
• **Attachment-based**: Attachment-E-Specs.pdf (government projects)

Search in:

• The Specifications directory discovered in Step 2
• The project root (some projects have no folder structure)
• Look for PDFs > 1MB with keywords: "spec", "manual", "volume", "attachment" + spec-related terms

Process EACH PDF found. All split sections go to the same output directory.

If the user specifies a single file (`/spec-splitter path/to/specific-volume.pdf`), process only that file.

Steps 4-6: Split and Index

Run the split script with the resolved output directory:

"${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_SKILL_DIR}/scripts/split_spec_manual.py" \
  "{project_manual.pdf}" \
  --output-dir "{resolved_spec_sections_dir}"

The script: 1. Scans ALL pages for `SECTION XX XX XX` headers to find exact page boundaries — this is the primary method and does NOT depend on a Table of Contents 2. Scans all pages for Table of Contents entries to enrich section titles (optional, best-effort) 3. For sections without ToC titles, extracts titles directly from the section header page 4. Splits into individual PDFs named `{section_number} - {SECTION TITLE}.pdf` 5. Writes `spec_index.yaml` with section metadata

**ToC edg