ADU City Research

When to Use Each Mode

• Standalone (no orchestrator): Run Discovery → Extraction → Fallback (if needed). Single agent, sequential.
• Orchestrated (called by adu-corrections-flow): The orchestrator specifies which mode to run. Discovery runs in parallel with other research. Extraction runs after Discovery completes. Fallback runs only if Extraction has gaps.
• Fan-out ready: The Extraction mode takes a list of URLs + topics. An orchestrator can split this list across multiple agents for parallel extraction without changing the mode's logic.

Mode 1: Discovery

Tool: WebSearch only Input: City name + list of correction topics (optional — omit for comprehensive discovery) Output: city_discovery.json — key URLs organized by category Time: ~30 seconds

Process

Run 3-5 targeted web searches to find the city's key ADU-related pages. Do NOT fetch or read the pages — just find the URLs.

Search queries to run (in order of priority):

1. "City of [Name]" ADU accessory dwelling unit — finds the city's ADU page
2. "City of [Name]" municipal code — finds the code platform (ecode360, Municode, QCode, etc.)
3. "City of [Name]" standard detail construction OR "City of [Name]" standard plans engineering — finds standard detail PDFs
4. "City of [Name]" information bulletin building — finds IBs
5. "City of [Name]" building permit submittal requirements — finds checklists

If correction topics are provided, add targeted searches:

Platform detection: Identify the municipal code platform from search results. See references/municipal-code-platforms.md for the major platforms (ecode360, Municode, QCode, American Legal, Sterling Codifiers, city-hosted).

Building vs. Planning split: Larger cities often split ADU information across two departments. Flag both URLs if found.

Discovery Output Format

{
  "city": "City name",
  "discovery_timestamp": "ISO date",
  "urls": {
    "adu_page": "https://...",
    "adu_page_building": "https://... (if separate from planning)",
    "municipal_code": {
      "platform": "ecode360 | municode | qcode | amlegal | sterling | city-hosted",
      "base_url": "https://...",
      "building_code_title_url": "https://... (if found in search results)",
      "zoning_title_url": "https://... (if found in search results)"
    },
    "standard_details": [
      {"name": "Inferred name from search result", "url": "https://..."}
    ],
    "information_bulletins": [
      {"name": "Inferred name from search result", "url": "https://..."}
    ],
    "submittal_requirements": "https://...",
    "pre_approved_plans": "https://..."
  },
  "not_found": ["category names where no URLs were found"],
  "notes": "Any observations from search results (e.g., 'city appears to use Municode but ADU page links to a separate handout site')"
}

Important: Discovery only finds URLs — it does NOT read page content. Speed comes from not fetching anything. The Extraction mode does the reading.

Mode 2: Targeted Extraction

Tool: WebFetch primarily Input: Discovery results (city_discovery.json or equivalent URL list) + specific topics to extract Output: city_research_findings.json — extracted content organized by category Time: ~60-90 seconds (depends on number of URLs)

Process

For each URL from Discovery, fetch the page content and extract information relevant to the correction topics. Prioritize by impact.

Extraction priority (highest first):

1. Standard detail PDFs — If the corrections reference city standard details, fetching these PDFs is the single most valuable action. They show exactly what the city wants drawn.
2. Municipal code sections — Fetch the specific title/chapter relevant to corrections (building code amendments, ADU ordinance, grading chapter). Do NOT fetch the entire municipal code.
3. Information Bulletins — Fetch IBs relevant to correction topics (wind parameters, submittal guides).
4. ADU page content — Fetch the city's ADU page for any additional requirements or handouts.
5. Submittal requirements — Fetch if corrections reference missing sheets, notes, or plan check items.

What to extract from each page:

WebFetch tips:

• Most municipal code platforms (ecode360, Municode, QCode) serve clean HTML that WebFetch handles well.
• Standard detail PDFs may not be readable via WebFetch — note the URL and title for the professional to download.
• If WebFetch returns empty or error for a URL, add it to extraction_gaps for Browser Fallback.

Extraction Output Format

