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:
# <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 action that continues the workflow.>
PR and Review Docs
When documenting a PR, reduce reviewer burnout by making the review path explicit:
- State what to review first.
- State what is intentionally out of scope.
- Link the previous and next PR when work is chained.
- Keep each section focused on one decision or unit of work.
- Use checklists for acceptance criteria and verification.
Commands
# Check markdown files changed in the current branch
git diff --name-only -- '*.md'
# Inspect PR changed-line count for cognitive load
gh pr view <PR_NUMBER> --json additions,deletions,changedFiles
1---
2name: cognitive-doc-design
3description: "Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs."
4license: Apache-2.0
5metadata:
6 source: https://skillmd.com/skills/gabrielmoreira/cognitive-doc-design
7 author: gentleman-programming
8 version: "1.0"
9---
10
11## When to Use
12
13Load this skill when creating or editing documentation that people need to understand quickly, retain, or use during review.
14
15Use it especially for:
16
17- PR descriptions and review notes.
18- Contributor or maintainer guides.
19- Architecture, workflow, or onboarding docs.
20- Any doc that currently feels long, dense, or hard to scan.
21
22## Critical Patterns
23
24| Pattern | Rule |
25|---------|------|
26| Lead with the answer | Put the decision, action, or outcome first. Context comes after. |
27| Progressive disclosure | Start with the happy path, then add details, edge cases, and references. |
28| Chunking | Group related information into small sections. Keep flat lists short. |
29| Signposting | Use headings, labels, callouts, and summaries so readers know where they are. |
30| Recognition over recall | Prefer tables, checklists, examples, and templates over prose that must be remembered. |
31| Review empathy | Design docs so reviewers can verify intent without reconstructing the whole story. |
32
33## Documentation Shape
34
35Use this default structure unless the repo already provides a stronger template:
36
37```markdown
38# <Outcome-oriented title>
39
40<One paragraph: what changed, who it helps, and why it matters.>
41
42## Quick path
43
441. <First action>
452. <Second action>
463. <Verification or expected result>
47
48## Details
49
50| Topic | Decision |
51|-------|----------|
52| <area> | <concise explanation> |
53
54## Checklist
55
56- [ ] <Reader can confirm this>
57- [ ] <Reader can confirm that>
58
59## Next step
60
61<Link or action that continues the workflow.>
62```
63
64## PR and Review Docs
65
66When documenting a PR, reduce reviewer burnout by making the review path explicit:
67
68- State what to review first.
69- State what is intentionally out of scope.
70- Link the previous and next PR when work is chained.
71- Keep each section focused on one decision or unit of work.
72- Use checklists for acceptance criteria and verification.
73
74## Commands
75
76```bash
77# Check markdown files changed in the current branch
78git diff --name-only -- '*.md'
79
80# Inspect PR changed-line count for cognitive load
81gh pr view <PR_NUMBER> --json additions,deletions,changedFiles
82```