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"
2. 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?"
3. 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:

  "${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:

  "${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

Critical extraction discipline:

• Record what IS there (citations found, requirements stated)
• Also record what is ABSENT that you would expect to find
• Do not interpret absence as compliance — absence is a potential gap
• Note edition years as specified — a correct requirement cited against the wrong edition is a potential gap

2c — Build the "Already Addressed" Inventory

Summarize Pass 1 into a flat inventory used for gap diffing in Phase 4. Write to .construction/skills/code-researcher/pass1_summary.yaml using the schema at: → ${CLAUDE_SKILL_DIR}/references/schemas.yaml § pass1_summary

Phase 3 — Code Research (Pass 2)

3a — Research Jurisdiction and Adopted Codes

Before researching requirements, establish which edition of each code is adopted by the jurisdiction. This is non-negotiable — code requirements vary significantly between editions.

Search for:

"{state} building code adopted edition {year}"
"{city} {state} local building code amendments"
"{state} IBC adoption effective date"
"{state} fire code adopted edition"
"{state} accessibility code requirements"

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

If jurisdiction code adoption cannot be confirmed via web search, mark as uncertain and note this prominently in the report. Do not assume the latest published edition is what's adopted.

3b — Research Requirements for Each Topic

For each topic in the confirmed research outline, research what the applicable codes require. Organize research by logical topic clusters, not fixed batch sizes.

For each topic, establish these three things:

1. What the code requires — the specific section, edition, and requirement language from the applicable code (IBC, ADA, NFPA, state code, etc.). Verify via web search; do not rely on paraphrases or training memory for exact language.
2. What referenced standards apply — codes reference downstream standards (ASTM, ANSI, UL, etc.) that contain the actual test methods and acceptance criteria.
3. What jurisdiction-specific overlays exist — state amendments, local amendments, and non-building-code authorities (health department, fire marshal, USDA/FDA for food service, etc.) that operate independently.

Use shared reference files at ${CLAUDE_PLUGIN_ROOT}/reference/ to verify specific numeric thresholds (clearances, load factors, occupant capacities) during research.

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

Adaptive scope expansion: If research reveals that a code requirement likely applies but may be addressed in a spec section or drawing not yet read in Pass 1, read that document before classifying the topic as a gap. Update the Pass 1 inventory with any new citations found. Note the additional documents read when reporting to the user at checkpoint 3c.

3c — USER CHECKPOINT: Interim Findings

After completing a cluster of related topics, report to the user. The example below shows the shape only: the [code] §[section] and [regulation] slots are placeholders, not citations. Fill them with the section numbers and requirement text you verified in Phase 3b, and never copy a value from this example into a finding.

Completed research on [topic 1], [topic 2], and [topic 3].

PRELIMINARY GAPS IDENTIFIED SO FAR
  ⚠  HIGH   Slip resistance — no COF requirement found in spec;
             [code] §[section] requires slip-resistant floors in [occupancy]
  ⚠  HIGH   Health department overlay — kitchen complex may be subject to
             [state] food service regulations [regulation]; not mentioned in scope
  ○  MEDIUM  VOC content — 09 67 23 does not cite VOC limits; Division 01
             may address this globally (will check)

NO GAP (already addressed in spec)
  ✓  Moisture testing — ASTM F 1869 and F 2170 both required (§3.1-B)
  ✓  Compressive strength — ASTM C 579 requirement at 7,700 psi (§2.1-D)
  ✓  Bond strength — ACI 503R at 400 psi (§2.1-D-10)

