Adu Corrections Flow

ADU Corrections Flow

Overview

Analyze ADU permit corrections and generate informed contractor questions. This is the first skill in a two-skill pipeline:

1. adu-corrections-flow (this skill) — reads corrections, researches codes, categorizes items, generates questions
2. adu-corrections-complete (second skill) — takes contractor answers + these research artifacts, generates the final response package

This skill coordinates three sub-skills through a 4-phase workflow and stops after producing contractor_questions.json.

Sub-skills used:

Key principle: Research happens before contractor questions. Questions informed by actual code requirements are specific and answerable in seconds. Vague questions waste the contractor's time.

Inputs

Outputs

All outputs are written to the session directory (e.g., correction-01/).

This skill stops here. The contractor_questions.json goes to the UI. After the contractor answers, the adu-corrections-complete skill takes the session directory + contractor_answers.json and generates the final response package (response letter, professional scope, corrections report, sheet annotations).

Do NOT generate Phase 5 outputs (response letter, professional scope, etc.). That is the job of adu-corrections-complete. Generating them here creates TODO-filled drafts that the second skill doesn't use.

Workflow

Phase 1 + Phase 2 (concurrent)

These two phases run simultaneously — they have no dependencies on each other.

Phase 1: Read Corrections Letter

Read the corrections letter visually (1-3 page PNG or PDF). No sub-skill needed — direct vision reading.

Extract each correction item as a structured object. Preserve the exact original wording. Identify all code references (CRC, CBC, ASCE, B&P Code, municipal code, etc.) and any sheet references.

Save as corrections_parsed.json. See references/output-schemas.md for the full schema.

Phase 2: Build Sheet Manifest

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

1. Check first: PNGs and title block crops may already be pre-extracted in project-files/pages-png/ and project-files/title-blocks/. If they exist, skip extraction and go straight to reading the cover sheet.
2. If PNGs don't exist: Extract PDF pages to PNGs: scripts/extract-pages.sh <binder.pdf> <output-dir>
3. Read the cover sheet (page 1) for the sheet index
4. If page count differs from index count, crop and read title blocks to resolve
5. Save sheet-manifest.json

This takes ~90 seconds (or ~30 seconds if PNGs are pre-extracted) and produces the sheet-to-page mapping needed for Phase 3C.

Phase 3 (concurrent — 3 subagents)

After Phases 1+2 complete, launch three parallel research subagents. Each is specialized by domain. All receive the parsed corrections from Phase 1.

See references/subagent-prompts.md for the full subagent prompts.

Subagent 3A: State Law Researcher

• Skill context: california-adu (28 reference files, all offline)
• Input: All correction items with their code references
• Task: Look up every referenced code section. Deduplicate — if multiple items cite the same section, look it up once and link to all relevant items.
• Speed: Fast — no network, just reading reference files (~60 sec)
• Output: Per-code-section findings with requirements, thresholds, ADU exceptions

Subagent 3B: City Discovery

• Skill context: adu-city-research — Mode 1 (Discovery) only
• Input: City name + list of topics extracted from corrections
• Task: Run WebSearch to find the city's key ADU-related URLs: ADU page, municipal code platform, standard detail PDFs, Information Bulletins, submittal requirements. Do NOT fetch page content — just find URLs.
• Speed: Fast — WebSearch only (~30 sec)
• Output: city_discovery.json — categorized URL list for extraction

Subagent 3C: Sheet Viewer

• Skill context: adu-targeted-page-viewer
• Input: Sheet manifest from Phase 2 + sheet references from corrections
• Task: Read only the plan sheets referenced by correction items (typically 5-8 out of 15-30 pages). For each, describe what is currently drawn in the area relevant to the correction.
• Speed: Fast — just reading PNGs (~60 sec)
• Output: Per-sheet observations: current state, what appears missing, location on sheet

Phase 3.5: City Extraction

After Phase 3 completes (all three subagents return), launch city content extraction using the URLs discovered by Subagent 3B.

Single-Agent Mode (default)

One subagent runs adu-city-research Mode 2 (Targeted Extraction) against all discovered URLs.

• Input: city_discovery.json + correction topics
• Task: WebFetch each discovered URL, extract content relevant to corrections. Prioritize standard detail PDFs and municipal code sections.
• Speed: ~60-90 sec (depends on URL count)
• Output: city_research_findings.json

Fan-Out Mode (optional, for speed)

Split the discovered URLs across 2-3 subagents by topic:

• Agent 1: Municipal code URLs — local amendments, ADU ordinance, grading chapter
• Agent 2: Standard detail PDFs + Information Bulletin URLs
• Agent 3: ADU page + submittal requirements

Each agent runs adu-city-research Mode 2 with its URL subset. Orchestrator merges results into a single city_research_findings.json.

When to use fan-out: When Discovery returns 6+ URLs across multiple categories. For smaller cities with 2-3 URLs, single-agent is sufficient.