canonical Completeness evaluation
Hard technique for evaluating whether documentation sections have substantive content. Refer to @{AGENT_FOLDER}/dockit/references/sections.md for the full list of sections and their requirements.
How to evaluate completeness
Step 1: Read the structure document
Read .planning/docs/{doc-name}/structure.md to know what sections the user chose. Only evaluate the sections in .planning/docs/{doc-name}/structure.md, not a theoretical maximum.
Step 2: Map sections to content
For each planned section, find it in the actual docs/{doc-name}.md file. Check:
- Does the section heading exist?
- Is there content under the heading?
Step 3: Assess substance
For each section present in the document, evaluate the substance according to the following levels.
Section status levels
Complete
- Section has substantive content that addresses its purpose
- Guiding questions from @{AGENT_FOLDER}/dockit/references/sections.md are answered
- Content is specific, not generic
- Cross-references to other sections are present where expected
Thin
- Section exists and has real content, but it is insufficient
- Missing key aspects that the section should cover
- Too brief to be useful on its own
- Example: a "Variants" section that lists variant names but does not explain when to use each one
Placeholder
- Section heading exists but has placeholder or minimal content
- Not useful to a reader in its current state
- Contains one of the following placeholder patterns:
- TODO, TBD, TBC, FIXME
- "Coming soon", "To be added", "To be documented"
- "See [link]" with no other content (a link alone is not documentation)
- A single sentence (unless the section genuinely only needs one, such as "Name")
- Only a heading and a subheading with no content
- Lorem ipsum or other placeholder text
- Repeated content from another section (copy-paste without adaptation)
Missing
- Section was in
structure.mdbut has no corresponding heading in the doc - Or heading exists but there is no content below it
Minimum content thresholds
These are guidelines, not rules. Context matters.
Constructs
| Section type | Minimum expectation |
|---|---|
| Metadata | The name, documentation type, and tier are stated clearly |
| Description | A clear, concise description that someone unfamiliar with the concept could understand |
| Anatomy | A numbered list of parts, each with a name and description, and a link to an annotated screenshot |
| Usage | Provides an understanding of how the construct should be used |
| Interactions | Lists the most important interactions that this construct has |
| Examples | A few scenarios showing how the construct is applied, including an image and description for each scenario |
| Properties | A list of the most important properties of this construct |
Concepts
| Section type | Minimum expectation |
|---|---|
| Metadata | The name, documentation type, and tier are stated clearly |
| Description | A clear, concise description that someone unfamiliar with the concept could understand |
| Content | Provides the minimum amount of content that a reader would need to understand the core of this concept |
Cross-reference checks
Sections should reference each other where appropriate:
- "When to use" and "When not to use" should reference specific variants or states mentioned earlier
- Usage guidelines or properties should reference the anatomy parts from the Anatomy section
- "When not to use" should reference other components of the design system that could be used instead
Flag when these cross-references are missing — it usually indicates incomplete thinking.
Internal consistency checks
- Component name should be identical across all sections
- Variant names should match between Variants and Do's/Don'ts
Output format
━━━ Completeness Review ━━━
Section Status:
[done] Name — Complete
[done] Description — Complete
[warning] When to Use — Thin: only 1 scenario listed, recommend 2-3
[done] When Not to Use — Complete
[done] Anatomy — Complete
[warning] Variants — Thin: variants listed but missing use-case rationale
[skip] States — Placeholder: contains "TBD"
[done] Props / API — Complete
[warning] Accessibility — Thin: missing screen reader behaviour
[done] Content Guidelines — Complete
[done] Code Examples — Complete
[skip] Do's and Don'ts — Missing: no section found in document
Cross-Reference Issues:
- Do's and Don'ts should reference the 3 variants described in Variants section
- Code Examples do not demonstrate the "compact" variant
Consistency Issues:
- Props section calls it "isDisabled" but Code Examples use "disabled"
Summary:
Complete: 7/12
Thin: 3/12
Placeholder: 1/12
Missing: 1/12
Cross-reference issues: 2
Consistency issues: 1