dleerdefi/claude-code-construction/submittal-review

Submittal Review

Review a submittal the way an experienced Project Engineer does, then hand the PE a draft GC review they can trust. The trust comes from four things:

• every requirement is traced from the contract documents before the submittal is opened;
• every document that governs an element is read, and the gate proves it;
• every finding cites both sides and says who acts;
• nothing the documents cannot answer is stated as fact.

What it produces: findings with sources and actions, a suggested GC disposition, routing to the trades that must act and by when, code and authority questions, and what could not be verified. What it never does: approve, stamp or send anything. The PE decides the disposition and sends the review.

The procedure is the same for every CSI division. Your knowledge of the trade supplies the checks. references/review-lens.md lists what reviews most often skip: package questions, cross-trade handoffs, and code and authority questions.

Permitted Scripts

Run every script through "${CLAUDE_PLUGIN_ROOT}/bin/construction-python". Double-quote every path. Do not write custom scripts or inline Python. Write every file in the review folder with the Write tool, and change one with the Edit tool. Never use a shell loop, heredoc, echo > or sed -i, even for fifteen elements that look alike. Check the files with check_review.py --review-dir, which names a file that is not valid JSON with its line and column, never with Python of your own. construction-python is always there: never probe for another Python (python3 - <<…, python --version), even with an empty program.

Load the construction-guide skill before reading any project document. Never read construction PDFs directly: rasterize pages first.

Data Contract

Everything for one review lives in .construction/skills/submittal-review/{review_id}/, where review_id is the submittal number and revision with spaces as hyphens (12-35-53-001-R0). Page images, crops and saved text dumps (pdf_text.py --output) go there too, never in /tmp or any other folder outside the project. The exact formats are in ${CLAUDE_SKILL_DIR}/references/review-data.md; read it before Step 1.

state.yaml            submittal, sections, facility types, jurisdiction, schedule, status
pages_N.json          page index of submittal file N (find_pages.py)
trace.json            every element the contract documents require, with every governing reference
inventory.json        where each element is in the submittal (or that it is missing)
review_NN.json        per element: each governing reference read, findings, unverifiable items, questions
package_review.json   the package questions and every cross-document reconciliation
findings_NN.json      findings
compliance.json       code and authority questions: open, or researched with a source
routing.json          each trade that must act: what to send, what is needed back, gate, need-by
prior.json            resubmittals only: what happened to each prior finding

state.yaml carries status. On restart, read it and resume at the step after the last completed one.

Workflow

- [ ] 1. Intake               - [ ] 6. Package questions and reconciliations
- [ ] 2. Trace requirements   - [ ] 7. Code questions and routing
- [ ] 3. Inventory            - [ ] 8. Gate
- [ ] 4. Checkpoint           - [ ] 9. Report
- [ ] 5. Review (fan out per element)

1. Intake

1. Mode. .construction/project.yaml present → AgentCM mode; otherwise flat file. In AgentCM mode, follow ${CLAUDE_PLUGIN_ROOT}/reference/agentcm-mode.md: which source wins, what a missing file or an empty search means, which file answers what, drawings through crop.sh, and how to record a correction of AgentCM's data.
2. Submittal. Locate the package file(s). Read the cover or transmittal for:

• submittal number, revision and title;
• subcontractor;
• spec section(s);
• submittal types, using submittal-log-generator's labels (Shop Drawings, Product Data, Samples, Design Data, Test Reports, Certificates, Delegated Design, ...).

1. Resubmittal. If the revision is above zero or the user names a prior review, find the prior review directory. Every prior finding must be accounted for in prior.json (Step 6).
2. Prerequisites.

