Brooks-Lint

What's New in v0.3.0

🆕 8th Dimension: Documentation Completeness

Brooks wrote in Ch. 15: "The other face of a program is the documentation it needs." And in Ch. 7: "The Tower of Babel failed not from lack of vision, but lack of communication."

v0.3 adds Documentation Completeness as a full scoring dimension with two independent sub-scores:

• Code-level — public interfaces, why-comments, parameter clarity
• Arch-level — ADRs, cross-team interface specs, system README currency

Report format: code-level X/5 · arch-level Y/5 → avg Z/5

🏢 Conway's Law Check (Architecture Audit)

Architecture Audit (Mode 2) now includes a Step 5: Conway's Law Check — an optional section that maps team boundaries against module boundaries and assesses Tower of Babel risk:

• Structural alignment between team ownership and module structure
• Cross-team dependency direction (unidirectional vs. bidirectional)
• Ownerless module detection
• Common language (interface spec coverage)

📋 ADR Health Assessment (Tech Debt)

Tech Debt Assessment (Mode 3) now classifies ADR debt as a sub-category of Knowledge Debt:

• Detects missing, stale, or incomplete Architecture Decision Records
• Repayment guidance: reverse ADRs for untouchable modules, minimum viable ADR template

🌐 Full Internationalization

All skill guide files are now fully in English — no mixed Chinese/English content. The skill is now accessible to international contributors and users.

🔧 12 Quality Fixes

A deep audit of the skill itself identified and fixed 12 issues:

• Naming consistency: "7 dimensions" corrected to "8 dimensions" throughout
• Formula clarity: Overall health weighted mean now fully specified with star thresholds
• Mode detection: Tiebreaker rule for Mode 1 vs Mode 2; Mode 3 covers code-with-debt-question
• Quick-skip alignment: Dimension 3 scope fixed (codebase-wide, not diff-only); Dimension 5 tightened
• Auto-generated code: Skip rule added for protobuf stubs, ORM migrations, lock files
• Architecture guide: Architecture-specific scoring added for all 3 previously missing dimensions
• Monorepo guidance: How to apply the dependency map and Conway check in monorepos
• Fallback handling: debt-guide now handles user declining evidence question

Upgrade

# Plugin manager
/plugin install hyhmrright/brooks-lint

# Manual
cp -r skills/brooks-lint ~/.claude/skills/brooks-lint

Breaking Changes

None. The 8th dimension is additive — existing 7-dimension reviews remain valid. Overall health denominator increases from 9 to 10 when all 8 dimensions are scored.