/fix-docs

Fix the highest priority documentation gap.

What This Does

• Invoke /check-docs to 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.example

README 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