/code-researcher

name: code-researcher
description: >
  Researches which building codes, accessibility standards and authority
  requirements (health department, fire marshal, state agency) apply to a
  scope or spec section, and which the project documents miss. Use for 'what
  codes apply', 'code check', 'ADA requirements', 'egress', 'health
  department'. Not for reading what the drawings or specs say
  (construction-guide).
argument-hint: "<scope_or_question> e.g. 'Section 09 67 23 resinous flooring' or 'egress from the kitchen complex'"

Code Researcher — Scope-Specific Gap Analysis

What This Skill Does

An engineer managing one or more scopes asks: *"Are there any code requirements for this scope that I'm missing?"*

This skill answers that question in three passes:

**Pass 1 — What the scope already addresses** Read the actual project documents — spec sections, drawings, schedules — and extract every code citation, standard reference, and requirement already incorporated by the design team.

**Pass 2 — What should apply** Research all codes and standards that apply to this type of work in this jurisdiction, regardless of what the project documents say.

**Pass 3 — The gap** Diff Pass 1 against Pass 2. Present only what's in Pass 2 but absent from Pass 1, with confidence levels and specific source citations from both the code and the project documents.

**This is a gap finder, not a code summary.** If the spec already addresses a requirement correctly, it does not appear in the output. The engineer's time is spent only on things that may actually be missing.

---

Framing Rule (Non-Negotiable)

Every finding is framed as: > *"Code [X] requires [Y]. The project documents [address this at / do not > appear to address this]. Confidence: [level]. Recommended action: [action]."*

Never frame findings as COMPLIANT / NON-COMPLIANT. The licensed design professional makes compliance determinations. This skill provides research.

---

Research Philosophy

This skill uses a document-grounded research approach:

• **Construction documents are ground truth.** Every claim about what the project does or does not address must trace to a specific document read in Pass 1. Never infer project status from memory or assumption.
• **Claude's domain knowledge drives topic discovery.** Use your training knowledge of construction codes, standards, and regulatory frameworks to identify what requirements SHOULD apply to this scope. The documents tell you what IS addressed; your knowledge tells you what to check for.
• **Web research confirms jurisdiction-specific requirements.** Building codes vary by jurisdiction and edition. Use web search to confirm which edition is adopted, retrieve exact code language, and discover jurisdiction-specific overlays. Do not rely on training knowledge alone for specific code section numbers or thresholds — verify via web.
• **Reference files verify numeric thresholds.** Shared reference files at `${CLAUDE_PLUGIN_ROOT}/reference/` contain structured ADA and IBC data useful for quick verification of specific dimensions and capacities during research.

---

Workflow Overview

Phase 1 — Context and Scope Definition
  1a  Gather project context (jurisdiction, occupancy, construction type)
  1b  Define the research scope (which spec sections, which question)
  1c  USER CHECKPOINT — confirm scope before any research begins

Phase 2 — Project Document Extraction (Pass 1)
  2a  Read all project documents in scope
  2b  Extract every code citation, standard reference, requirement
  2c  Build the "already addressed" inventory

Phase 3 — Code Research (Pass 2)
  3a  Research jurisdiction and adopted code editions
  3b  Research applicable requirements for this scope and work type
  3c  USER CHECKPOINT — interim findings, confirm continuation

Phase 4 — Gap Analysis (Pass 3)
  4a  Diff research findings against project document inventory
  4b  Classify each gap by severity and confidence
  4c  USER CHECKPOINT — review gaps before report is written

Phase 5 — Report
  5a  Generate structured gap report
  5b  Write a finding

**Human checkpoints at 1c, 3c, and 4c.** Do not skip them.

---

Phase 1 — Context and Scope Definition

1a — Gather Project Context

Collect minimum required project parameters. Check in this order:

**AgentCM project files (if `.construction/project.yaml` exists):** follow `${CLAUDE_PLUGIN_ROOT}/reference/agentcm-mode.md` (which source wins, missing files, which file answers what, drawings through `crop.sh`, corrections of AgentCM's data).

• `.construction/project.yaml` — location, occupancy, construction type
• `.construction/index/sheet_index.yaml` — drawing set composition
• `.construction/specs/<section>.txt` — each spec section's text (`01 10 00` is `01-10-00.txt`), listed in `.construction/INDEX.md`; only for a manual INDEX.md lists under "Spec manuals not read", spec-splitter's `.construction/skills/spec_text/`
• `.construction/INDEX.md` — orientation: how many sheets and specification sections there are, and how many rooms are known (its headings, found by name)
• `.construction/tags.tsv` — each room by number, with every sheet it occurs on (`kind` room); INDEX.md says when its room list is incomplete
• `.construction/schedules/<sheet>-<n>.tsv` — a room's finishes, a door's size or rating: the schedules INDEX.md lists under Schedules and legends
• `.construction/sheets/<sheet>.tsv` — the text on a sheet, each line with its position and view

**Project documents (read directly):**

• Architectural title block — project name, location, jurisdiction
• Spec Section 01 10 00 (Summary of Work) — occupancy, construction type,

project description

• Spec Section 01 40 00 (Quality Requirements) — codes the design team has

already identified as applicable

• Spec Section 01 35 13 or 01 35 14 — special project requirements, authority

having jurisdiction contacts

Minimum required context — write to `.construction/skills/code-researcher/project_co