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.
One doc type per page	Pick one Diátaxis type: tutorial, how-to, reference, or explanation. Link to the others instead of mixing them. A README is the exception: an entry point (pitch + how-to + index).

Length Budget (MANDATORY)

Structure does not fix volume. Enforce these limits:

Element	Limit
Opening paragraph	3 lines max.
Section prose	~25 lines max. Code blocks do not count; keep one example per concept.
Flat bullet list	7 items max. Lookup tables (commands, options, codes) and link lists are exempt.
Sentence	One idea. Active voice. Common words.

Where overflow goes:

• A page that already exists, or one you write in the same change.
• Otherwise a <details> block (GitHub renders it).
• Never cut reference content that has no other home.

Cut on sight:

• Restating what the code, command, or table already says.
• Closing summaries that repeat the opening.
• Generic "considerations", "best practices", or "notes" sections with no action.
• Catalogs of options the reader will not choose between.

Trim Pass (before delivering)

1. Delete every sentence the reader would not use to act or decide.
2. Target ~40% fewer words than the first draft (measure words, not lines: tables and <details> add lines). Preservation wins over the target; if it cannot be met on one page, say the doc needs splitting.
3. Re-check the length budget.
4. Preservation check (MANDATORY when rewriting an existing doc): extract every command, flag, config key, env var, error message, and link from the original and the result, and diff them. Each missing item must live on an existing linked page; otherwise restore it. Report the diff, never claim "nothing lost" without it. Ignore anchor slugs (#lint---base-ref) when extracting flags.
5. Keep heading anchors that other pages link to, or list the broken ones.

Actionable = anything the reader types, configures, or sees as output or error.

README Shape

# <name> — <one-line what it does>
<3-line pitch: problem, who it is for>
## Install
## Quick start   (first useful result in < 5 commands)
## Usage         (command/option lookup table)
## Configuration (keys table)
## Upgrading     (only versions that need action)
## Further reading (links to existing pages)

Documentation Shape

For PRs, RFCs, and guides, use this 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