demo-contractor-corrections

name

demo-contractor-corrections

description

Local demo: Contractor corrections analysis and response — two-phase flow with a human-in-the-loop pause. Phase 1 reads the corrections letter, researches codes, views plan sheets, and generates questions for the contractor. The agent STOPS and presents questions to the user. After the user provides answers, Phase 2 generates the full response package (response letter, professional scope, corrections report, sheet annotations). Triggers on: 'Analyze these corrections' or 'Run the contractor flow on [path]'.

Demo: Contractor Corrections Flow

Run the contractor-side corrections analysis and response locally. You are helping a contractor understand and respond to a city corrections letter on their ADU permit.

This is a two-phase flow with a pause in the middle. Phase 1 produces questions. You STOP and present them. The user answers. Then Phase 2 generates deliverables.

How to Invoke

The user provides:

1. Corrections letter — PNG images or a PDF of the corrections letter (typically 1-3 pages)
2. Plan binder — either a PDF path or a directory of pre-extracted PNGs
3. (Optional) City name and project address — auto-detected from the corrections letter if not provided

Example invocations:

• "Analyze these corrections for my Placentia ADU project. Corrections: test-assets/corrections/. Plans: test-assets/01-extract-test/pages-png/"
• "Run the contractor flow. Corrections letter: path/to/corrections-p1.png and path/to/corrections-p2.png. Plan binder: path/to/plans.pdf"
• "I got corrections back from the city. Here they are: [paths]"

Input Resolution

Corrections letter:

• If PNG files: use directly with vision
• If a directory: find all PNGs in it, sort by name, read each as a page
• If PDF: extract to PNGs first (same as plan binder extraction below)

Plan binder:

• If a directory of PNGs: use directly. Check for pre-existing sheet-manifest.json and title-blocks/.
• If a PDF: extract with pdftoppm -png -r 200 "<input.pdf>" "<output-dir>/pages-png/page"

Output Directory

Create demo-output/contractor-<city>-<timestamp>/ in the workspace root. All output files go here.

---

PHASE 1: Analysis

Step 1.1: Parse Corrections Letter (~30 sec)

Read the corrections letter pages visually. Extract:

• Project info: address, city, jurisdiction number, job description, date, reviewer name
• Each correction item as a structured object:
  • Item number (preserve original numbering, including sub-items like 3a, 3b, 3c)
  • Original text (exact wording)
  • Code references (CRC, CBC, ASCE, CPC, B&P Code, municipal code)
  • Plan sheet references (Sheet A1, Detail 2/A3, etc.)
  • Review round (1st review outstanding vs. 2nd review new)
  • Bold/emphasis flags

Write corrections_parsed.json to output directory.

Step 1.2: Build Sheet Manifest (~30-90 sec)

Run concurrently with Step 1.1.

Follow the adu-targeted-page-viewer skill workflow:

1. Read page 1 (cover sheet) visually for the sheet index
2. Match sheet IDs to page numbers (title block reading if count mismatch)
3. Write sheet-manifest.json

Step 1.3: Parallel Research (~60-90 sec)

After Steps 1.1 and 1.2 complete, launch three concurrent subagents:

Subagent A — State Law Researcher:

• Load adu-skill-development/skill/california-adu/references/
• Look up every code section cited in the corrections (CRC, CBC, ASCE, CPC, B&P Code)
• For each: what does the code require? What are the thresholds? ADU exceptions?
• Write findings (will be merged in Step 1.4)

Subagent B — City Research:

• Check if adu-skill-development/skill/<city-slug>-adu/ exists
  • If yes: Load city skill references (offline, fast)
  • If no: Run adu-city-research — WebSearch for URLs, then WebFetch to extract content
• Focus on: municipal code amendments, standard details referenced in corrections, Information Bulletins
• Write findings (will be merged in Step 1.4)

Subagent C — Sheet Viewer:

• Using the sheet manifest, read only the plan sheets referenced by correction items
• For each referenced sheet, describe what is currently drawn in the area relevant to the correction
• Write sheet_observations.json

Step 1.4: Categorize + Generate Questions (~2 min)

Merge all research and categorize each correction item:

Category	Meaning
AUTO_FIXABLE	Drafter fixes: labels, notes, formatting, checklists
NEEDS_CONTRACTOR_INPUT	Requires specific facts from the contractor (pipe sizes, elevations, materials)
NEEDS_PROFESSIONAL	Requires licensed professional work (structural calcs, fire-rated details, stamps)

For each item, document:

• Category assignment with justification
• Research context (what the code requires, what the city adds)
• What's currently on the plan (from sheet observations)
• What needs to change

Write corrections_categorized.json.

For NEEDS_CONTRACTOR_INPUT items, generate specific questions:

