cognitive-doc-design

Structures documentation to reduce cognitive load for readers and reviewers.

Updated Jul 10, 2026

Search Tags:#code review #documentation #markdown #technical writing #readme #cognitive load #pr description

Ready to run

npx skills add https://github.com/AD-Paladins/beaconator-web --skill cognitive-doc-design-ad-paladins

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: cognitive-doc-design
Source: https://github.com/AD-Paladins/beaconator-web/tree/main/.config/opencode/skills/cognitive-doc-design
Command: npx skills add https://github.com/AD-Paladins/beaconator-web --skill cognitive-doc-design-ad-paladins

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Documentation often becomes long, dense, and hard to scan, forcing readers and PR reviewers to reconstruct context before they can act. This Skill applies cognitive load principles so docs lead with the answer, chunk information, and stay scannable. ## Core Features & Use Cases - Cognitive Patterns: Six rules including lead with the answer, progressive disclosure, chunking, signposting, recognition over recall, and review empathy. - Default Doc Template: A reusable Markdown structure with outcome-oriented title, quick path, details table, checklist, and next step. - PR Review Guidance: Conventions for stating review order, scope boundaries, and linked PR chains to reduce reviewer burnout. - Use Case: When writing a README, onboarding guide, or PR description that feels dense, apply the patterns to restructure it into a scannable, action-first document. ## Quick Start Rewrite my PR description using the cognitive-doc-design patterns so reviewers can scan it quickly.

Frequently Asked Questions about cognitive-doc-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I write documentation that is easier to scan?▼

Lead with the answer or decision first, then add context. Group related information into small chunks, use headings and tables for signposting, and prefer checklists and examples over prose readers must memorize.

How to structure a PR description for faster code review?▼

State what to review first, declare what is intentionally out of scope, and link previous and next PRs when work is chained. Keep each section focused on one decision and use checklists for acceptance criteria.

What is progressive disclosure in technical writing?▼

Progressive disclosure means presenting the happy path first, then layering in details, edge cases, and references. Readers get the essential action immediately without wading through exceptions.

When should I not use a fixed documentation template?▼

Skip the default template when the repository already provides a stronger or established structure. The skill explicitly defers to existing repo conventions rather than overriding them.

How can I check if my PR is too large for reviewers?▼

Run gh pr view <PR_NUMBER> --json additions,deletions,changedFiles to inspect the changed-line count. Large diffs signal high cognitive load and may need splitting or clearer review guidance.