ADU Plan Review — City Corrections Generator

City Routing

The city knowledge source depends on whether the city has been onboarded:

Input: city_name

IF dedicated city skill exists (e.g., placentia-adu/):
  → Tier 3: Load city skill reference files (offline, fast, ~30 sec)
ELSE:
  → Tier 2: Run adu-city-research
    → Mode 1 (Discovery): WebSearch for city URLs (~30 sec)
    → Mode 2 (Extraction): WebFetch discovered URLs (~60-90 sec)
    → Mode 3 (Browser Fallback): Only if extraction has gaps (~2-3 min)

How to detect onboarded cities: Check for a city skill directory at skill/{city-slug}-adu/SKILL.md. If it exists, the city is onboarded. If not, fall back to web research.

Tier 1 (state law only) is always available — it's the california-adu skill. Even without any city knowledge, state law catches ~70% of common corrections.

Inputs

Review scope options:

• administrative — Cover sheet, sheet index, stamps/signatures, governing codes, project data. Fast (~2 min), HIGH confidence. Good for completeness screening.
• full — All sheet types, all check categories. Slower (~5-8 min), mixed confidence. Produces the draft corrections letter.

Outputs

All written to the session directory.

Workflow

Phase 1: Extract & Map

Run adu-targeted-page-viewer:

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 cover sheet for sheet index
4. Match sheet IDs to pages (title block reading if needed)
5. Save sheet-manifest.json

~90 seconds (or ~30 seconds if PNGs are pre-extracted). Identical to Phase 2 of adu-corrections-flow.

Phase 2: Sheet-by-Sheet Review

Review each sheet against the relevant checklist reference file. Group sheets by discipline to limit subagent count.

Subagent grouping:

Rolling window: 3 subagents in flight. Architectural A + Architectural B + Site/Civil start first. As each completes, launch the next.

Each subagent receives:

• The sheet PNG(s) for its assigned sheets
• The relevant checklist reference file(s)
• The sheet manifest (for cross-reference context)

Each subagent produces: A findings array for its sheets — one entry per check, with:

• check_id — Which checklist item (e.g., "1A" = architect stamp)
• sheet_id — Which sheet (e.g., "A1")
• status — PASS | FAIL | UNCLEAR | NOT_APPLICABLE
• visual_confidence — HIGH | MEDIUM | LOW
• observation — What the subagent actually saw (evidence)
• code_ref — Code section this check is grounded in

For administrative review scope: Only launch the Architectural A subagent (cover sheet + floor plan). Skip all others.

~2-3 minutes for full review (5 subagents, 3-at-a-time rolling window).

Phase 3: Code Compliance (concurrent 3A + 3B)

After Phase 2 completes, launch two concurrent subagents to verify findings against code.

3A: State Law Verification

• Skill: california-adu
• Input: All FAIL and UNCLEAR findings from Phase 2
• Task: For each finding, look up the cited code section in the california-adu reference files. Verify: Is this actually required by state law? What are the exact thresholds? Are there ADU-specific exceptions?
• Output: state_compliance.json — per-finding code verification with exact citations

Why this matters: The checklist reference files cite code sections, but the california-adu skill has the detailed rules with exceptions and thresholds. Phase 3A catches false positives — e.g., the checklist flags a 3-foot setback, but the ADU is a conversion and conversions have no setback requirement.

3B: City Rules

Route based on City Routing decision (see above).

If onboarded city (Tier 3):

• Load city skill reference files
• Check findings against city-specific amendments, standard details, and IBs
• Fast — ~30 sec, all offline

If web research (Tier 2):

• Run adu-city-research Mode 1 → Mode 2 → optional Mode 3
• Check findings against discovered city requirements
• Slower — ~90 sec to 3 min

Output: city_compliance.json — city-specific requirements, local amendments, standard details that apply to the findings

Phase 4: Generate Draft Corrections Letter

Single agent merges all inputs and produces the corrections letter.

Inputs to this phase:

1. sheet_findings.json (Phase 2) — what the AI found on the plans
2. state_compliance.json (Phase 3A) — state law verification
3. city_compliance.json (Phase 3B) — city-specific rules
4. sheet-manifest.json (Phase 1) — for sheet references

