brooks-harness

---

"The bearing of a child takes nine months, no matter how many women are assigned." — Frederick Brooks, The Mythical Man-Month (1975)

50 years later, Brooks was still right — and so were McConnell, Fowler, Martin, Hunt & Thomas, Evans, Ousterhout, Winters, Meszaros, Osherove, Feathers, and the Google Testing team.

Most code quality tools count lines and cyclomatic complexity. brooks-lint goes deeper — it diagnoses your code against six decay risk dimensions synthesized from twelve classic engineering books, producing structured findings with book citations, severity labels, and concrete remedies every time.

For the full source-to-skill mapping, including exceptions and false-positive guards, see skills/_shared/source-coverage.md.

Quick Start

# Claude Code
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace

# Any other Agent Skills platform — Cursor · Codex · Gemini · Copilot · Windsurf · OpenCode · Kiro · Bob …
curl -fsSL https://raw.githubusercontent.com/hyhmrright/brooks-lint/main/scripts/install.sh | bash -s -- <platform>

Then just ask ("review this PR", "audit the architecture"), or run one of the six commands — /brooks-review, /brooks-audit, /brooks-debt, /brooks-test, /brooks-health, /brooks-sweep (what each one does).

Every finding comes back as Symptom → Source → Consequence → Remedy with a book citation and a 0–100 Health Score. Full install options (10 more platforms) and CI/CD setup are below.

The Twelve Books

The Six Decay Risks

brooks-lint evaluates your code across six production-code decay risks and six test-suite decay risks synthesized from twelve classic engineering books:

Philosophy of SD = A Philosophy of Software Design (Ousterhout) · SE@Google = Software Engineering at Google (Winters et al.)

What It Looks Like

Given this code:

class UserService:
    def update_profile(self, user_id, name, email, avatar_url):
        user = self.db.query(f"SELECT * FROM users WHERE id = {user_id}")
        user['email'] = email
        ...
        if user['email'] != email:   # always False — silent bug
            self.smtp.send(...)
        points = user['login_count'] * 10 + 500
        self.db.execute(f"UPDATE loyalty SET points={points} WHERE user_id={user_id}")

brooks-lint produces:

---

Health Score: 28/100

This method concentrates four unrelated business responsibilities into a single function, contains a logic bug that silently suppresses email change notifications, and is wide open to SQL injection.

🔴 Change Propagation — Single Method Changes for Four Unrelated Business Reasons

Symptom: update_profile performs profile field updates, email change notifications, loyalty points recalculation, and cache invalidation all in one method body. Source: Fowler — Refactoring — Divergent Change; Hunt & Thomas — The Pragmatic Programmer — Orthogonality Consequence: Any change to the loyalty formula risks breaking email notifications and vice versa. Every edit carries regression risk across four unrelated domains simultaneously. Remedy: Extract NotificationService, LoyaltyService, and UserCacheInvalidator. UserService.update_profile should orchestrate by calling each — it should hold no implementation logic itself.

🔴 Domain Model Distortion — Silent Logic Bug: Email Notification Never Fires

Symptom: user['email'] = email overwrites the old value before if user['email'] != email — the condition is always False. The notification is dead code. Source: McConnell — Code Complete — Ch. 17: Unusual Control Structures Consequence: Users are never notified when their email address changes. Silent data integrity failure — the system appears functional while violating a business rule. Remedy: Capture old_email = user['email'] before any mutation. Compare against old_email, not user['email'].

*(+ 6 more findings including SQL injectio