dleerdefi/claude-code-construction/code-researcher

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_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 scope, Sections 23 00 00 through 23 80 00"
• A code topic: "accessibility requirements for the toilet rooms"

1. Research question — what specifically the engineer is worried about.

Examples:

• "Am I missing any code requirements?"
• "Does the spec cover the slip resistance requirements?"
• "Are there fire separation requirements I haven't addressed?"

1. Scopes in scope — if the engineer is managing multiple scopes (e.g.,

scopes A through C), confirm which ones this research covers.

Write to .construction/skills/code-researcher/scope_definition.yaml using the schema at: → ${CLAUDE_SKILL_DIR}/references/schemas.yaml § scope_definition

Research topics are generated from the combination of:

• The work type (resinous flooring → surface profile requirements, slip

resistance, chemical resistance, substrate preparation)

• The occupancy group (kitchen/food service → USDA/FDA/health department overlay)
• The project type (renovation → existing conditions, special inspections)
• The question framing (gap analysis → broader research than targeted check)

Use your full domain knowledge to identify research topics. You know what code requirements typically apply to each type of construction work, which regulatory authorities have jurisdiction, and what gaps commonly appear in specifications. The project documents tell you what the engineer has already addressed — your job is to identify everything they should have considered.

1c — USER CHECKPOINT: Confirm Scope

Present to the user:

I have enough context to start. Before I begin research, here's what I'm planning:
 
PROJECT
  Name:          [project_name]
  Location:      [city, state]
  Occupancy:     [group]
  Type:          [construction type]
  Sprinklered:   [yes/no/unknown]
  Code year:     [inferred from drawing date]
 
SCOPE I'LL RESEARCH
  Spec sections: [list]
  Sheets:        [list, or "none specified — I'll search for relevant sheets"]
  Your question: [restated in plain language]
 
RESEARCH TOPICS I'VE IDENTIFIED
  1. [topic] — because [reason derived from scope]
  2. [topic] — because [reason derived from scope]
  3. [topic] — because [reason derived from scope]
  [...]
 
TOPICS I'M NOT INCLUDING (and why)
  • [topic] — not applicable to this occupancy/type
  • [topic] — already confirmed complete by Spec 01 40 00
 
Before I spend time researching, please confirm:
  • Is the project context correct?
  • Should I add or remove any research topics?
  • Are there specific code concerns you already have that I should prioritize?

Do not begin Phase 2 until the user responds.

Phase 2 — Project Document Extraction (Pass 1)

This phase reads what the project documents already say. It runs before web research so the gap analysis has a firm baseline.

2a — Read All In-Scope Documents

For each spec section in scope:

• Read the full section (all parts — General, Products, Execution)
• In AgentCM mode, read .construction/specs/<section>.txt (Phase 1a): it is the section's text, and a section's pages are never extracted again. A section whose text looks incomplete (a part missing, a "B." with no "A.") is reported as incomplete, citing the manual and page its lines give. A read manual's pages in no section (a table of contents, a cover: INDEX.md lists them under "Spec manuals read") are read in the PDF, those pages only: pdf_text.py --pages <n> or rasterize_page.py on that page. A manual INDEX.md lists under "Spec manuals not read" is spec-splitter's: read its sections from .construction/skills/spec_text/.
• In flat-file mode, dump the section's text layer; pages it marks VISION are scanned or image-heavy: rasterize them and read them with vision:

``bash "${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_PLUGIN_ROOT}/scripts/pdf/pdf_text.py" "{section.pdf}" "${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_PLUGIN_ROOT}/scripts/pdf/rasterize_page.py" "{section.pdf}" {page} --dpi 200 --output ".construction/skills/code-researcher/pages/{section}_p{page}.png" ``

For drawing sheets:

• Read title block, notes, schedules, and details relevant to the scope
• In AgentCM mode, search the sheet's text in .construction/sheets/ and look at a box with crop.sh (reference/agentcm-mode.md). Otherwise rasterize the sheet ({page} is 1-based; a split sheet PDF has one page) and read it with vision; a schedule with a text layer can be read from pdf_text.py's dump, and a region cropped with crop_region.py:

``bash "${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_PLUGIN_ROOT}/scripts/pdf/rasterize_page.py" "{sheet.pdf}" {page} --dpi 200 --output ".construction/skills/code-researcher/pages/{sheet}.png" "${CLAUDE_PLUGIN_ROOT}/bin/construction-python" "${CLAUDE_PLUGIN_ROOT}/scripts/pdf/crop_region.py" ".construction/skills/code-researcher/pages/{sheet}.png" --box {x1},{y1},{x2},{y2} --normalized --output ".construction/skills/code-researcher/pages/{sheet}_detail.png" ``

• Page images and text dumps are working data: keep them in .construction/skills/code-researcher/pages/, never elsewhere under .construction/ and never in /tmp. Do not write your own extraction code (no python -c, no helper script): these scripts are the reading toolkit for this skill.

For referenced standards within spec sections:

• Note every standard cited (ASTM, ANSI, NFPA, UL, SMACNA, etc.) with its

edition year as cited in the spec

2b — Extract All Code and Standard Citations

For each document read, extract every code reference, standard citation, and requirement into a structured inventory. Write to .construction/skills/code-researcher/pass1_project_inventory.yaml using the schema at: → ${CLAUDE_SKILL_DIR}/references/schemas.yaml § pass1_project_inventory