For each finding, apply this filter:

Output format — draft_corrections.json:

Each correction item includes:

• item_number — Sequential
• section — Building, Fire/Life Safety, Site/Civil, Planning/Zoning
• description — The correction text (what needs to be fixed)
• code_citation — Specific code section(s)
• sheet_reference — Which sheet(s) are affected
• confidence — HIGH | MEDIUM | LOW
• visual_confidence — How certain the AI is about the visual observation
• reviewer_action — CONFIRM (quick check) | VERIFY (needs closer look) | COMPLETE (reviewer must fill in)

See references/output-schemas.md for full JSON schema.

Phase 4 also outputs draft_corrections.md — a formatted markdown version of the corrections letter. This markdown is the handoff to Phase 5 (PDF generation) and also serves as the frontend-renderable version.

Phase 5: PDF Generation + QA Loop (sub-agent)

Launch the adu-corrections-pdf skill as a sub-agent. This skill uses the document-skills/pdf primitive (reportlab, pdf-lib, pypdfium2) for the actual PDF generation. It only handles formatting — no research, no content changes.

Sub-agent skills loaded:

• adu-corrections-pdf — domain formatting (letterhead, badges, sections)
• document-skills/pdf — PDF generation primitives (reportlab, pypdfium2, etc.)

Sub-agent input:

• draft_corrections.md from Phase 4
• City name, project address, project info (from Phase 1 cover sheet extraction)
• Output path for the PDF

Sub-agent output:

• corrections_letter.pdf — Professional formatted PDF with city header, confidence badges, proper pagination
• qa_screenshot.png — Screenshot of page 1

QA Loop

After the sub-agent returns the screenshot, the main agent (not the sub-agent) reviews it:

LOOP (max 2 retries):
  1. View qa_screenshot.png
  2. Check:
     - Header correct? (city name, project info, "DRAFT" visible)
     - Sections formatted? (numbered items, horizontal rules)
     - Tables readable? (no overflow, columns aligned)
     - No layout breaks? (text not cut off, pages not blank)
     - Footer present? (page numbers, draft disclaimer)
  3. IF everything looks good → Phase 5 COMPLETE
  4. IF issues found → re-invoke sub-agent with fix_instructions:
     - Describe what's wrong: "Table on page 2 overflows right margin"
     - Sub-agent applies fix and regenerates PDF + new screenshot
     - Return to step 1

Max 2 retries. If the PDF still has issues after 2 fix attempts, deliver it as-is with a note to the user. A slightly imperfect PDF is better than an infinite loop.

The draft_corrections.md serves double duty:

1. Input to the PDF sub-agent (Phase 5) → downloadable PDF
2. Input to the frontend UI (rendered in Next.js) → interactive viewer

Both consumers get the same content. The markdown is the source of truth.

Timing

Reference Files

Checklist References (what to check per sheet type)

Output References

Sub-Skill References

Important Notes

• No false positives. A city tool that generates incorrect corrections destroys trust. Phase 4's filter is designed to DROP findings that lack code basis rather than include them with low confidence. Err on the side of missing something (the human reviewer catches it) rather than flagging something incorrectly.
• Reviewer blanks > AI guesses. For structural, engineering, and judgment-call items, insert [REVIEWER: describe what needs human assessment] rather than attempting an assessment. The AI's job is the repeatable 60%, not the expert 40%.
• Objective standards only. Per Gov. Code § 66314(b)(1), ADUs can only be subject to objective (measurable, verifiable) standards. If a potential finding requires subjective judgment ("design doesn't match neighborhood character"), do NOT include it. This is the law.
• State preemption. State law sets minimum ADU rights. If city rules are MORE restrictive than state law, flag the conflict — the state law prevails. The california-adu skill is the authority on state requirements.
• Two confidence dimensions. Every finding has both code confidence (is this legally required?) and visual confidence (am I right about what I see?). Both must be reported. A reviewer needs to know "the law is clear but I'm not sure what I see" vs. "I can clearly see this but I'm not sure it's required."