ReddRadar
Agent skill
enhance-docs
Use when documentation needs to be updated, clarified, or reorganized to better serve users' jobs-to-be-done with low cognitive load and high signal.
Install this agent skill to your Project
npx add-skill https://github.com/computerlovetech/agr/tree/main/skills/development/codebase-maintenance/enhance-docs
SKILL.md
Enhance Docs
Overview
Improve documentation so it is up to date, coherent, and centered on users' jobs-to-be-done. Favor less content with higher clarity.
Inputs (ask if missing, max 5)
- Docs scope (which files or sections)
- Primary audiences and their jobs-to-be-done
- Source of truth for product behavior (code, APIs, changelog)
- Recent changes or upcoming releases
- Constraints (tone, length, compliance, deadlines)
Principles
- Less is more: reduce noise, keep only what helps users act.
- Low cognitive load: short paragraphs, clear headings, predictable structure.
- High signal: prioritize steps, outcomes, and decision points.
- JTBD-first: structure around what users are trying to accomplish.
Workflow
- Map jobs-to-be-done
- List top 3-5 user jobs and the docs that should enable each.
- Check freshness and accuracy
- Compare docs against current behavior, APIs, and recent changes.
- Simplify and restructure
- Remove redundancy, collapse long lists, and apply progressive disclosure.
- Improve coherence
- Align terminology, fix contradictions, and add consistent cross-links.
- Clarify with examples
- Add minimal examples only where they unblock action.
- Deliver ranked improvements
- Prioritize changes by impact on user success and confusion reduction.
Output Format
## Documentation Enhancement
### Context Summary
[1-3 sentences]
### JTBD Map
- Job: ... -> Docs: ... -> Success criteria: ...
### Issues (ranked)
1) [Issue] — impact: high, evidence: ...
### Proposed Changes (ranked)
1) [Change] — rationale: ...
### Quick Wins
- ...
### Open Questions
- ...
Quick Reference
- Trim before adding.
- Structure by jobs and outcomes, not features.
- Keep headings short and action-oriented.
Common Mistakes
- Adding more text instead of removing noise
- Mixing audiences in the same section
- Describing features without user tasks
- Missing cross-links or inconsistent terminology
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
computerlovetech/agr
migrate-to-skills
computerlovetech/agr
discover-assumptions
Use after solution concepts exist to surface and prioritize assumptions behind outcomes, opportunities, or solution ideas and design experiments to test them.
computerlovetech/agr
discover-opportunities
Use after outcomes are defined to discover opportunities, unmet needs, market gaps, or JTBD insights before choosing solutions.
computerlovetech/agr
discover-outcomes
Use at the start of product strategy to define or refine desired outcomes and success metrics (e.g., for Opportunity Solution Trees or continuous discovery) before selecting opportunities or solutions.
computerlovetech/agr
ideate-solutions
Use after opportunities are defined to generate and evaluate multiple product solution concepts before validating assumptions. Triggers when you need a set of distinct solution options tied to outcomes and opportunities.
computerlovetech/agr
ost
Use when running or maintaining an Opportunity Solution Tree (OST) workflow with a lightweight graph store and CLI. Provides a single entry skill that routes to outcome, opportunity, solution, and assumption/experiment phases via progressive disclosure.
Didn't find tool you were looking for?