Structure guides, READMEs, design documents, and pull request descriptions so readers can find answers quickly. Put outcomes first, introduce details gradually, and use examples, tables, and checklists to support understanding and review.
Design docs that reduce cognitive load. Trigger: writing guides, READMEs, RFCs, onboarding, architecture, or review-facing docs.
Review the instructions the agent will receive before you install.
Load this skill when creating or editing documentation that people need to understand quickly, retain, or use during review.
Use it especially for:
| 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. |
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.>
When documenting a PR, reduce reviewer burnout by making the review path explicit:
# 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
No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Prepare pull requests by checking approved issue links, change-type labels, and required automated checks. Draft the repository’s PR template using observed test results, while leaving commits, pushes, PR creation, and merging under human control.
Split changes exceeding 400 lines into linked pull requests with clear boundaries and dependencies. Choose a chain structure, keep tests and documentation with each work unit, and document review order, verification plans, and justified size exceptions.
Draft clear, considerate comments for code reviews, issue replies, and team updates. Put the actionable point first, explain technical reasons when needed, and give a concrete next step while matching the conversation’s language.
Create and verify gentle-ai journeys, which are scripted sequences of product actions. Check their declarations separately from actual execution, review outdated expectations after behavior changes, and record execution results for pull requests.
Prepare Gentle AI changes for review by linking approved issues, following branch and commit naming rules, and drafting pull requests with observed test results. Check change size and required automated checks before claiming readiness.
Split large code changes into linked pull requests, each with a focused scope. Organize their order, dependencies, and verification steps so reviewers can assess one unit of work at a time.