{
  "city": "City name",
  "extraction_timestamp": "ISO date",
  "municipal_code": {
    "platform": "ecode360 | municode | qcode | etc.",
    "url": "https://...",
    "code_edition": "2022 | 2025 California Building Standards Code",
    "current_through": "Ordinance # or date if available",
    "building_code_title": "Title XX",
    "relevant_chapters": [
      {
        "chapter": "XX.XX",
        "title": "Chapter title",
        "url": "direct URL",
        "key_content": "Summary of relevant provisions"
      }
    ],
    "local_amendments": [
      {
        "section": "XX.XX.XXX",
        "amends": "CBC/CRC/CPC section reference",
        "description": "What it changes from state code",
        "applies_to_items": ["correction item numbers"]
      }
    ]
  },
  "standard_details": [
    {
      "name": "Detail name",
      "url": "PDF URL",
      "description": "What the detail shows",
      "applies_to_items": ["correction item numbers"]
    }
  ],
  "information_bulletins": [
    {
      "number": "IB-XXX",
      "title": "Title",
      "url": "URL",
      "key_requirements": "Summary of requirements",
      "applies_to_items": ["correction item numbers"]
    }
  ],
  "specific_findings": [
    {
      "topic": "What was researched",
      "finding": "What was found",
      "source": "URL or code section",
      "applies_to_items": ["correction item numbers"]
    }
  ],
  "extraction_gaps": [
    {
      "category": "What we tried to find",
      "url_attempted": "URL that failed or returned empty",
      "reason": "Why extraction failed (timeout, empty response, PDF not readable, etc.)",
      "fallback_suggestion": "What to try in Browser Fallback mode"
    }
  ]
}

Fan-out design: The extraction input is a list of URLs + topics. To parallelize, split this list:

• Agent 1: Municipal code URLs + code-related topics
• Agent 2: Standard detail and IB URLs
• Agent 3: ADU page + submittal requirements

Each agent produces a partial city_research_findings.json. The orchestrator merges them.

Mode 3: Browser Fallback

Tool: Chrome MCP (browser automation) Input: City name + extraction_gaps from Mode 2 Output: Gap-filling additions to city_research_findings.json Time: ~2-3 minutes When to use: Only when Mode 2 has extraction gaps that matter for the corrections

Process

For each gap in extraction_gaps:

1. Navigate to the city's website (start from the ADU page or main site)
2. Use browser automation to click through to the needed page
3. Read the content visually or via page text extraction
4. Extract the missing information

Common reasons for gaps and browser strategies:

Do NOT use Browser Fallback for:

• URLs that WebFetch handled successfully
• Topics where no gap exists
• General browsing "just to be thorough" — this mode is for filling specific gaps

Browser Fallback Output

Return the same structure as Mode 2's specific_findings array, to be merged into the existing research findings.

{
  "browser_findings": [
    {
      "topic": "What was searched",
      "finding": "What was found",
      "source": "URL visited",
      "applies_to_items": ["correction item numbers"],
      "filled_gap": "Which extraction_gap this addresses"
    }
  ],
  "remaining_gaps": [
    {
      "category": "What we still couldn't find",
      "attempted": "What browser actions were tried",
      "recommendation": "What the contractor should do (e.g., call the building department)"
    }
  ]
}

What to Search For

Seven categories of city-level information relevant to ADU projects:

Targeted Lookup Patterns

When researching items from a corrections letter, use targeted searches:

Important Notes

• This tool helps contractors comply, not litigate. If the city says to fix something, the contractor needs to know how to fix it. Focus on finding what the city requires and how to satisfy it.
• City websites change. URLs break. If a direct link fails, fall back to searching the city's main website.
• Check the date. Verify the municipal code version is current — look for "current through" or "last updated" on the code platform. Some cities lag behind on updating their ADU ordinances after state law changes.
• Standard details are gold. When a corrections letter says "See [City] Standard Detail" — finding that PDF on the city website is the single most useful thing to return. It tells the contractor exactly what the city wants to see drawn.
• Building vs. Planning split. Larger cities often split ADU information across two departments. The Planning department handles zoning and development standards. The Building department handles construction, permits, plan check, and inspections. Check both.

References

See references/municipal-code-platforms.md for a quick-reference of the major municipal code hosting platforms and search patterns.