Jean-Gabriel Gill-Couture
3d9db8746b
All checks were successful
Run Check Script / check (pull_request) Successful in 1m59s
71 lines
2.9 KiB
Markdown
71 lines
2.9 KiB
Markdown
---
|
|
name: code-derived-doc-review
|
|
description: Use when writing or reviewing architecture and design documentation to derive claims from code, map claims to tests, run an external review, and improve clarity and information density with the humanizer skill.
|
|
license: AGPL-3.0-only
|
|
compatibility: opencode
|
|
---
|
|
|
|
# Code-derived documentation review
|
|
|
|
Keep design documentation factual, concise, and difficult to drift away from
|
|
the codebase.
|
|
|
|
## Workflow
|
|
|
|
1. Read the complete document set before editing.
|
|
2. Identify the authoritative document for decisions, operational behavior,
|
|
wire contracts, and implementation details. Remove duplicate specifications.
|
|
3. Extract every architecturally significant claim: ownership, trust boundary,
|
|
ordering, state transition, failure policy, durability guarantee, limit, and
|
|
security constraint.
|
|
4. For each claim, locate:
|
|
- the implementation owner with file and symbol;
|
|
- the test that observes the behavior;
|
|
- the coverage level: direct, partial, or missing.
|
|
5. Treat an unsupported claim as a finding. Correct the prose, add a behavioral
|
|
test when the guarantee is required, or label the gap explicitly.
|
|
6. Ask an independent read-only reviewer to compare the finished documentation
|
|
with code and tests. Address findings, then request confirmation.
|
|
7. Load the `humanizer` skill. Remove repetition, inflated certainty, generic
|
|
conclusions, and AI-style transitions without removing facts or caveats.
|
|
8. Run a density pass: each fact has one authoritative home; diagrams summarize
|
|
and do not introduce unique guarantees; planning files point to maintained
|
|
documentation instead of restating it.
|
|
9. Validate links, documentation builds, diagram syntax, formatting, and stale
|
|
terminology.
|
|
|
|
## Claim table
|
|
|
|
Use this shape during review:
|
|
|
|
| Architectural claim | Documentation | Implementation owner | Validating test | Coverage |
|
|
|---|---|---|---|---|
|
|
|
|
Coverage means:
|
|
|
|
- **Direct:** the test observes the documented behavior at the owning boundary.
|
|
- **Partial:** the test covers a component or serialization detail but not the
|
|
full guarantee.
|
|
- **Missing:** no automated test proves the claim.
|
|
|
|
Do not count a compile check, helper-only test, or repeated production logic as
|
|
behavioral proof. Do not imply integration coverage when only a unit test exists.
|
|
|
|
## External review prompt
|
|
|
|
Ask the reviewer to report findings first with file and line references. Require
|
|
checks for factual drift, hidden failure cases, security overclaims, duplicate
|
|
authority, unsupported certainty, unclear ownership, and missing tests. The
|
|
reviewer must not edit the files.
|
|
|
|
## Completion standard
|
|
|
|
Documentation is complete when:
|
|
|
|
- each significant claim is traceable to code;
|
|
- each required guarantee has a direct test or an explicit coverage gap;
|
|
- one source owns each fact;
|
|
- external review findings are resolved;
|
|
- the prose passes the humanizer and density checks;
|
|
- documentation and diagram validation pass.
|