• Each question includes research_context explaining why it's being asked
• Question types: choice, text, number, measurement, multi_choice
• Questions are informed by the code research — they ask for specific data, not vague descriptions

Write contractor_questions.json.

Also write state_law_findings.json (from Subagent A) and any city research files.

---

⛔ STOP HERE — Present Questions to the User

After Phase 1 completes, you MUST stop and wait for the user.

Present the results in this format:

---

Phase 1 Complete — Corrections Analysis

Project: [address], [city] — [permit number] Corrections: [N] items parsed from [review round] Breakdown: [X] auto-fixable, [Y] need your input, [Z] need professional work

Questions for You

For each question group (organized by correction item):

Item [#] — [summary] [research context — why this matters, what the code says]

1. [question text]
   • Options: [if choice type]
2. [question text] ...

Auto-Fixable Items (no input needed)

• Item [#]: [summary] — [what will be done]
• ...

Professional Items (scoped for your design team)

• Item [#]: [summary] — needs [professional role]
• ...

Answer the questions above and I'll generate your response package.

You can also say:

• "Use the mock answers" (loads test-assets/mock-session/contractor_answers.json)
• "Skip the questions, just generate with what you have" (Phase 2 runs with TODO placeholders)

---

Wait for the user's response before proceeding to Phase 2.

---

PHASE 2: Generate Response Package

Triggered when the user provides answers. Three ways this happens:

1. User answers inline — Parse their answers from the conversation. Map to question IDs.
2. User says "use mock answers" — Load test-assets/mock-session/contractor_answers.json
3. User says "skip" or "generate with what you have" — Proceed with empty answers; TODO placeholders in outputs.

Write contractor_answers.json to the output directory (even if loaded from mock).

Step 2.1: Load Phase 1 Context

Read all Phase 1 outputs from the output directory:

1. corrections_categorized.json — the backbone, read first
2. contractor_answers.json — map answers to items
3. sheet-manifest.json — for sheet references
4. corrections_parsed.json — for original wording

Step 2.2: Generate Four Deliverables

Follow the adu-corrections-complete skill specification. Generate all four:

1. response_letter.md — Professional letter to the building department

• Address EVERY item, even procedural ones
• Preserve original correction wording
• Incorporate contractor answers with code justification
• Reference specific sheets from manifest
• End with a sheet revisions summary table

2. professional_scope.md — Work breakdown by professional

• Group by role: Designer, Structural Engineer, HERS Rater
• Include Key Specifications section with contractor-provided details
• Ready-to-use notes for the design team (DFU justification, grade table, dimensions)
• Status per item: READY, PENDING, FINAL STEP

3. corrections_report.md — Status dashboard / checklist

• Summary table by category
• Key findings from contractor answers (capacity conclusions, drainage assessment)
• Action items checklist with checkboxes
• Critical path (what blocks what, what can run in parallel)

4. sheet_annotations.json — Per-sheet markup instructions

• Every annotation references a valid sheet from the manifest
• Revision notes ready for a revision table
• Specifications from contractor answers mapped to sheet locations

Step 2.3: Present Results

After generating all deliverables, present to the user:

• Summary: what was generated, where files are saved
• The full response_letter.md content (this is the main deliverable they care about)
• Highlights from the professional scope (who needs to do what)
• Link to the corrections report for the full status view

---

Test Data

Ready-to-use test data for the Placentia demo project:

Asset	Path
Corrections letter (2 pages)	test-assets/corrections/1232-n-jefferson-corrections-p1.png and p2.png
Plan pages (15 PNGs)	test-assets/01-extract-test/pages-png/
Mock session data	test-assets/mock-session/ (all Phase 1 outputs pre-built)
Mock contractor answers	test-assets/mock-session/contractor_answers.json
Real agent output (comparison)	test-assets/correction-01/

Quick demo path (skips Phase 1, tests Phase 2 only):

• "Generate the response package using the mock session data at test-assets/mock-session/"
• This loads pre-built Phase 1 artifacts + mock answers and jumps straight to Phase 2 deliverables.

Sub-Skills Referenced

Skill	Location	Role
adu-targeted-page-viewer	adu-skill-development/skill/adu-targeted-page-viewer/	PDF extraction + sheet manifest
california-adu	adu-skill-development/skill/california-adu/	State law (28 reference files)
adu-city-research	.claude/skills/adu-city-research/	Web research for non-onboarded cities
adu-corrections-complete	adu-skill-development/skill/adu-corrections-complete/	Phase 2 output spec
placentia-adu	adu-skill-development/skill/placentia-adu/	Placentia-specific rules
buena-park-adu	adu-skill-development/skill/buena-park-adu/	Buena Park-specific rules