Brooks-Lint

A focused patch on top of v1.0.0: 28 files of documentation accuracy, skill-guide tightening, and developer-experience fixes. No behavior or API changes — all skill logic is identical to v1.0.0. Existing users can upgrade at any time with zero migration risk.

🐛 Fixed

Documentation bugs that broke workflows

• Broken Manual Install commands in README.md (Claude Code & Gemini CLI sections). cp -r skills/ ~/.claude/skills/brooks-lint silently produced a nested brooks-lint/skills/ directory instead of installing the skills. Fixed with an explicit mkdir -p plus cp -r skills/*.
• Fictional gemini skills reload command in GEMINI.md — replaced with /quit + relaunch, which is how Gemini CLI actually picks up local skill edits.
• bug_report.md version query — the cat ~/.claude/plugins/.../package.json placeholder couldn't be pasted and run. Replaced with a /plugin list instruction that actually works.

Wrong citations in skill guides

• Characterization Tests — Ch. 8 corrected to Ch. 13 in test-guide.md (Feathers, Working Effectively with Legacy Code).
• Over-engineering source — removed the stale “Evils of Duplication (YAGNI corollary)” entry (that chapter is DRY, not YAGNI). Now correctly cites Topic 4: Good-Enough Software from The Pragmatic Programmer.
• Slow-suite T6 source — tightened from vague “Test suite design principles” to Meszaros' explicit Slow Tests (p. 253); now aligned across test-guide.md and test-decay-risks.md.

Structural errors in skill guides

• pr-review-guide.md Output section was placed before Step 7, which broke the Analysis Process flow. Moved to its correct position after Step 7 so the steps are contiguous.
• debt-guide.md declared "three steps" but actually shipped four (Step 1, 2, 2b, 3). Promoted Step 2b: Classify Debt Intent to Step 3, renumbered the final step to Step 4, and fixed the preamble.
• architecture-guide.md Step 2 hint referenced a stale ⚠️ symbol that wasn't in the example. Now correctly cites the actual -.->|circular| Mermaid edge.
• common.md Auto Scope Detection was missing the Health Dashboard branch. Also removed a hard-coded "PR Review Step 7" label — now uses the named "Quick Test Check" step, so future renumbering won't silently rot the reference.

Contribution workflow

• CONTRIBUTING.md — the "Three Ways to Contribute" section actually shipped with four paths (the fourth was unnumbered and floated between §2 and §3). Renamed to "Four Ways", promoted Adding a new decay risk to a numbered §4, and reordered by difficulty (1 → 2 → 3 → 4).

Gallery accuracy

• docs/gallery.md — fixed a self-contradicting "Critical / Scheduled" cell in the Debt Summary Table (the schema expects a single classification). Now reads "Mixed (1 Critical + 1 Scheduled)". Harmonized the ~9 min vs ~542s inconsistency for the same data point. The preamble now honestly says "lightly abridged — some Consequence lines trimmed" instead of claiming zero editing.

🔧 Changed

SKILL.md Process convention — skeleton + guide citation

v1.0.0 required SKILL.md Process sections to mirror the guide's step list 1:1. In practice this forced readers — and Claude running the skill — to read the same list twice. v1.0.1 switches to a high-level skeleton (3–6 items) that cites guide Step ranges inline, e.g. Scan decay risks (Steps 1–7 of the guide).

• The guide owns the detailed numbered steps; the skeleton is for orientation.
• Counts no longer need to match — CLAUDE.md, AGENTS.md, and GEMINI.md all document the new rule.
• npm run validate still enforces guide step continuity (sub-steps like 2a / 6b allowed) and SKILL.md Process-section presence.
• All five SKILL.md Process sections have been updated to the new format.

Slash-command wrapper hardening

All five commands/*.md now declare allowed-tools: Skill. The command turn can only dispatch the skill; once invoked the skill retains full tool access. Result: fewer permission prompts on first use.

Typographic consistency

• Unified Pain × Spread (Unicode × with spaces) across brooks-debt/SKILL.md, health-guide.md, evals.json, and docs/gallery.md. Previously a mix of Pain x Spread (ASCII) and Pain×Spread (no spaces).
• Unified Ch. X chapter citations (ASCII space after the period) across test-decay-risks.md, test-guide.md, architecture-guide.md, and pr-review-guide.md.

README.md Roadmap

Added a Current state callout so historical milestones like v0.3: Eight Brooks dimensions and v0.4: Six-book framework aren't misread as today's feature set.

health-guide.md dashboard template

Added the **Mode:** Health Dashboard field and standard --- section dividers so the dashboard report aligns visually with the other four skill reports.

📦 Install / Upgrade

Claude Code plugin marketplace

```
/plugin marketplace update
/plugin install brooks-lint@brooks-lint-marketplace
```

Manual install — Claude Code

```bash
mkdir -p ~/.claude/skills/brooks-lint
cp -r skills/* ~/.claude/skills/brooks-lint/
```

Manual install — Gemini CLI

```bash
mkdir -p ~/.gemini/skills/brooks-lint
cp -r skills/* ~/.gemini/skills/brooks-lint/
```

New users

See the README for the full install matrix (Claude Code, Gemini CLI, Codex CLI).

📚 Available Skills

| Command | Description |
|---------|-------------|
| `/brooks-review` | PR code review — decay risks with Iron Law findings |
| `/brooks-audit` | Architecture audit — dependency graph, layering, Conway's Law |
| `/brooks-debt` | Tech debt assessment — Pain × Spread prioritization |
| `/brooks-test` | Test quality review — brittleness, mock abuse, coverage illusions |
| `/brooks-health` | Health dashboard — composite score across all four dimensions |

All skills are behaviourally unchanged from v1.0.0.

🙏 Credits

Consistency pass driven by a repo-wide documentation audit. Full diff: v1.0.0...v1.0.1.