Skip to content

v0.3.0 — Documentation Completeness, Conway's Law Check & Internationalization

Choose a tag to compare

View all tags
@hyhmrright hyhmrright released this 27 Mar 01:04
v0.3.0
f9452fe

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.

Assets 2
Loading