| name | doc |
| model | claude-opus-4-7 |
| description | Scan all documentation against source-of-truth files (config.py, board_config.h, routing.py, BOM, PCB) and report/fix outdated values. Use after PCB changes, GPIO remapping, BOM updates, or before releases. |
| disable-model-invocation | true |
| allowed-tools | Bash, Read, Edit, Grep, Glob, Agent |
Documentation Audit & Sync
Verify all documentation in website/docs/ is up-to-date with the actual codebase, then fix any discrepancies.
Critical Rules
- NEVER invent numbers — always read from source-of-truth files first
- Report ALL discrepancies before fixing anything
- Fix docs to match code, NEVER the reverse
Steps
0. Regenerate Schematics
The schematics are generated from scripts/generate_schematics/config.py (GPIO assignments, net names, component values). They must be regenerated before auditing docs so that the .kicad_sch files reflect the current config.
cd /Users/pierrejonnycau/Documents/WORKS/esp32-emu-turbo
python3 -m scripts.generate_schematics hardware/kicad
This regenerates all 7 schematic sheets from config.py. If any .kicad_sch file changed, it means the schematics were out of date — the docs likely are too.
1. Collect Source-of-Truth Values
Read these files to build the ground truth:
cd /Users/pierrejonnycau/Documents/WORKS/esp32-emu-turbo
| Data | Source File | What to Extract |
|---|
| GPIO pins | scripts/generate_schematics/config.py | GPIO_NETS dict (all 35 assignments) |
| Firmware pins | software/main/board_config.h | All #define GPIO numbers |
| Trace widths | scripts/generate_pcb/routing.py lines 32-36 | W_PWR, W_SIG, W_DATA, W_AUDIO |
| Board dims | scripts/generate_pcb/config.py | BOARD_W, BOARD_H |
| BOM | hardware/kicad/jlcpcb/bom.csv | Component count, refs |
| CPL | hardware/kicad/jlcpcb/cpl.csv | Placement count |
| DFM tests | python3 scripts/verify_dfm_v2.py 2>&1 | grep Results | Test count |
| DFA tests | python3 scripts/verify_dfa.py 2>&1 | grep Results | Test count |
| Collision grid | python3 -c "from scripts.generate_pcb.collision import _SUPPRESSIONS; print(len(_SUPPRESSIONS))" | Suppression count |
| Via count | grep -c '(via ' hardware/kicad/esp32-emu-turbo.kicad_pcb | Total vias |
| Via annular ring | scripts/verify_dfm_v2.py grep for ring threshold | Min ring value |
| Footprint count | grep -c '(footprint ' hardware/kicad/esp32-emu-turbo.kicad_pcb | Total footprints |
2. Audit Each Documentation File
Cross-reference extracted values against these docs:
2a. website/docs/schematics.md
- GPIO pin assignments (lines ~154-165)
- Component count references
- Net name list
2b. website/docs/components.md
- BOM table: component count, LCSC part numbers
- Cost estimates
- Compare against
hardware/kicad/jlcpcb/bom.csv
2c. website/docs/manufacturing.md
- DFM flagged component count
- Total component count
- DRC error count
- Board specs (layers, thickness)
2d. website/docs/verification.md
- DFM test count (was 64, check current)
- DFA test count (should be 9)
- Trace width table (should match routing.py)
- Via drill/pad/annular ring specs
- Connectivity test results (44/44 nets)
- Via counts per signal
2e. website/docs/pcb.md
- Board dimensions (160x75mm)
- Layer count (4)
- Trace width table (W_PWR, W_SIG, W_DATA, W_AUDIO)
- Via counts per net
- Footprint count
- Power net segment/via counts
- Collision/suppression references
2f. website/docs/software.md
- GPIO cross-verification table
- Pin assignments must match board_config.h
2g. website/docs/claude-agents.md
- Skills count per agent
- Test count references
3. Generate Report
Output a table:
## Documentation Audit Report
| File | Check | Status | Details |
|------|-------|--------|---------|
| schematics.md | GPIO pins | OK/OUTDATED | ... |
| components.md | BOM count | OK/OUTDATED | ... |
| ... | ... | ... | ... |
4. Fix Outdated Docs
For each OUTDATED entry:
- Show the old value and new value
- Edit the file using the Edit tool
- Mark as FIXED in the report
5. Final Verification
After fixes, re-run the audit to confirm all checks pass:
cd website && npm run build 2>&1 | tail -5
Key Files
Source of Truth
scripts/generate_schematics/ — Schematic generator (regenerate with python3 -m scripts.generate_schematics hardware/kicad)scripts/generate_schematics/config.py — GPIO assignmentssoftware/main/board_config.h — Firmware GPIO definesscripts/generate_pcb/routing.py — Trace widths, via sizesscripts/generate_pcb/config.py — Board dimensionsscripts/generate_pcb/collision.py — Collision suppressionshardware/kicad/jlcpcb/bom.csv — BOM componentshardware/kicad/jlcpcb/cpl.csv — CPL placementsscripts/verify_dfm_v2.py — DFM test definitionsscripts/verify_dfa.py — DFA test definitions
Documentation
website/docs/schematics.md — Electrical schematic docswebsite/docs/components.md — BOM with linkswebsite/docs/manufacturing.md — JLCPCB ordering guidewebsite/docs/verification.md — Pre-production checkswebsite/docs/pcb.md — PCB layout documentationwebsite/docs/software.md — Firmware architecturewebsite/docs/claude-agents.md — Agent/skill architecture
