hyhmrright/brooks-lint

What it solves

brooks-lint is an AI-powered code review tool that identifies architectural drift, technical debt, and domain model distortion—issues that traditional linters (which focus on syntax and style) typically miss. It provides a structured, traceable way to evaluate code quality based on established software engineering principles rather than generic AI suggestions.

How it works

The tool synthesizes principles from twelve classic engineering books (such as The Mythical Man-Month, Clean Architecture, and Refactoring) to diagnose code across twelve "decay risks" (six for production code and six for test suites).

When reviewing code, it follows a strict diagnostic chain: Symptom $\rightarrow$ Source $\rightarrow$ Consequence $\rightarrow$ Remedy. Each finding is backed by a book citation, a severity label (Critical, Warning, or Suggestion), and a numeric Health Score (0–100).

Who it’s for

Software engineers and architects who want consistent, evidence-based code reviews and architecture audits that are grounded in software engineering literature rather than just LLM patterns.

Highlights

• Book-Grounded Analysis: Traces every finding back to one of twelve classic software engineering texts.
• Six Production Decay Risks: Diagnoses issues like Cognitive Overload, Change Propagation, and Dependency Disorder.
• Architecture Audits: Generates Mermaid dependency graphs to visualize module relationships and identify circular dependencies.
• Multi-Platform Support: Integrates as an "Agent Skill" across various AI coding assistants including Claude Code, Cursor, Windsurf, and GitHub Copilot.
• Comprehensive Toolset: Includes specialized commands for technical debt roadmapping (/brooks-debt), test suite auditing (/brooks-test), and automated fixing (/brooks-sweep).