agentleFS
mikeOnBreezemikeOnBreeze/cc-crossbeam/.claude/skills/demo-contractor-corrections/SKILL.md

demo-contractor-corrections

Skill297 starsChanged 9 months agoMITView on GitHub

Local demo: Contractor corrections analysis and response — two-phase flow with a human-in-the-loop pause. Phase 1 reads the corrections letter, researches codes, views plan sheets, and generates questions for the contractor. The agent STOPS and presents questions to the user. After the user provides answers, Phase 2 generates the full response package (response letter, professional scope, corrections report, sheet annotations). Triggers on: 'Analyze these corrections' or 'Run the contractor flow on [path]'.

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. About 0 are common, 13 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈13

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the contractor-side corrections analysis and response locally.

    line 8
  2. Distinctive:

    If PNG files: use directly with vision

    line 27
  3. Distinctive:

    If a directory: find all PNGs in it, sort by name, read each as a page

    line 28
  4. Distinctive:

    If PDF: extract to PNGs first (same as plan binder extraction below)

    line 29
  5. Very specific:

    If a directory of PNGs: use directly.

    line 32
  6. Very specific:

    If a PDF: extract with pdftoppm -png -r 200 "<input.pdf>" "<output-dir>/pages-png/page"

    line 33
  7. Very specific:

    Create demo-output/contractor-<city>-<timestamp>/ in the workspace root.

    line 37
  8. Distinctive:

    Read the corrections letter pages visually.

    line 45
  9. Very specific:

    Write corrections_parsed.json to output directory.

    line 55
  10. Distinctive:

    Run concurrently with Step 1.1.

    line 59
  11. Very specific:

    Follow the adu-targeted-page-viewer skill workflow:

    line 61
  12. Distinctive:

    Read page 1 (cover sheet) visually for the sheet index

    line 62
  13. Distinctive:

    After Steps 1.1 and 1.2 complete, launch three concurrent subagents:

    line 68
  14. Distinctive:

    Look up every code section cited in the corrections (CRC, CBC, ASCE, CPC, B&P Code)

    line 72
  15. Distinctive:

    Write findings (will be merged in Step 1.4)

    line 74
  16. Very specific:

    Check if adu-skill-development/skill/<city-slug>-adu/ exists

    line 77
  17. Very specific:

    If no: Run adu-city-research — WebSearch for URLs, then WebFetch to extract content

    line 79
  18. Very specific:

    Write contractor_answers.json to the output directory (even if loaded from mock).

    line 171
  19. Distinctive:

    Read all Phase 1 outputs from the output directory:

    line 175
  20. Very specific:

    Follow the adu-corrections-complete skill specification.

    line 183
  21. Distinctive:

    Every annotation references a valid sheet from the manifest

    line 205
  22. Distinctive:

    After generating all deliverables, present to the user:

    line 211

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Demo: Contractor Corrections Flow

Run the contractor-side corrections analysis and response locally. You are helping a contractor understand and respond to a city corrections letter on their ADU permit.

This is a two-phase flow with a pause in the middle. Phase 1 produces questions. You STOP and present them. The user answers. Then Phase 2 generates deliverables.

How to Invoke

The user provides:

  1. Corrections letter — PNG images or a PDF of the corrections letter (typically 1-3 pages)
  2. Plan binder — either a PDF path or a directory of pre-extracted PNGs
  3. (Optional) City name and project address — auto-detected from the corrections letter if not provided

Example invocations:

  • "Analyze these corrections for my Placentia ADU project. Corrections: test-assets/corrections/. Plans: test-assets/01-extract-test/pages-png/"
  • "Run the contractor flow. Corrections letter: path/to/corrections-p1.png and path/to/corrections-p2.png. Plan binder: path/to/plans.pdf"
  • "I got corrections back from the city. Here they are: [paths]"

Input Resolution

Corrections letter:

  • If PNG files: use directly with vision
  • If a directory: find all PNGs in it, sort by name, read each as a page
  • If PDF: extract to PNGs first (same as plan binder extraction below)

