Skill.md
Harness Step 2 — Fill docs/ with Real Content
After Step 1 creates the docs/ skeleton, the most common outcome is a set of files with placeholder text. An agent reading "naming conventions: see code" gets nothing useful. This skill fixes the gap — it reads the actual codebase deeply and writes specific, accurate documentation backed by real code examples.
What Gets Filled In
| File | Content written |
|---|---|
docs/ARCHITECTURE.md | Module responsibilities, dependency direction rules (with reasons), main data flows |
docs/CONVENTIONS.md | File naming patterns (with real examples), variable/function naming rules |
docs/TECH_DECISIONS.md | Rationale for each major framework/library (inferred where possible; flagged where not) |
docs/QUALITY.md | Project-specific Definition of Done, code review checklist |
docs/exec-plans/tech-debt-tracker.md | Duplicate code, naming inconsistencies, TODO comments found during scan |
Core Principle
Inferred content is labeled as inferred. Unknown content is marked "TODO: confirm." Nothing is fabricated to fill space.
After the scan, the skill produces a "TODO: confirm" list — typically 3–5 items per project, concentrated around historical tech decisions (the code shows the choice, not why it was made) and runtime metrics (which can't be read from files).
Supported Use Cases
- Immediately after Step 1, to fill skeleton with real content
- After a major refactor, to resync docs with current code
- Taking over an unfamiliar codebase and generating architecture docs for it
How to Use
- Confirm the project has
AGENTS.mdanddocs/directory (from Step 1) - Say "fill in the docs" or "write ARCHITECTURE.md" or "analyze codebase and write docs"
- The skill reads entry files, module boundaries, dependency declarations, naming patterns
- All docs/ files are written; "TODO: confirm" list is surfaced
- You confirm or fill in only what the skill couldn't infer
Limitations
The skill reads files — it doesn't access git history or team communication. Historical decision rationale ("why did we choose X?") typically needs human input. Runtime behavior (actual query performance, API response shapes) can't be inferred from source files.