/fix-docs
Fix the highest priority documentation gap.
What This Does
- Invoke
/check-docsto audit documentation - Identify highest priority gap
- Fix that one issue
- Verify the fix
- Report what was done
This is a fixer. It fixes one issue at a time. Run again for next issue. Use /documentation for full setup.
Process
1. Run Primitive
Invoke /check-docs skill to get prioritized findings.
2. Fix Priority Order
Fix in this order:
- P0: Missing README.md, missing.env.example
- P1: README sections, undocumented env vars, architecture
- P2: Stale docs, CONTRIBUTING.md, ADRs
- P3: Polish, extras
3. Execute Fix
Missing README.md (P0): Generate README with proper structure:
- Project name and tagline
- What it does (one paragraph)
- Quick Start (3 commands max)
- Configuration (env vars)
- Development commands
- License
Delegate to Codex or write directly.
Missing.env.example (P0):
# Scan for env vars and create .env.example
grep -rhoE "process\.env\.[A-Z_]+" --include="*.ts" --include="*.tsx" src/ app/ 2>/dev/null | \
sort -u | sed 's/process.env.//' | \
awk '{print $1"="}' > .env.exampleREADME missing sections (P1): Add the missing section with appropriate content.
Undocumented env vars (P1): Add missing vars to.env.example with comments.
Missing architecture docs (P1): Invoke /cartographer to generate CODEBASE_MAP.md.
Stale documentation (P2): Review and update outdated content.
4. Verify
After fix:
# Verify file exists
[ -f "README.md" ] && echo "✓ README exists"
[ -f ".env.example" ] && echo "✓ .env.example exists"
# Verify content
grep -q "## Installation" README.md && echo "✓ Has installation"
grep -q "## Quick Start" README.md && echo "✓ Has quick start"5. Report
Fixed: [P0] Missing README.md
Created README.md with:
- Project description
- Quick start guide
- Environment setup
- Development commands
Next highest priority: [P1] Missing .env.example
Run /fix-docs again to continue.Branching
Before making changes:
git checkout -b docs/fix-$(date +%Y%m%d)Single-Issue Focus
This skill fixes one issue at a time. Benefits:
- Small, reviewable changes
- Easy to revert if needed
- Clear commit history
- Predictable behavior
Run /fix-docs repeatedly to work through the backlog.
Related
/check-docs- The primitive (audit only)/log-doc-issues- Create issues without fixing/documentation- Full documentation workflow/cartographer- Generate architecture docs