Demo Contractor Corrections

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:

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]
• ...