• Spec text. In AgentCM mode, read each section from .construction/specs/<section>.txt (08 71 00 is 08-71-00.txt; each line starts with its page), listed in .construction/INDEX.md: it is the section's text, and a section's pages are never extracted again from the PDF. A read manual's pages in no section (INDEX.md lists them) are read in the PDF, those pages only (pdf_text.py --pages). Never run pdf_text.py or rasterize_page.py on a section's pages: not to check them, not in a page range and not in a whole-manual dump. Only for a manual INDEX.md lists under "Spec manuals not read" is it in .construction/skills/spec_text/. Otherwise the text must exist in .construction/skills/spec_text/. When text spec-splitter provides is missing, invoke the construction:spec-splitter skill (Skill tool) yourself.
• Drawing sheets should be split and indexed (sheet_index.yaml, or AgentCM's index). sheet-splitter is user-invoked only, so you cannot run it from here: ask the user to run /construction:sheet-splitter and resume. If nobody can answer (unattended run), continue with the bound drawing set, locate sheets with find_pages.py, and add a notes entry in state.yaml saying the drawings were not split.

1. Project facts. Read .construction/skills/project_context.yaml:

• Facility types (building.facility_types): if missing, infer them from the cover sheet and code analysis, and confirm them at the checkpoint.
• Jurisdiction: city, county and state.
• Construction schedule: if the project has one, record its path in state.yaml as schedule.

1. Register. Check the submittal log for this item, and the RFI log and ASI/bulletin log for changes that affect the section. Note approved submittals this one depends on, such as the approved sink or fume hood a casework submittal must fit.
2. Lessons. If .construction/skills/submittal-review/lessons.yaml exists, read it. It holds what earlier reviews on this project missed or the PE overturned.
3. Index each submittal file (any file over about 20 pages):

``bash PY="${CLAUDE_PLUGIN_ROOT}/bin/construction-python"; FP="${CLAUDE_PLUGIN_ROOT}/scripts/pdf/find_pages.py" "$PY" "$FP" index --pdf "{submittal file N}" --output "{dir}/pages_N.json" `` It reports pages with no text layer (scans). Those must be rasterized to be read.

Write state.yaml (status: intake).

2. Trace requirements (before reading the submittal)

A review fails most often because the right detail was never pulled. Build trace.json from the contract documents alone:

1. Package requirements. Every submittal requirement in Part 1 of the section, with its article reference.
2. Elements. Every element of the scope in the contract documents:

• Use each tagged elevation, equipment item, mark, door number, fixture type or assembly.
• Find them in plans, elevations, details and schedules.
• In AgentCM mode, start from AgentCM's files instead of reading sheets: .construction/tags.tsv (every occurrence of a mark, door number or other known identifier, with its sheet and position), .construction/xrefs.tsv (every reference between sheets, details and specification sections), the schedules INDEX.md lists (.construction/schedules/<sheet>-<n>.tsv) and, for what those miss, the sheet's .construction/sheets/<sheet>.tsv.
• For product data with no tagged elements, the elements are the products the spec requires.

1. Governing references per element (cd_refs): every sheet, detail, section cut, schedule row and spec article that governs it. Follow every cut drawn on an elevation or plan. Record in stated what each one states about the element (sizes, models, ratings, heights, voltages, finishes, supports).
2. Changes. Apply responded RFIs, ASIs and bulletins to the trace, citing them.

3. Inventory the submittal

Map the submittal to the trace in inventory.json, both ways.

1. Find each element's pages. For an indexed file, write element_terms.json with the search terms for each element: tag, item number, name, scheduled model. Then run:

``bash "$PY" "$FP" map --index "{dir}/pages_N.json" --elements "{dir}/element_terms.json" --output "{dir}/page_map_N.json" `` It lists, per element, its heading pages and the pages that follow until the next element's tab. It also lists tabs that match no element (possible extra items), pages that match nothing, and image-only pages.

1. Confirm the map. Check each element's first page by reading its heading (extract_text_region.py, or a rasterized strip). For a short file, identify pages from titles and tags directly.
2. Record the result:

• each trace element → its pages, or missing;
• each submittal item with no matching element → extra_items, with a note;
• each Part 1 package requirement → submitted or missing.

A missing element or package item becomes a completeness finding. Keep this pass light; detailed reading happens in Step 5.

4. Checkpoint

Show the user, in one short message:

• the section(s), submittal types, element count and pages, facility types and jurisdiction;
• the code and authority questions the trace already raises (accessibility, health department, fire, state agency, utility), each as a question.

Ask two things: confirm the facility types and jurisdiction, and whether to run /construction:code-researcher on those questions. A researched question can be checked. An unresearched one stays open in the report and is never answered from memory.

Write confirmed facility types to project_context.yaml (building.facility_types) if they were missing. If nobody can answer (unattended run), set unattended: true, proceed with the inferred values, leave every question open, and say so at the top of the report.

5. Review

Start each batch from its records:

"$PY" "${CLAUDE_SKILL_DIR}/scripts/check_review.py" --review-dir "{dir}" --scaffold {NN} --elements "{ids}"

This writes review_{NN}.json with every governing reference of each element marked todo.