Plan binder:

  • If a directory of PNGs: use directly. Check for pre-existing sheet-manifest.json and title-blocks/.
  • If a PDF: extract with pdftoppm -png -r 200 "<input.pdf>" "<output-dir>/pages-png/page"

Output Directory

Create demo-output/contractor-<city>-<timestamp>/ in the workspace root. All output files go here.


PHASE 1: Analysis

Step 1.1: Parse Corrections Letter (~30 sec)

Read the corrections letter pages visually. Extract:

  • Project info: address, city, jurisdiction number, job description, date, reviewer name
  • Each correction item as a structured object:
    • Item number (preserve original numbering, including sub-items like 3a, 3b, 3c)
    • Original text (exact wording)
    • Code references (CRC, CBC, ASCE, CPC, B&P Code, municipal code)
    • Plan sheet references (Sheet A1, Detail 2/A3, etc.)
    • Review round (1st review outstanding vs. 2nd review new)
    • Bold/emphasis flags

Write corrections_parsed.json to output directory.

Step 1.2: Build Sheet Manifest (~30-90 sec)

Run concurrently with Step 1.1.

Follow the adu-targeted-page-viewer skill workflow:

  1. Read page 1 (cover sheet) visually for the sheet index
  2. Match sheet IDs to page numbers (title block reading if count mismatch)
  3. Write sheet-manifest.json

Step 1.3: Parallel Research (~60-90 sec)

After Steps 1.1 and 1.2 complete, launch three concurrent subagents:

Subagent A — State Law Researcher:

  • Load adu-skill-development/skill/california-adu/references/
  • Look up every code section cited in the corrections (CRC, CBC, ASCE, CPC, B&P Code)
  • For each: what does the code require? What are the thresholds? ADU exceptions?
  • Write findings (will be merged in Step 1.4)

Subagent B — City Research:

  • Check if adu-skill-development/skill/<city-slug>-adu/ exists
    • If yes: Load city skill references (offline, fast)
    • If no: Run adu-city-research — WebSearch for URLs, then WebFetch to extract content
  • Focus on: municipal code amendments, standard details referenced in corrections, Information Bulletins
  • Write findings (will be merged in Step 1.4)

Subagent C — Sheet Viewer:

  • Using the sheet manifest, read only the plan sheets referenced by correction items
  • For each referenced sheet, describe what is currently drawn in the area relevant to the correction
  • Write sheet_observations.json

Step 1.4: Categorize + Generate Questions (~2 min)

Merge all research and categorize each correction item:

CategoryMeaning
AUTO_FIXABLEDrafter fixes: labels, notes, formatting, checklists
NEEDS_CONTRACTOR_INPUTRequires specific facts from the contractor (pipe sizes, elevations, materials)
NEEDS_PROFESSIONALRequires licensed professional work (structural calcs, fire-rated details, stamps)

For each item, document:

  • Category assignment with justification
  • Research context (what the code requires, what the city adds)
  • What's currently on the plan (from sheet observations)
  • What needs to change

Write corrections_categorized.json.

For NEEDS_CONTRACTOR_INPUT items, generate specific questions:

  • Each question includes research_context explaining why it's being asked
  • Question types: choice, text, number, measurement, multi_choice
  • Questions are informed by the code research — they ask for specific data, not vague descriptions

Write contractor_questions.json.

Also write state_law_findings.json (from Subagent A) and any city research files.


⛔ STOP HERE — Present Questions to the User

After Phase 1 completes, you MUST stop and wait for the user.

Present the results in this format:


Phase 1 Complete — Corrections Analysis

Project: [address], [city] — [permit number] Corrections: [N] items parsed from [review round] Breakdown: [X] auto-fixable, [Y] need your input, [Z] need professional work

Questions for You

For each question group (organized by correction item):

