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.
AKILI-SPECS Integration
| AKILI moment |
Documents written with this skill |
/akili-constitution |
docs/prd.md and the baseline docs |
/akili-specify |
requirements.md, design.md, tasks.md |
/akili-execute |
PR descriptions and review notes (PR and Review Docs section below) |
/akili-archive |
The archive summary and the Kaizen entry file under docs/specs/kaizen/ |
The AKILI templates in docs/specs/general-setup/ win over the default Documentation Shape below — apply the Critical Patterns inside their structure.
Boundary with caveman: this skill owns persistent artifacts (documents humans reread — PRDs, TRDs, specs, reports, PR descriptions); caveman owns transient agent output (inter-agent messages, progress narration in /akili-execute and /akili-test). Never apply caveman compression to a document this skill governs, and never pad transient chatter with document structure.
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-design3description: Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs.4license: Apache-2.05---67## When to Use89Load this skill when creating or editing documentation that people need to understand quickly, retain, or use during review.1011Use it especially for:1213- PR descriptions and review notes.14- Contributor or maintainer guides.15- Architecture, workflow, or onboarding docs.16- Any doc that currently feels long, dense, or hard to scan.1718## AKILI-SPECS Integration1920| AKILI moment | Documents written with this skill |21|---|---|22| `/akili-constitution` | `docs/prd.md` and the baseline docs |23| `/akili-specify` | `requirements.md`, `design.md`, `tasks.md` |24| `/akili-execute` | PR descriptions and review notes (PR and Review Docs section below) |25| `/akili-archive` | The archive summary and the Kaizen entry file under `docs/specs/kaizen/` |2627The AKILI templates in `docs/specs/general-setup/` win over the default Documentation Shape below — apply the Critical Patterns inside their structure.2829**Boundary with `caveman`:** this skill owns *persistent artifacts* (documents humans reread — PRDs, TRDs, specs, reports, PR descriptions); `caveman` owns *transient agent output* (inter-agent messages, progress narration in `/akili-execute` and `/akili-test`). Never apply caveman compression to a document this skill governs, and never pad transient chatter with document structure.3031## Critical Patterns3233| Pattern | Rule |34|---------|------|35| Lead with the answer | Put the decision, action, or outcome first. Context comes after. |36| Progressive disclosure | Start with the happy path, then add details, edge cases, and references. |37| Chunking | Group related information into small sections. Keep flat lists short. |38| Signposting | Use headings, labels, callouts, and summaries so readers know where they are. |39| Recognition over recall | Prefer tables, checklists, examples, and templates over prose that must be remembered. |40| Review empathy | Design docs so reviewers can verify intent without reconstructing the whole story. |4142## Documentation Shape4344Use this default structure unless the repo already provides a stronger template:4546```markdown47# <Outcome-oriented title>4849<One paragraph: what changed, who it helps, and why it matters.>5051## Quick path52531. <First action>542. <Second action>553. <Verification or expected result>5657## Details5859| Topic | Decision |60|-------|----------|61| <area> | <concise explanation> |6263## Checklist6465- [ ] <Reader can confirm this>66- [ ] <Reader can confirm that>6768## Next step6970<Link or action that continues the workflow.>71```7273## PR and Review Docs7475When documenting a PR, reduce reviewer burnout by making the review path explicit:7677- State what to review first.78- State what is intentionally out of scope.79- Link the previous and next PR when work is chained.80- Keep each section focused on one decision or unit of work.81- Use checklists for acceptance criteria and verification.8283## Commands8485```bash86# Check markdown files changed in the current branch87git diff --name-only -- '*.md'8889# Inspect PR changed-line count for cognitive load90gh pr view <PR_NUMBER> --json additions,deletions,changedFiles91```
JuankCadavid