| name | cognitive-doc-design |
| description | Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs. |
| license | Apache-2.0 |
| metadata | {"author":"gentleman-programming","version":"1.0"} |
Activation Contract
Load when creating or editing documentation that people need to understand quickly, retain, or use during review:
- PR descriptions and review notes
- Contributor or maintainer guides
- Architecture, workflow, or onboarding docs
- Any doc that currently feels long, dense, or hard to scan
Hard Rules
- Lead with the answer — decision, action, or outcome first; context comes after
- Never open with "This document explains..." or "In this guide we will..."
- Headers must be outcome-oriented actions, not topic labels ("Add a route" not "Routes")
- Progressive disclosure: happy path first, edge cases and references last
Decision Gates
| Doc type | Recommended shape |
|---|
| PR description | Summary (1 para) → Changes table → Test Plan → Linked issue |
| README / guide | Outcome title → Quick path (numbered) → Details table → Checklist → Next step |
| RFC / architecture | Decision first → Context → Options considered → Trade-offs → Out of scope |
| Onboarding | First action → Expected result → Troubleshooting → Next step |
| Runbook | Symptom → Steps → Verification → Escalation |
Critical Patterns
| Pattern | Rule |
|---|
| Lead with the answer | Put the decision, action, or outcome first. Context comes after. |
| Progressive disclosure | Start with the happy path, then add details, edge cases, and references. |
| Chunking | Group related information into small sections. Keep flat lists short. |
| Signposting | Use headings, labels, callouts, and summaries so readers know where they are. |
| Recognition over recall | Prefer tables, checklists, examples, and templates over prose that must be remembered. |
| Review empathy | Design docs so reviewers can verify intent without reconstructing the whole story. |
Documentation Shape
# <Outcome-oriented title>
<One paragraph: what changed, who it helps, and why it matters.>
## Quick path
1. <First action>
2. <Second action>
3. <Verification or expected result>
## Details
| Topic | Decision |
|-------|----------|
| <area> | <concise explanation> |
## Checklist
- [ ] <Reader can confirm this>
## Next step
<Link or action that continues the workflow.>
Output Contract
Return the rewritten or new document following the shape for its type (from Decision Gates). Every section must be present. No section may start with "This section covers...".
Gotchas
- Opening paragraphs that recap the problem before stating the solution — the reader already knows the problem
- Headers like "Background", "Overview", "Introduction" — these signal the answer is buried; replace with outcome-oriented titles
- Bullet lists with 8+ items — group them or convert to a table; long flat lists don't chunk
- Missing "Next step" — docs without a clear next action leave readers stranded
Commands
git diff --name-only -- '*.md'
gh pr view <PR_NUMBER> --json additions,deletions,changedFiles
