docs-review

Files (10)

• SKILL.md
• evals.json · evals/
• trigger-evals.json · evals/
• known-canonical-plans.md · references/
• sweep-checklist.md · references/
• check-template.sh · scripts/
• detect-plan-files.sh · scripts/
• file-freshness.sh · scripts/
• validate-links.sh · scripts/
• review-report.md.tmpl · templates/

SKILL.md (first lines)

# docs-review

A documentation-quality sweep: every Markdown file under `README.md` (root) and
`docs/**` is audited against eight axes, then fixed in place. The goal is to
finish a sweep with a clean working tree, zero broken links, no stray plan
files in git, and every doc reflecting the current state of the codebase —
including accurate counts of agents, skills, and commands.

## Confirm before the first write when there is no parent skill

This skill **fixes files in place**. That is correct when `repo-standards` (or
another skill) invoked it as part of a sweep the user already agreed to. It is
not correct when the model reached for it on its own.

Before the first mutating edit, decide which case this is: was this skill
invoked by a parent skill, or autonomously from a user prompt? If there is no
invoking parent skill, **state what you are about to change and get the user's
go-ahead before the first write.** Read-only auditing needs no confirmation —
run the full audit, report the findings, then ask. One confirmation covers the
rest of the sweep; do not ask per file.

This is the safety that replaces this skill's old `disable-model-invocation`
gate. The gate was removed because it also blocked sub-agent invocation, which
broke `repo-standards` phase 6 under orchestration — a sub-agent calling a skill
is model invocation. Keeping the confirmation here, inside the skill, is the
repo's standing preference over gating (see CLAUDE.md, "Gating warning").

## When repo-standards invokes this skill

| repo-standards step | Action |
|---------------------|--------|
| **Polish phase 6** — after standards scaffolding and multi-agent setup | Full audit of `$TARGET_ROOT/README.md` and `docs/**` |
| **Re-run** — after manual P1 doc fixes | Confirm link-clean and counts accurate |

`repo-standards` sets the working directory to `$TARGET_ROOT` before calling this skill. **Always treat the current working directory as the repo root** for all axes — never use the plugin install path or absolute paths from this skill's own directory.

When invoked from `repo-standards`, print a pass/fail summary at the end (format below). Return control only when all P1 doc issues are fixed or explicitly listed for repo-standards to handle.

```
=== docs-review complete ===
Files audited: N
Fixes applied: N
Broken links: N (0 = pass)
Stale docs updated: N
Plan files flagged: N (user confirmation pending)
Platform doc inconsistencies: N (0 = pass)
Install commands verified: N ok / N failed (0 failed = pass)
Generated tables: N in sync / N drifted (0 drifted = pass)
```

## Why this skill exists

Docs drift faster than code. A sweep that's "by hand" misses files,
mis-classifies plan dumps as canonical reference material, and leaves behind
stale agent/skill counts. This skill codifies the routine so the audit is
exhaustive and its judgement calls are explicit.

## Scope

**Full audit (all 8 axes):** `README.md` (repo root), every `*.md` under `docs/`.

**Consistency-check only (Axes 0 + 6):**
- `CLAUDE.md` — verify agent/skill counts match filesystem; update stale claims
- `.github/copilot-instructions.md` — verify architecture description, counts, commands
- `docs/engineering/reference/agent-quick-ref.md` — verify every `plugin/agents/pm-*.md` has an entry

**Out of scope:** `plugin/skills/**/*.md`, `plugin/agents/*.md`, `.claude/rules/*.md` — those have their own validators (`validate-skills.sh`, `validate-agents.sh`).

If the user passes a path argument, restrict the per-file audit to that subset (still run Axis 0 first).

## Axis 0 — Repo State Inventory (ALWAYS FIRST)

**Run before any per-file work.** Generates ground truth used by Axes 6 and 7. All paths are relative to the repo root (current working directory when this skill is invoked).

```bash
# Count entities — gracefully handle repos that lack these paths
AGENT_COUNT=$(ls plugin/agents/pm-*.md 2>/dev/null | wc -l | tr -d ' ')
PLUGIN_SKILL_COUNT=$(ls -d plugin/skills/*/ 2>/dev/null | wc -l | tr -d ' ')
DEV_SKILL_COUNT=$(ls -d .claude/skills/*/ 2>/dev/null | wc -l | tr -d ' ')
HOOK_COUNT=$(jq '.hooks | length' plugin/hooks/hooks.json 2>/dev/null || echo "?")
CLAUDE_AGENT_CLAIM=$(grep -oP '\d+(?= sub-agent)' CLAUDE.md 2>/dev/null | head -1 || echo "?")
CLAUDE_SKILL_CLAIM=$(grep -oP '\d+(?= MCP skill)' CLAUDE.md 2>/dev/null | head -1 || echo "?")
```

Print an inventory table:
```
=== Axis 0 — Repo State Inventory ===
agents:        20  (CLAUDE.md claims: 20) ✓
plugin skills: 32  (CLAUDE.md claims: 29) ✗ → NEEDS UPDATE
dev skills:    11
hooks:         13
```

If counts differ AND `tooling/ci/regen-claude-md.sh` exists, run it to auto-update CLAUDE.md:
```bash
[[ -f tooling/ci/regen-claude-md.sh ]] && bash tooling/ci/regen-claude-md.sh
```
If the script doesn't exist, update the stale counts in CLAUDE.md manually via Edit.

Then generate the per-file manifest:
```bash
{ find . -maxdepth 1 -name 'README.md'; find docs -name '*.md' -type f 2>/dev/null; } | sort > /tmp/review-docs-manifest.txt
TOTAL=$(wc -l < /tmp/review-docs-manifest.txt)
echo "=== $TOTAL files queued for audit ==="
```

If `docs/` does not exist in this repo, note it in the summary and skip Axes 2–5 for that directory.

## The five doc audit axes

The skill walks each in-scope file once and applies all five checks. Fixes are
applied in-place. Findings are appended to `docs/review-${DATE}.md`.

### Axis 1 — Visual cleanliness

Goal: a reader scanning the doc isn't tripped by formatting noise.

What to fix:
- Stray trailing whitespace, mixed tabs/spaces, inconsistent heading levels.

From Tamircohen28/tamirs-superpowers, MIT.

More from Tamircohen28/tamirs-superpowers