/code-researcher

name: code-researcher
description: >
  Scope-specific code gap analysis — extracts referenced codes from project
  docs, researches what should apply, surfaces the delta. Triggers: 'code
  research', 'what codes apply', 'code check', 'ADA requirements', 'egress'.
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_SKILL_DIR}/../../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 graph entry

**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/` exists):**

• `.construction/project.yaml` — location, occupancy, construction type
• `.construction/index/sheet_index.yaml` — drawing set composition
• Database (read `query_command` from `.construction/database.yaml`):
• `{query_command} -c "SELECT * FROM v_room_profile WHERE room_number = '...'"` — rooms with schedule data
• `{query_command} -c "SELECT * FROM v_sheet_contents WHERE sheet_number = '...'"` — elements on sheets
• Orientation: `{query_command} -c "SELECT COUNT(*) FROM sheets WHERE project_id = '...'; SELECT COUNT(*) FROM rooms WHERE project_id = '...'"`

**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/code_research/project_context.yaml` using the schema at: → `${CLAUDE_SKILL_DIR}/references/schemas.yaml` § project_context

If any required field cannot be found in the documents, ask the user before proceeding. Do not assume occupancy group or construction type — these determine which code provisions apply and an incorrect assumption cascades through the entire analysis.

1b — Define the Research Scope

Parse the user's question to identify:

1. **Target scope** — which spec sections, drawing sheets, systems, or elements the engineer wants checked. Examples:

• A spec section: "Section 09 67 23 Resinous Flooring"
• A system: "all egress paths from the kitchen complex"
• A trade package: "mechanical