playbooks

home / skills / phrazzld / claude-config / fix-docs

fix-docs skill

/skills/fix-docs

This skill audits docs, fixes the highest priority gap, and verifies the result, iterating through issues one by one.

npx playbooks add skill phrazzld/claude-config --skill fix-docs

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.8 KB
---
name: fix-docs
description: |
  Run /check-docs, then fix the highest priority documentation issue.
  Creates one fix per invocation. Invoke again for next issue.
  Use /log-doc-issues to create issues without fixing.
effort: high
---

# /fix-docs

Fix the highest priority documentation gap.

## What This Does

1. Invoke `/check-docs` to audit documentation
2. Identify highest priority gap
3. Fix that one issue
4. Verify the fix
5. 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:
1. **P0**: Missing README.md, missing .env.example
2. **P1**: README sections, undocumented env vars, architecture
3. **P2**: Stale docs, CONTRIBUTING.md, ADRs
4. **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):**
```bash
# 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:
```bash
# 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:
```bash
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

Overview

This skill automates a single, high-priority documentation fix per run. It audits the repo with /check-docs, applies a focused correction for the top-priority gap, verifies the change, and reports the result. Run repeatedly to work through the backlog one issue at a time.

How this skill works

First it runs /check-docs to generate a prioritized list of documentation issues. It selects the highest priority finding and applies a targeted fix (for example, creating README.md or .env.example, adding missing README sections, or updating env var docs). After making the change it runs simple verification checks and summarizes what was changed and what remains.

When to use it

  • You want an automated, single-change fix for the most critical documentation gap.
  • You prefer small, reviewable documentation commits instead of large bulk updates.
  • You need to bootstrap missing essentials like README.md or .env.example quickly.
  • You want to iterate through documentation backlog with predictable, repeatable steps.
  • You need a safety-first approach that makes one fix per invocation for easy review.

Best practices

  • Run /check-docs first to see the prioritized findings before invoking fixes.
  • Use a dedicated docs branch (git checkout -b docs/fix-YYYYMMDD) for each fix.
  • Keep each invocation focused: one issue, one commit, clear commit message.
  • Verify fixes locally with the provided verification commands before PR.
  • Run the skill repeatedly to address remaining items in priority order.

Example use cases

  • Repository missing README.md: generate a complete README with tagline, quick start, config, and dev commands.
  • Project lacks .env.example: scan source files for env vars and create a populated .env.example.
  • README exists but lacks Quick Start or Installation: append the missing sections with concise commands.
  • Undocumented environment variables discovered: add them to .env.example with comments.
  • You want to iteratively create architecture docs by addressing P1 items, then invoking /cartographer when needed.

FAQ

How many issues does this skill fix per run?

One. This skill is intentionally single-issue focused to keep changes small and reviewable.

What priority order does it follow?

It fixes in priority order: P0 (missing README, .env.example), then P1 (sections, env docs, architecture), P2 (stale docs, CONTRIBUTING, ADRs), and P3 (polish).