harmony/.opencode/skills/code-derived-doc-review/SKILL.md

name, description, license, compatibility

name	description	license	compatibility
code-derived-doc-review	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.	AGPL-3.0-only	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.