kidoc — Engineering Documentation Skill

1. Generate scaffold — kidoc_scaffold.py auto-runs all available analyses, renders schematics, generates diagrams, and writes the markdown scaffold.
2. Fill narratives — The agent reads the scaffold and writes engineering prose for each <!-- NARRATIVE: section_name --> placeholder. The engineer reviews and edits.
3. Regenerate — On re-run, data sections between <!-- GENERATED: section_id --> markers update from fresh analysis; user-written narrative content is preserved.
4. Render output — kidoc_generate.py produces PDF, HTML, DOCX, or ODT.

Document Types

Custom Reports

Use --spec to generate reports with arbitrary section ordering:

python3 skills/kidoc/scripts/kidoc_scaffold.py \
  --project-dir . --spec my-report.json --output reports/custom.md

Spec format (JSON):

{
  "type": "custom",
  "title": "USB Interface Analysis",
  "sections": [
    {"id": "front_matter", "type": "front_matter"},
    {"id": "signal_interfaces", "type": "signal_interfaces"},
    {"id": "bom", "type": "bom_summary"}
  ]
}

Each section's type must match a known section type (same names used in the document types table above). The id field is a unique key for that section instance.

To see the full default spec for any built-in type:

python3 skills/kidoc/scripts/kidoc_spec.py --expand hdd
python3 skills/kidoc/scripts/kidoc_spec.py --list

The --spec flag also works with kidoc_generate.py (uses the spec title as fallback project name).

Schematic and PCB Rendering

Rendering is integrated into the figure generation engine. The orchestrator and scaffold automatically render schematics and PCB views as part of document generation:

# Generate all figures (diagrams + schematic/PCB renders) from analysis JSON
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --output reports/figures/

# Full orchestration with spec, analysis, and project files
python3 skills/kidoc/scripts/kidoc_orchestrator.py --analysis schematic.json \
    --project-dir . --output reports/figures/

The figure generators support: full-sheet rendering (root + all sub-sheets), subsystem cropping (focus_refs in spec sections), net highlighting, pin-level net annotation, and all PCB layer presets. These options are configured in the document spec or passed through the analysis dict.

Rendering features available through the generator framework:

• Crop: Focus on a subsystem bounding box around specific component refs
• Focus/dim: Show focused components at full opacity, dim the rest to 15%
• Highlight nets: Color-trace specific nets via BFS
• Pin nets: Annotate pin-level net names at pin tips

For direct programmatic access, use figures.renderers:

from figures.renderers import render_schematic, render_pcb
render_schematic('design.kicad_sch', 'output/', crop_refs=['R1', 'R2'], highlight_nets=['VCC'])
render_pcb('board.kicad_pcb', 'output/', preset_name='assembly-front')

Layer presets:

Additional options: --highlight-nets, --crop-refs, --crop x,y,w,h, --mirror, --overlay annotations.json (callout boxes with leader lines).

Block Diagrams

python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --all --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --power-tree --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --bus-topology --output diagrams/
python3 skills/kidoc/scripts/kidoc_diagrams.py --analysis schematic.json --architecture --output diagrams/

Generated from schematic analysis JSON. Power trees show regulator topology with inductor values, capacitor summaries, and output voltages.

Output Formats

PDF output includes a styled cover page, table of contents, formatted tables with alternating rows, and vector SVG diagrams.

Configuration

Report settings live in .kicad-happy.json under the "reports" key. Config files cascade: ~/.kicad-happy.json (user-level defaults, e.g. company branding) merges with project-level config.

{
  "project": {
    "name": "Widget Board",
    "number": "HW-2024-042",
    "revision": "1.2",
    "company": "Acme Electronics",
    "author": "Jane Smith",
    "market": "eu"
  },
  "reports": {
    "classification": "Company Confidential",
    "documents": [
      {"type": "hdd", "output": "HDD-{project}-{rev}", "formats": ["pdf", "docx"]}
    ],
    "branding": {
      "logo": "templates/logo.png",
      "header_left": "{company}",
      "header_right": "{number} Rev {rev}"
    }
  }
}

Writing Narratives

After generating a scaffold, fill the narrative placeholder sections with engineering prose.

Workflow

1. Run the context builder to get focused data for each section:

   python3 skills/kidoc/scripts/kidoc_narrative.py \
     --analysis analysis/schematic.json \
     --section power_design
   

   Or build contexts for all narrative sections at once:

   python3 skills/kidoc/scripts/kidoc_narrative.py \
     --analysis analysis/schematic.json \
     --report reports/HDD.md
   

2. For each section, read the context and write prose that:

   • Explains why, not just what — engineering rationale, tradeoffs
   • References specific component values and part numbers
   • Uses quantitative language ("2.3ms hold-up time" not "adequate capacitance")
   • Flags deviations from datasheet recommendations
   • References SPICE validation results when available

3. Replace the italic placeholder *[...]* in the markdown with real prose.

4. On regeneration, data tables update automatically. Review narratives for consistency with any changed data.

Style Guide

Write as a senior EE explaining to a peer:

• Lead with the key finding or decision
• Support with specific numbers from the analysis
• Note any risks or deviations
• Keep paragraphs to 3-5 sentences
• Don't repeat data that's already in tables

Requirements

• Python 3.9+ with python3-venv (for PDF/DOCX/ODT generation)
• KiCad schematic file (.kicad_sch, KiCad 6+) — for SVG rendering
• Optional: Analysis JSONs are auto-generated from .kicad_sch/.kicad_pcb; pre-generated JSONs in analysis/ (or the path configured in .kicad-happy.json) are used if present. Generated figures (diagrams, schematic SVGs) are placed in reports/figures/ for git tracking

Limitations

• Schematic and PCB renderers support KiCad 6+ formats only (.kicad_sch, .kicad_pcb)
• Narrative sections require the agent or manual authoring — the scaffold provides structure and data, not prose
• SPICE simulation results require manual simulation setup (not auto-run by scaffold)
• PDF vector SVG embedding uses svglib when available; falls back to raster if svglib cannot parse a particular SVG

Related Skills

Run the kicad skill's analyzers first, then emc and spice if available. The scaffold auto-runs kicad and emc analyses when source files are present, so manual pre-analysis is only needed for SPICE.