Item [#] — [summary] [research context — why this matters, what the code says]

  1. [question text]
    • Options: [if choice type]
  2. [question text] ...

Auto-Fixable Items (no input needed)

  • Item [#]: [summary] — [what will be done]
  • ...

Professional Items (scoped for your design team)

  • Item [#]: [summary] — needs [professional role]
  • ...

Answer the questions above and I'll generate your response package.

You can also say:

  • "Use the mock answers" (loads test-assets/mock-session/contractor_answers.json)
  • "Skip the questions, just generate with what you have" (Phase 2 runs with TODO placeholders)

Wait for the user's response before proceeding to Phase 2.


PHASE 2: Generate Response Package

Triggered when the user provides answers. Three ways this happens:

  1. User answers inline — Parse their answers from the conversation. Map to question IDs.
  2. User says "use mock answers" — Load test-assets/mock-session/contractor_answers.json
  3. User says "skip" or "generate with what you have" — Proceed with empty answers; TODO placeholders in outputs.

Write contractor_answers.json to the output directory (even if loaded from mock).

Step 2.1: Load Phase 1 Context

Read all Phase 1 outputs from the output directory:

  1. corrections_categorized.json — the backbone, read first
  2. contractor_answers.json — map answers to items
  3. sheet-manifest.json — for sheet references
  4. corrections_parsed.json — for original wording

Step 2.2: Generate Four Deliverables

Follow the adu-corrections-complete skill specification. Generate all four:

1. response_letter.md — Professional letter to the building department

  • Address EVERY item, even procedural ones
  • Preserve original correction wording
  • Incorporate contractor answers with code justification
  • Reference specific sheets from manifest
  • End with a sheet revisions summary table

2. professional_scope.md — Work breakdown by professional

  • Group by role: Designer, Structural Engineer, HERS Rater
  • Include Key Specifications section with contractor-provided details
  • Ready-to-use notes for the design team (DFU justification, grade table, dimensions)
  • Status per item: READY, PENDING, FINAL STEP

3. corrections_report.md — Status dashboard / checklist

  • Summary table by category
  • Key findings from contractor answers (capacity conclusions, drainage assessment)
  • Action items checklist with checkboxes
  • Critical path (what blocks what, what can run in parallel)

4. sheet_annotations.json — Per-sheet markup instructions

  • Every annotation references a valid sheet from the manifest
  • Revision notes ready for a revision table
  • Specifications from contractor answers mapped to sheet locations

Step 2.3: Present Results

After generating all deliverables, present to the user:

  • Summary: what was generated, where files are saved
  • The full response_letter.md content (this is the main deliverable they care about)
  • Highlights from the professional scope (who needs to do what)
  • Link to the corrections report for the full status view

Test Data

Ready-to-use test data for the Placentia demo project:

AssetPath
Corrections letter (2 pages)test-assets/corrections/1232-n-jefferson-corrections-p1.png and p2.png
Plan pages (15 PNGs)test-assets/01-extract-test/pages-png/
Mock session datatest-assets/mock-session/ (all Phase 1 outputs pre-built)
Mock contractor answerstest-assets/mock-session/contractor_answers.json
Real agent output (comparison)test-assets/correction-01/

Quick demo path (skips Phase 1, tests Phase 2 only):

  • "Generate the response package using the mock session data at test-assets/mock-session/"
  • This loads pre-built Phase 1 artifacts + mock answers and jumps straight to Phase 2 deliverables.

Sub-Skills Referenced

SkillLocationRole
adu-targeted-page-vieweradu-skill-development/skill/adu-targeted-page-viewer/PDF extraction + sheet manifest
california-aduadu-skill-development/skill/california-adu/State law (28 reference files)
adu-city-research.claude/skills/adu-city-research/Web research for non-onboarded cities
adu-corrections-completeadu-skill-development/skill/adu-corrections-complete/Phase 2 output spec
placentia-aduadu-skill-development/skill/placentia-adu/Placentia-specific rules
buena-park-aduadu-skill-development/skill/buena-park-adu/Buena Park-specific rules

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.