cognitive-doc-design

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