UNCERTAIN (couldn't confirm code language)
  ?  [Local jurisdiction] amendments to [code] §[section] — could not confirm
     if local amendments modify the slip resistance requirement

Continuing with [next batch]: [topic 4], [topic 5].
Do you want me to dig deeper on any of these before continuing, or shall I proceed?

Phase 4 — Gap Analysis (Pass 3)

4a — Diff Research Against Project Inventory

Compare every research finding from Phase 3 against the Pass 1 project inventory. Write to .construction/skills/code-researcher/gap_analysis.yaml using the schema at: → ${CLAUDE_SKILL_DIR}/references/schemas.yaml § gap_analysis

Classify each finding into one of: gaps (with severity + confidence), already_addressed, or uncertain.

4b — Classify Each Gap

Each gap gets a severity and confidence rating:

Severity:

• HIGH — a code requirement clearly applies, is not addressed in the project documents, and creates regulatory or safety risk if unresolved
• MEDIUM — a code requirement likely applies but may be addressed elsewhere (e.g., in a Division 01 section not yet reviewed) or its applicability depends on a condition that hasn't been confirmed
• LOW — a code reference that could be added for completeness but whose absence is unlikely to cause a compliance issue

Confidence:

• confirmed — the code requirement is definitively established (correct jurisdiction, correct edition, correct applicability) and the project document status is definitively established (read the full section)
• needs_review — the requirement likely applies but requires information not available in the current documents (AHJ confirmation, additional spec sections not provided, etc.)
• uncertain — conflicting sources, could not confirm jurisdiction's adopted code edition, or the code's applicability to this specific scope is genuinely ambiguous

4c — USER CHECKPOINT: Review Gaps Before Report

Before generating the report, present the gap summary. As in 3c, the bracketed code and regulation slots are placeholders; fill them from your verified findings, never from this example:

GAP ANALYSIS COMPLETE

HIGH-CONFIDENCE GAPS (take action)
  GAP-001 ⚠ HIGH    Slip resistance — no COF requirement in 09 67 23
                     [code] §[section] requires [threshold] in [occupancy]
                     Recommended action: add COF requirement and test method

  GAP-002 ⚠ HIGH    Health department — kitchen complex not addressed
                     [state] [regulation] may apply; needs AHJ confirmation
                     Recommended action: confirm with Owner whether food
                     service permit required

MEDIUM-CONFIDENCE GAPS (confirm and close)
  GAP-003 ○ MEDIUM   VOC content — 09 67 23 may need cross-ref to 01 61 16
                      Likely covered globally; confirm and add cross-reference

UNCERTAIN (need more information)
  ?  [Local jurisdiction] amendments to slip resistance — couldn't confirm locally

ALREADY ADDRESSED (no action needed)
  ✓  Moisture vapor emission testing — well covered, both test methods
  ✓  Substrate preparation — shot-blast, priming, patching all specified
  ✓  Compressive strength — ASTM C 579 at 7,700 psi
  ✓  Bond strength — ACI 503R at 400 psi
  ✓  Installer qualification — manufacturer written cert required

Before I write the report:
  • Are any of these gaps ones you were already aware of and have addressed
    outside the documents I reviewed?
  • Should I research any topic further before finalizing?
  • Any gaps you want to remove from the report?

Phase 5 — Report

5a — Generate Gap Report

Write the report where the user can see it — the project root as Code_Research_Report_{scope}_{date}.md, never inside .construction/ — using the template at: → ${CLAUDE_SKILL_DIR}/references/gap_report_template.md

Populate all placeholder fields from the gap_analysis.yaml and jurisdiction.yaml data. The report must include: applicable codes table, all gaps (action required + confirm and close), uncertain items, already addressed items, documents reviewed, and the disclaimer.

5b — Write a Finding

Record the analysis in .construction/skills/code-researcher/findings/ (both modes):

"${CLAUDE_PLUGIN_ROOT}/bin/construction-python" \
  "${CLAUDE_PLUGIN_ROOT}/scripts/graph/write_finding.py" \
  --skill "code-researcher" --type "code_gap_analysis" \
  --title "Code gap analysis: {scope} — {n_gaps} gaps identified" \
  --data '{
    "scope": "[spec sections or topic]",
    "topics_researched": 0,
    "already_addressed": 0,
    "gaps_high": 0,
    "gaps_medium": 0,
    "gaps_low": 0,
    "uncertain": 0,
    "jurisdiction_confirmed": true
  }'

Resumption

Check for .construction/skills/code-researcher/ before starting:

Discipline Notes

PE discipline guidance for jurisdiction research, scope boundaries, regulatory overlays, and confidence levels: → ${CLAUDE_SKILL_DIR}/references/discipline_notes.md

File Safety

Never overwrite an existing gap report. Version output files (_v2, _v3) if a prior version exists at the target path.

Allowed Scripts

• ${CLAUDE_PLUGIN_ROOT}/bin/construction-python
• ${CLAUDE_PLUGIN_ROOT}/scripts/pdf/pdf_text.py — flat-file mode: spec section and sheet text, with a TEXT/VISION verdict per page (Phase 2a). In AgentCM mode, only on a read manual's pages in no section (--pages), never on a section's pages or a drawing
• ${CLAUDE_PLUGIN_ROOT}/scripts/pdf/rasterize_page.py and ${CLAUDE_PLUGIN_ROOT}/scripts/pdf/crop_region.py — flat-file mode: page images for vision, into .construction/skills/code-researcher/pages/ (Phase 2a). In AgentCM mode, only a read manual's page in no section; drawings go through crop.sh
• ${CLAUDE_PLUGIN_ROOT}/scripts/graph/write_finding.py
• ${CLAUDE_PLUGIN_ROOT}/scripts/corrections_append.py — AgentCM mode: record a correction of AgentCM's data (reference/agentcm-mode.md)
• ${CLAUDE_PLUGIN_ROOT}/scripts/issue_manager.py — log a code gap the design team must answer to the Issue Registry (command and severity mapping in construction-guide)