cognitive-doc-design

## When to Use Load this skill when creating or editing documentation that people need to understand quickly, retain, or use during review. Use it especially for: - 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. ## 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 Use this default structure unless the repo already provides a stronger template: ```markdown # <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> - [ ] <Reader can confirm that> ## Next step <Link or act...