gentle-ai-cognitive-doc-design

1## When to Use
2 
3Load this skill when creating or editing documentation that people need to understand quickly, retain, or use during review.
4 
5Use it especially for:
6 
7- PR descriptions and review notes.
8- Contributor or maintainer guides.
9- Architecture, workflow, or onboarding docs.
10- Any doc that currently feels long, dense, or hard to scan.
11 
12## Critical Patterns
13 
14| Pattern | Rule |
15|---------|------|
16| Lead with the answer | Put the decision, action, or outcome first. Context comes after. |
17| Progressive disclosure | Start with the happy path, then add details, edge cases, and references. |
18| Chunking | Group related information into small sections. Keep flat lists short. |
19| Signposting | Use headings, labels, callouts, and summaries so readers know where they are. |
20| Recognition over recall | Prefer tables, checklists, examples, and templates over prose that must be remembered. |
21| Review empathy | Design docs so reviewers can verify intent without reconstructing the whole story. |
22 
23## Documentation Shape
24 
25Use this default structure unless the repo already provides a stronger template:
26 
27```markdown
28# <Outcome-oriented title>
29 
30<One paragraph: what changed, who it helps, and why it matters.>
31 
32## Quick path
33 
341. <First action>
352. <Second action>
363. <Verification or expected result>
37 
38## Details
39 
40| Topic | Decision |
41|-------|----------|
42| <area> | <concise explanation> |
43 
44## Checklist
45 
46- [ ] <Reader can confirm this>
47- [ ] <Reader can confirm that>
48 
49## Next step
50…