/submittal-review

name: submittal-review
description: >
  Expert PE review of a submittal (shop drawings, product data, samples,
  equipment brochures) against specs, drawings, code questions and trade
  coordination. Produces findings with both sources, trade routing and a
  completeness gate. Triggers: 'review submittal', 'review shop drawings'.
argument-hint: "<submittal.pdf> [--section \"12 35 53\"] [--resubmittal-of <review_id>]"
disable-model-invocation: true

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

| Script | Location | Purpose | |---|---|---| | `find_pages.py` | `${CLAUDE_PLUGIN_ROOT}/scripts/pdf/` | Index a large submittal once; find the pages for each element | | `check_review.py` | `${CLAUDE_SKILL_DIR}/scripts/` | Write review records; prove the review is complete | | `export_submittal_review.py` | `${CLAUDE_SKILL_DIR}/scripts/` | Build the Excel review, suggested disposition and markup items | | `annotate_pdf.py` | `${CLAUDE_PLUGIN_ROOT}/scripts/pdf/` | Write review clouds and notes onto a copy of the submittal | | `rasterize_page.py`, `crop_region.py`, `extract_text_region.py` | `${CLAUDE_PLUGIN_ROOT}/scripts/pdf/` | Read submittal and drawing pages | | `pdf_text.py` | `${CLAUDE_PLUGIN_ROOT}/scripts/pdf/` | Text of a submittal file; of a spec page AgentCM did not read, with `--pages` | | `issue_manager.py` | `${CLAUDE_PLUGIN_ROOT}/scripts/` | Log design-team questions as issues for `rfi-drafter` | | `write_finding.py` | `${CLAUDE_PLUGIN_ROOT}/scripts/graph/` | A finding in `.construction/skills/submittal-review/findings/` (both modes) | | `corrections_append.py` | `${CLAUDE_PLUGIN_ROOT}/scripts/` | AgentCM mode: record a correction of AgentCM's data (`reference/agentcm-mode.md`) |

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, ...).

3. **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). 4. **Prere