Forem: hyhmrright

caveman + brooks-lint + logic-lens: The Complete AI Code Review Stack for Claude

hyhmrright — Wed, 29 Apr 2026 09:32:09 +0000

If you use Claude Code regularly, you've probably heard of caveman — the skill that makes Claude talk like a caveman to cut token usage by 65%. It's brilliant in its simplicity and has earned 49k+ stars for good reason.

But here's a question I started asking myself: what happens after caveman helps Claude think faster and cheaper? Who's actually reviewing the quality of what gets written?

That's the gap I built two new Claude skills to fill. Let me show you how all three tools work together as a complete AI-assisted development stack.

Quick Recap: What caveman Does

caveman is a Claude Code skill that compresses Claude's internal monologue. Instead of verbose reasoning, Claude thinks in primitive shorthand — and uses 65% fewer tokens doing it.

It's a token optimizer. It makes Claude faster and cheaper without changing the quality of what it produces.

What it doesn't do: caveman doesn't review whether your code has architectural debt, logic errors, or violates established software engineering principles. That's not its job — and that's exactly where brooks-lint and logic-lens come in.

The Two Skills That Complete the Stack

1. brooks-lint — The Architectural Review Layer

brooks-lint is a Claude skill that reviews code through the lens of 12 classic software engineering books:

Category	Books
Complexity & Design	A Philosophy of Software Design, Clean Code, Refactoring
Architecture	Clean Architecture, Designing Data-Intensive Applications
Team & Process	The Mythical Man-Month, The Pragmatic Programmer
Reliability	Release It!, Site Reliability Engineering
Security & Quality	The Art of Software Security, Accelerate, Software Engineering at Google

It maps problems to 6 risk categories (R1–R6):

R1 – Accidental Complexity (Ousterhout)
R2 – Rotting Design (Fowler — needs refactoring)
R3 – Mythical Man-Month risk (Brooks — hidden coordination cost)
R4 – Pragmatic debt (Hunt & Thomas — quick fixes that compound)
R5 – Release risk (Nygard — production reliability issues)
R6 – Security concern (Viega & McGraw)

Real example — what it catches:

/brooks-review src/payment/PaymentService.ts

Reviewing 847 lines...

⚠️ R1 – ACCIDENTAL COMPLEXITY (HIGH)
PaymentService handles: payment processing, retry logic, 
notifications, audit logging, and fraud detection.
God class with 5 responsibilities. Split into focused services.

⚠️ R2 – ROTTING DESIGN (MEDIUM)  
processPayment() is 340 lines with 6 nesting levels.
Feature envy: reaching into Order internals 12 times.
Refactoring opportunity: extract PaymentValidator.

⚠️ R5 – RELEASE RISK (HIGH)
No circuit breaker on payment gateway calls.
Retry loop can cascade during gateway outages.

5 usage modes:

/brooks-review file.ts        # Full architectural review
/brooks-quick file.ts         # Fast scan, critical issues only
/brooks-refactor file.ts      # Refactoring suggestions
/brooks-security file.ts      # Security-focused review
/brooks-compare v1.ts v2.ts   # Before/after comparison

2. logic-lens — The Logic & Correctness Layer

logic-lens is a Claude skill that focuses on runtime correctness — the things that compile fine but fail in production:

/logic-lens src/order/OrderProcessor.ts

Analyzing logic patterns...

🔴 CRITICAL – NULL DEREFERENCE (Line 47)
user.address.city accessed without null check.
If user has no address (guest checkout), NullPointerException.
Fix: use optional chaining user.address?.city ?? 'Unknown'

🔴 CRITICAL – RACE CONDITION (Line 103)  
inventory.count checked then decremented in separate operations.
Under concurrent load, two threads can both pass the check.
Fix: Use atomic decrement with minimum-value guard

🟡 MEDIUM – OFF-BY-ONE (Line 156)
Loop runs i <= items.length instead of i < items.length
Will throw ArrayIndexOutOfBoundsException on last iteration

🟡 MEDIUM – SILENT FAILURE (Line 203)
try/catch swallows exception with empty catch block
Payment failures will be silently ignored

logic-lens covers 9 risk categories across 49 scenario types: null/undefined access, race conditions, integer overflow, SQL injection, memory leaks, auth bypass, state machine violations, and more.

How the Three Tools Work Together

Here's the workflow I've settled into:

caveman → [Claude writes code faster & cheaper]
    ↓
/brooks-review → [Is the architecture sound?]
    ↓
/logic-lens → [Will it actually work correctly at runtime?]

Think of it as three layers of defense:

caveman — Efficiency layer. Saves tokens, speeds up iteration.
brooks-lint — Architecture layer. Catches structural problems inspired by engineering classics.
logic-lens — Correctness layer. Catches runtime bugs before they reach production.

A Real Workflow Example

# Step 1: Use caveman for fast, cheap code generation
# (caveman handles this automatically in background)

# Step 2: Check architectural integrity
/brooks-review src/checkout/CheckoutService.ts

# Step 3: Verify runtime correctness
/logic-lens src/checkout/CheckoutService.ts

# Result: Code that's architecturally sound AND logically correct

Why These Tools Are Complementary (Not Overlapping)

Tool	Focus	Catches
caveman	Token efficiency	Nothing — it optimizes Claude's thinking
brooks-lint	Architecture & design	God classes, tight coupling, missing patterns, technical debt
logic-lens	Runtime correctness	Null refs, race conditions, off-by-ones, auth gaps

There's almost zero overlap. Each tool catches a completely different class of problems.

Installation

All three are Claude Code skills — install in seconds:

# caveman (token optimization)
claude mcp add caveman

# brooks-lint (architectural review)
claude skills add https://github.com/hyhmrright/brooks-lint

# logic-lens (logic & correctness)
claude skills add https://github.com/hyhmrright/logic-lens

The Bottom Line

caveman makes Claude think faster. But fast + cheap code that has architectural debt and runtime bugs is still problematic code.

With all three tools in your Claude Code setup:

You write code 65% cheaper (caveman)
Your architecture stays sound (brooks-lint: 12 books, R1–R6 categories)
Your logic stays correct (logic-lens: 49 runtime scenarios)

That's the complete stack. Try all three and let me know what you catch in your codebase.

Built both skills with Claude Code. Happy to answer questions about the implementation in the comments.

Links:

caveman (the original — 49k stars, highly recommended)
brooks-lint — architectural review grounded in 12 books
logic-lens — runtime correctness across 49 scenarios

Why AI Code Review Misses Logic Bugs — And How Structured Execution Tracing Fixes It

hyhmrright — Wed, 29 Apr 2026 05:58:10 +0000

Your CI is green. Your linter is happy. The PR has three approvals. And yet — three weeks later, 2 a.m. PagerDuty.

Sound familiar?

The bugs that cause real production outages rarely look wrong. They pass lint. They pass review. They often pass tests. They emerge from the interaction between two functions, where neither author anticipated what happens when their assumptions silently collide.

This is the problem Logic-Lens was built to solve.

The Root Cause: Pattern Matching vs. Reasoning

When you ask an AI to review code without structure, it pattern-matches. It compares your code to patterns it has seen before. This works well for style. It fails for logic bugs — because logic bugs live in syntax-clean, lint-passing code that looks perfectly normal.

The research is unambiguous. Models using structured semi-formal reasoning achieve 87–93% accuracy on interprocedural code semantics tasks. Unstructured chain-of-thought: 76–78% — and the gap is largest on exactly the class of bugs that cause production incidents.

The difference isn't model capability. It's methodology.

The Fix: Structured Execution Tracing

The key insight: force the model to build an explicit execution trace before reaching any conclusion.

Instead of "does this look right?", the model must:

State premises — every assumption about types, nullability, and preconditions
Trace execution — follow the actual path step by step, crossing function boundaries
Identify divergence — find the exact point where a premise breaks
Prescribe remedy — fix the root cause, not just the symptom

This is the methodology behind Logic-Lens — an open-source plugin for Claude Code, Codex CLI, and Gemini CLI that enforces structured execution tracing on every code review.

What It Looks Like in Practice

Here's a deceptively ordinary Python function:

def process_order(order_id, items, discount_code=None):
    order = db.get_order(order_id)
    total = sum(item['price'] * item['qty'] for item in items)

    if discount_code:
        discount = coupon_service.get_discount(discount_code)
        total = total * (1 - discount)

    order['total'] = total
    order['items'] = items
    db.save_order(order)
    email_service.send_confirmation(order['email'], total)

Looks fine. Three approvals. Ships to production. Here's what Logic-Lens produces:

Logic Health: 31/100

🔴 L6 — Callee Contract Mismatch
   Premises: coupon_service.get_discount(discount_code) → assumed float
   Trace: get_discount returns None for expired codes (documented in coupon_service.py:47)
   Divergence: total * (1 - None) raises TypeError at runtime
   Remedy: Guard with `if discount is not None` before applying. Add contract test.

🔴 L3 — Boundary Blindspot
   Premises: items assumed non-empty
   Trace: sum() over [] returns 0 → order saved with total = $0.00
   Divergence: No validation before db.save_order
   Remedy: Assert len(items) > 0 or raise ValueError("Order must have at least one item")

🟡 L5 — Control Flow Escape
   Premises: email_service.send_confirmation assumed non-throwing
   Trace: SMTPException propagates before db connection cleanup
   Divergence: Connection pool exhausted under sustained email failures
   Remedy: Wrap email send in try/finally; release connection unconditionally

Every finding includes all four sections — Premises, Trace, Divergence, Remedy. That's the Iron Law of Logic-Lens: no finding ships without showing its work.

Nine Logic Risk Categories

Logic-Lens evaluates code across nine dimensions:

Code	Name	What It Catches
L1	Shadow Override	Variable shadowing across scopes
L2	Type Contract Breach	Type assumptions that break at runtime
L3	Boundary Blindspot	Edge cases (empty, zero, max)
L4	State Mutation Hazard	Shared mutable state side effects
L5	Control Flow Escape	Exception paths that skip cleanup
L6	Callee Contract Mismatch	Return value assumptions that fail
L7	Concurrency/Async Hazard	Race conditions, await misuse
L8	Resource Lifecycle Issue	Leaked connections, handles, memory
L9	Time/Locale Hazard	Timezone, clock, and locale bugs

How It Compares

	Logic-Lens	ESLint/Pylint	GitHub Copilot Review	Plain AI
Explicit execution trace	✅	❌	❌	❌
Premises → Trace → Divergence → Remedy	✅	❌	❌	❌
Interprocedural bug detection	✅	❌	~	~
Zero config, any language	✅	❌	✅	✅
Auditable / reproducible reasoning	✅	✅	❌	❌

Logic-Lens doesn't replace your linter. It catches what linters structurally cannot: behavioral bugs in syntax-clean code.

Benchmark: 91% vs. 19%

Across three real-world codebases with documented production bugs:

Logic-Lens: 91% pass rate on interprocedural, boundary, and state-mutation scenarios
Plain AI (unstructured): 19%

The gap isn't what the model can find with perfect prompting. It's what it consistently finds, across every run, with a traceable reasoning chain that shows its work every time.

Six Skills, One Install

logic-lens          → Full structured trace (the full review)
logic-lens-quick    → Fast path for time-sensitive reviews
logic-lens-security → OWASP-mapped security focus
logic-lens-perf     → Bottleneck and complexity hunting
logic-lens-diff     → PR diff review (interprocedural focus)
logic-lens-report   → Team-ready output with severity scoring

Install in 60 Seconds

Claude Code:

/plugin marketplace add hyhmrright/logic-lens
/plugin install logic-lens@logic-lens-marketplace/logic-review```
{% endraw %}
**Gemini CLI:**
{% raw %}

/extensions install https://github.com/hyhmrright/logic-lens




**Codex CLI:**
See the [README](https://github.com/hyhmrright/logic-lens) for the skill installer command.

---

## Try It

If you've shipped a bug that passed review, it's worth running Logic-Lens on the function that caused it. The trace output is often illuminating even in retrospect.

⭐ [github.com/hyhmrright/logic-lens](https://github.com/hyhmrright/logic-lens)

**Which of the nine risk categories (L1–L9) have you hit most in production?** Drop a comment — happy to run Logic-Lens on a representative example and share the raw output.

---

## Related

If you also care about *why* your architecture has decay risks — not just where behavioral bugs live — I wrote a companion piece grounding AI code review in 12 classic engineering books:

[Show DEV: brooks-lint — an AI code reviewer that cites Fowler, Martin, and Brooks](https://dev.to/hyhmrright/i-synthesized-12-classic-engineering-books-into-an-ai-code-reviewer-heres-what-it-caught-3ed1)

The two tools cover different failure modes and work well together: Logic-Lens catches runtime behavioral bugs via execution tracing; brooks-lint diagnoses architectural decay against Fowler, Martin, Evans, and nine others.

Logic-first code review: catching the bugs your linter, type checker, and AI reviewer all miss

hyhmrright — Sat, 25 Apr 2026 13:32:18 +0000

Your linter says 0 warnings.
Your type checker is clean.
Your AI reviewer says LGTM.

And yet the bug ships.

TL;DR — A category of bugs slips past linters, type checkers, and AI reviewers because they only show up when two functions interact in a way neither author anticipated. I built a free, open-source plugin for Claude Code / Codex CLI / Gemini CLI that uses a methodology called semi-formal execution tracing to catch them. Repo + install: github.com/hyhmrright/logic-lens — feedback and PRs welcome.

This post is about a class of bugs that pass every automated check we have, because the bug only appears when two functions interact in a way neither author anticipated — and how a methodology called semi-formal execution tracing can catch them with surprising consistency.

The bug your tools can't see

Here's a real-looking function. It passes lint, passes type checks, passes its unit tests:

def process_order(order_id, items, discount_code=None):
    order = db.get_order(order_id)
    total = sum(item['price'] * item['qty'] for item in items)
    if discount_code:
        discount = coupon_service.get_discount(discount_code)
        total = total * (1 - discount)
    order['total'] = total
    order['items'] = items
    db.save_order(order)
    email_service.send_confirmation(order['email'], total)

Looks fine, right? There are at least three real bugs here, and none of them are visible without tracing across function boundaries:

get_discount can return None for invalid or expired coupons. 1 - None raises TypeError. The order is never saved — but the user might assume it was, because no exception is logged at the call site.
An empty items list silently produces a $0.00 order. sum([]) returns 0. The order is saved and a confirmation email is sent. No invariant catches this.
If email_service.send_confirmation raises, the database connection is never explicitly released. Under sustained SMTP failure, the pool exhausts.

A linter can't see any of this. A type checker without strict Optional annotations can't either. And in my experience, plain LLM code review catches maybe one of the three on a good day — usually the most surface-level one.

Why AI reviewers miss interprocedural bugs

A 2026 paper, Agentic Code Reasoning (Ugare & Chandra), measured this directly. When LLMs are asked to review code with unstructured chain-of-thought, they catch interprocedural bugs at 76–78% accuracy. When the same models are forced to follow a structured reasoning template — stating premises explicitly before tracing execution — accuracy jumps to 87–93%.

The gap isn't capability. It's discipline. Without structure, the model pattern-matches on what the code looks like and anchors on the happy path. With structure, it has to actually trace what happens when assumptions break.

The Iron Law: four sections per finding

I built a small open-source project called Logic-Lens that operationalizes this methodology. It's a plugin that works with Claude Code, Codex CLI, and Gemini CLI. The core idea: no finding is reported unless it has all four of these sections.

Premises — every assumption about name resolution, types, and preconditions, stated explicitly.
Trace — the actual execution path, step by step, crossing function boundaries.
Divergence — the exact point where a premise breaks and what happens after.
Remedy — a fix that addresses the divergence, not its symptom.

For the process_order example above, here's an abbreviated version of what Logic-Lens produces for the first finding:

🔴 L6 — Callee Contract Mismatch: get_discount may return None

Premises: coupon_service.get_discount(code) is assumed to always return a numeric discount rate between 0 and 1.

Trace: discount_code is truthy → get_discount(discount_code) is called → result assigned to discount → total * (1 - discount) is evaluated.

Divergence: get_discount returns None for expired or invalid codes (documented in its docstring). When discount is None, 1 - None raises TypeError. The call reaches db.save_order only on the happy path.

Remedy: Check if discount is not None: before applying. Or have get_discount raise a typed InvalidCouponError that the caller handles explicitly.

The difference from "this looks wrong" is that you can audit the reasoning. If the trace is wrong, you can point to which step is wrong. If the premise is bogus, you can correct it. The reasoning is a first-class artifact.

Six skills, one taxonomy

Logic-Lens defines six logic risk dimensions (L1–L6): Shadow Override, Type Contract Breach, Boundary Blindspot, State Mutation Hazard, Control Flow Escape, Callee Contract Mismatch. Every finding is labeled with one of these so reports are scannable.

The project ships six commands:

/logic-review — find behavioral bugs via execution tracing
/logic-explain — step-by-step execution explanation that crosses function boundaries
/logic-diff — semantic equivalence check between two versions of a function
/logic-locate — root cause localization for a failing test or crash
/logic-health — aggregate logic health score across a codebase
/logic-fix-all — autonomous audit-and-fix pipeline for an entire repo

Install on Claude Code:

/plugin marketplace add hyhmrright/logic-lens
/plugin install logic-lens@logic-lens-marketplace

Then /logic-review and paste any function. Gemini CLI and Codex CLI have equivalent install paths in the README.

What this is not

It's not a replacement for your linter — your linter still catches the syntax-level stuff much faster. It's not a static analyzer in the academic sense; it doesn't execute code or build an AST. It's a structured prompting methodology that turns the LLM into a more disciplined reviewer.

What it's good at: callee contract violations, state mutation hazards, and control flow escapes — the bugs that cause production incidents in syntax-clean, lint-passing code.

I'd love help making it better

The project is MIT-licensed: github.com/hyhmrright/logic-lens

The most valuable contribution right now is new eval test cases — especially interprocedural bugs from real production incidents you've encountered. There's an issue template that walks you through the format: paste the minimal repro, label the L1–L6 category, and describe what the four sections (Premises/Trace/Divergence/Remedy) should contain.

If you try it on real code and it catches something useful — or misses something it shouldn't — please open an issue. The benchmark suite genuinely needs more coverage, and that's where the project gets sharper over time.

If this resonates, a ⭐ on the repo helps others find it. Thanks for reading.

13 legendary investors in your terminal. No API keys, no Python, no setup.

hyhmrright — Tue, 21 Apr 2026 14:52:55 +0000

TL;DR

I took the excellent ai-hedge-fund project — a multi-agent system where AI versions of famous investors analyze stocks — and rebuilt it as a pure-prompt Claude Code skill.

No Python. No API keys. No financial data subscription. Just:

/sages NVDA

And 13 legendary investors — Buffett, Munger, Graham, Burry, Taleb, Cathie Wood, Druckenmiller, Ackman, Fisher, Lynch, Pabrai, Damodaran, Jhunjhunwala — walk into the room and argue about your stock.

Repo: https://github.com/hyhmrright/market-sages

Why rebuild it as a skill?

ai-hedge-fund is brilliant, but to run it you need a Python environment, multiple LLM API keys, a paid financial data API, and some patience with setup. That's a high bar for the "I just want to hear what Buffett thinks about NVDA on a Tuesday night" crowd — which is most of us.

Claude Code skills are basically a single markdown file that teaches Claude a new trick. That made me wonder: how much of ai-hedge-fund's value is in the orchestration code, and how much is in the personas and frameworks?

Turns out: a lot of the magic is in the frameworks. And frameworks compress beautifully into prompts.

What it looks like

╔══════════════════════════════════╗
║ 🧠 Warren Buffett                ║
║ Signal: NEUTRAL                  ║
║ Confidence: 55%                  ║
║ Reasoning: Exceptional moat      ║
║ (gaming ecosystem), but current  ║
║ P/E leaves no margin of safety.  ║
╚══════════════════════════════════╝

╔══════════════════════════════════╗
║ 🧠 Michael Burry                 ║
║ Signal: BEARISH                  ║
║ Confidence: 72%                  ║
║ Reasoning: FCF yield ~1.8%,      ║
║ EV/EBIT ~80x — no deep value     ║
║ here, this is momentum not math. ║
╚══════════════════════════════════╝

... (11 more sages)

╔══════════════════════════════════════════════╗
║ 🏦 PORTFOLIO MANAGER — FINAL VERDICT         ║
║ Action: WATCH                                ║
║ Conviction: MEDIUM                           ║
║ Entry Strategy: Wait for 20-25% pullback     ║
╚══════════════════════════════════════════════╝

Each sage has their own signal rules, valuation lens, and voice. Buffett will talk about moats and owner earnings. Burry will quote EV/EBIT and FCF yield. Taleb will refuse to give you a price target and lecture you about tail risk instead.

The design choices that mattered

1. Signal rules per investor, not one shared rubric.
Buffett's BULLISH is not Cathie Wood's BULLISH. If you give every agent the same "how to decide" rubric, they all sound the same. Each sage has their own thresholds (e.g., Pabrai wants downside <10% before even considering an idea).

2. Voice style is part of the spec.
Munger should be blunt. Fisher should be meticulous. Damodaran should sound like a professor. Specifying tone explicitly makes the output way more readable — you can scan 13 opinions because they don't blur together.

3. A "Portfolio Manager" synthesis agent at the end.
13 opinions is noise unless someone reconciles them. The final agent weighs confidence, flags disagreement clusters, and outputs an actionable verdict.

4. Let users paste fresh data.
LLMs have stale training data. So the skill explicitly tells Claude: if the user pastes financial figures or news, trust those over training knowledge.

/sages AAPL
Revenue: $391B (+2% YoY)
Net Income: $94B
FCF: $107B
P/E: 28x, EV/EBITDA: 22x

5. Cross-CLI portability.
The same skill.md works in Claude Code. I also wrote thin adapters (AGENTS.md, GEMINI.md) so it runs in Codex CLI and Gemini CLI. One prompt, three ecosystems.

Install (30 seconds)

Claude Code (recommended):

/plugin marketplace add hyhmrright/market-sages
/plugin install market-sages@market-sages-marketplace

Then: /sages AAPL

Codex CLI:

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo hyhmrright/market-sages --path skills --name market-sages

Gemini CLI:

/extensions install https://github.com/hyhmrright/market-sages

Any other LLM: copy skill.md as your system prompt.

Fun things to try

/sages compare AAPL MSFT GOOG META AMZN
/sages TSLA --value
/sages NVDA @buffett @burry @taleb
Review my portfolio: 40% AAPL, 30% NVDA, 20% TSLA, 10% BTC

Caveats (real ones)

Not financial advice. This is an educational/entertainment tool.
LLMs hallucinate numbers. Paste real data for anything serious.
These are AI impressions of how these investors think, not the actual investors.

Credit

Huge credit to @virattt and ai-hedge-fund for the original concept. Market Sages is a lighter, prompt-only sibling — if you want full multi-agent orchestration with real data pipelines, use ai-hedge-fund.

Repo + docs (中文 / 日本語 / 한국어 included): https://github.com/hyhmrright/market-sages

If it helps you think more clearly about a stock, a GitHub star is appreciated 🌟

Which sage would you add? I'm thinking about Soros (reflexivity) or Howard Marks (cycles) next — curious what you'd want to see in the council.

Show DEV: brooks-lint — an AI code reviewer that cites Fowler, Martin, and Brooks

hyhmrright — Thu, 16 Apr 2026 16:20:33 +0000

I gave an AI code reviewer a PaymentProcessor class — seven services injected, payment + fraud + inventory + notifications all in one 60-line method.

Here's what it flagged:

🔴 Change Propagation — Seven-service constructor signals a God Class in formation

Source: Fowler — Refactoring — Divergent Change; Martin — Clean Architecture — SRP

Consequence: This class will change for at least four independent reasons. Each change is a merge conflict waiting to happen.

Remedy: Introduce FraudCheckService, InventoryDeductionService, PaymentNotifier. PaymentProcessor then injects 3 services, not 7.

Not "this is bad." Here's which book explains why, what breaks if you ignore it, and how to fix it.

That's brooks-lint — an open-source plugin for Claude Code, Codex CLI, and Gemini CLI.

⭐ github.com/hyhmrright/brooks-lint · MIT · v1.0.0

Why I Built It

ESLint flags unused variables. Complexity checkers count branches. SonarQube tracks duplication percentages. All useful. None of them answer the question a senior engineer actually asks:

"What architectural principle is this violating, and what happens if we ignore it?"

I've spent years reading the classics — Fowler, Martin, Evans, Brooks, Ousterhout, McConnell. Each book has a chapter that makes you think "I've seen this exact failure before." But the insight stays locked in the book.

brooks-lint is an attempt to make that insight executable.

Every finding follows the same shape:

Symptom → Source → Consequence → Remedy

Symptom is what the linter sees
Source is the book + chapter it comes from
Consequence is what breaks in six months if you ignore it
Remedy is a concrete refactor

The Six Decay Risks

After synthesizing twelve books, six patterns kept appearing as root causes of software decay:

Code	Risk	Core Insight
R1	Cognitive Overload	Mental load exceeds working memory → mistakes and avoidance
R2	Change Propagation	One change forces unrelated changes elsewhere
R3	Knowledge Duplication	Same fact in two places → they diverge
R4	Responsibility Rot	One module does too many things
R5	Dependency Disorder	Modules depend on modules that depend on modules…
R6	Domain Model Distortion	Code doesn't speak the business's language

There are also six test-space variants (T1–T6) covering test brittleness, mock abuse, coverage theater, and more.

The Twelve Books

Book	Author	Risks
The Mythical Man-Month	Frederick Brooks	R2, R4, R5
Code Complete	Steve McConnell	R1, R4
Refactoring	Martin Fowler	R1, R2, R3, R4, R6
Clean Architecture	Robert C. Martin	R2, R5
The Pragmatic Programmer	Hunt & Thomas	R2, R3, R4, R5, T2, T3
Domain-Driven Design	Eric Evans	R1, R3, R6
A Philosophy of Software Design	Ousterhout	R1, R4
Software Engineering at Google	Winters et al.	R2, R5
xUnit Test Patterns	Meszaros	T1, T2, T4
The Art of Unit Testing	Osherove	T1, T2, T3
Working Effectively with Legacy Code	Feathers	T3, T4, T5
Unit Testing: Principles, Practices, Patterns	Khorikov	T1, T2, T6

The books agree more than they disagree. Fowler's Divergent Change smell, Martin's Single Responsibility Principle, and Evans's Bounded Context are all describing the same underlying failure from different angles.

Five Review Modes

/brooks-review   → PR code review (diff-focused)
/brooks-audit    → Architecture audit
/brooks-debt     → Tech debt assessment
/brooks-test     → Test quality review
/brooks-health   → Codebase health dashboard with score

Works on Claude Code, Codex CLI, and Gemini CLI.

Install in 60 Seconds

Claude Code:

/plugin install brooks-lint@brooks-lint-marketplace/brooks-audit```
{% endraw %}
**Codex CLI:**
{% raw %}

codex plugin install hyhmrright/brooks-lint


plaintext

**Gemini CLI:**

gemini extension install hyhmrright/brooks-lint




Source: [github.com/hyhmrright/brooks-lint](https://github.com/hyhmrright/brooks-lint)

---

## The Hard Part: False Positives

A 60-line function in a data-migration script isn't the same as a 60-line function in a payment handler. The tool needed to know **when not to flag something** — which meant reading the exception clauses in each book more carefully than expected.

The benchmark suite now has **49 scenarios**, including explicit false-positive cases that must not be flagged. That's probably the most useful artifact in the repo — it forces the skill to be calibrated, not just pattern-matching.

---

## I'd Love Your Help

v1.0 is out, but a linter grounded in books is only as good as the communities that stress-test it.

**Three specific ways you can help:**

1. **Try it on a real repo** and open an issue if a finding feels wrong — false positives are the highest-priority bug class
2. **Propose a 13th book** — if there's a classic that covers a failure mode R1–R6 misses, tell me which chapter
3. **Share a code smell** you see constantly in the comments — I'll run brooks-lint on a representative example and post the raw output

⭐ [github.com/hyhmrright/brooks-lint](https://github.com/hyhmrright/brooks-lint)

**Which of the six risks (R1–R6) do you hit most often?** Drop a comment — happy to dig into specific examples.

---

## Also From Me

If brooks-lint's *why-this-matters* framing resonated, I also built **logic-lens** — same philosophy but focused on execution-time behavioral bugs (callee contract mismatches, control flow escapes, boundary blindspots) rather than architectural decay:

[Why AI Code Review Misses Logic Bugs — And How Structured Execution Tracing Fixes It](https://dev.to/hyhmrright/why-ai-code-review-misses-logic-bugs-and-how-structured-execution-tracing-fixes-it-3n0p)

The two tools cover different failure modes and work well together: **logic-lens** catches runtime behavioral bugs via execution tracing; **brooks-lint** diagnoses architectural decay against 12 classic books.

I gave Claude the same code review twice. It missed a SQL injection the second time. So I encoded 12 engineering books into it.

hyhmrright — Wed, 15 Apr 2026 09:13:10 +0000

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

Fifty years later, Brooks was still right. And so was the rest of my shelf.

I ran the same code review with Claude twice.

First time: caught the SQL injection, flagged separation of concerns. Solid review.
Second time: focused on naming conventions. Missed the injection entirely.

Same code. Same model. Completely different results.

That's not a Claude problem. That's a consistency problem. And it's fixable — if you give the model a framework to work from.

So I encoded 12 classic engineering books into a Claude Code skill. Here's what happened.

The Problem

Most code quality tools count lines and cyclomatic complexity. That's useful, but it misses the deeper problems: architectural drift, knowledge silos, domain model distortion — the issues that slow teams down for months before anyone notices.

Meanwhile, the software engineering classics have had answers to these problems for decades. Brooks, Fowler, Martin, McConnell, Evans, Ousterhout — twelve books, fifty years of hard-won wisdom. The insights haven't changed. We just stopped encoding them consistently.

What I Built

brooks-lint is a Claude Code skill (also works with Gemini CLI and Codex CLI) that diagnoses code against twelve decay risk dimensions synthesized from 12 classic engineering books, producing structured findings with book citations, severity labels, and concrete remedies every time.

The 12 Books

Book	Author
The Mythical Man-Month	Frederick Brooks
Code Complete	Steve McConnell
Refactoring	Martin Fowler
Clean Architecture	Robert C. Martin
The Pragmatic Programmer	Hunt & Thomas
Domain-Driven Design	Eric Evans
A Philosophy of Software Design	John Ousterhout
Software Engineering at Google	Winters, Manshreck & Wright
xUnit Test Patterns	Gerard Meszaros
The Art of Unit Testing	Roy Osherove
How Google Tests Software	Whittaker, Arbon & Carollo
Working Effectively with Legacy Code	Michael Feathers

The Six Production Code Decay Risks

Risk	Diagnostic Question
🧠 Cognitive Overload	How much mental effort to understand this?
🔗 Change Propagation	How many unrelated things break on one change?
📋 Knowledge Duplication	Is the same decision expressed in multiple places?
🌀 Accidental Complexity	Is the code more complex than the problem?
🏗️ Dependency Disorder	Do dependencies flow in a consistent direction?
🗺️ Domain Model Distortion	Does the code faithfully represent the domain?

Every finding follows the same chain: Symptom → Source (book + chapter) → Consequence → Remedy

The Six Test-Suite Decay Risks (New in v0.5)

brooks-lint now also audits your test suite against six test-space decay risks sourced from xUnit Test Patterns, The Art of Unit Testing, How Google Tests Software, and Working Effectively with Legacy Code:

Risk	Diagnostic Question
🔍 Test Obscurity	Can you understand what this test verifies at a glance?
🧱 Test Brittleness	Does this test break when unrelated implementation details change?
📋 Test Duplication	Are the same scenarios covered in multiple places?
🎭 Mock Abuse	Are mocks hiding real design problems?
📊 Coverage Illusion	Does high coverage give false confidence?
🏗️ Architecture Mismatch	Do tests reflect the production architecture?

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

🔴 Change Propagation — Single Method Changes for Four Unrelated Business Reasons
Symptom: update_profile performs profile updates, email 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.
Remedy: Extract NotificationService, LoyaltyService, and UserCacheInvalidator.

🔴 Domain Model Distortion — Silent Logic Bug: Email Notification Never Fires
Symptom: user['email'] = email overwrites the old value before the comparison —
         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.
Remedy: Capture old_email = user['email'] before any mutation.

(+ 6 more findings including SQL injection, dependency disorder, magic numbers)

Architecture Audit with Dependency Graph (v0.6)

In Mode 2, brooks-lint generates a Mermaid dependency graph color-coded by severity — red = Critical, yellow = Warning, green = clean. It renders natively in GitHub, VS Code, and Notion.

Four Modes

Command	Short Form	Action
`/brooks-lint:brooks-review`	`/brooks-review`	PR-level code review
`/brooks-lint:brooks-audit`	`/brooks-audit`	Architecture audit with Mermaid dependency graph
`/brooks-lint:brooks-debt`	`/brooks-debt`	Tech debt assessment with prioritized roadmap
`/brooks-lint:brooks-test`	`/brooks-test`	Test suite health review

Benchmark Results

Tested across 3 real-world scenarios (PR review, architecture audit, tech debt):

Criterion	brooks-lint	Plain Claude
Structured findings	✅ 100%	❌ 0%
Book citations	✅ 100%	❌ 0%
Severity labels	✅ 100%	❌ 0%
Health Score (0–100)	✅ 100%	❌ 0%
Overall pass rate	94%	16%

The gap isn't what Claude can find — it's what it consistently finds, with traceable evidence and actionable remedies every time.

How It Compares

	brooks-lint	ESLint/Pylint	GitHub Copilot	Plain Claude
Structured diagnosis chain	✅	❌	❌	❌
Traces findings to classic books	✅	❌	❌	❌
Architecture-level insights	✅	❌	~	~
Domain model analysis	✅	❌	❌	~
Zero config, no plugins	✅	❌	✅	✅
Works with any language	✅	❌	✅	✅

brooks-lint doesn't replace your linter. It catches what linters can't.

Installation

Claude Code (Recommended)

/plugin marketplace add hyhmrright/brooks-lint

Gemini CLI

/extensions install https://github.com/hyhmrright/brooks-lint

Codex CLI

$brooks-review  # skills trigger automatically on code quality discussions

Manual Install

cp commands/*.md ~/.claude/commands/
cp -r skills/ ~/.claude/skills/brooks-lint

Configuration (v0.7)

Place a .brooks-lint.yaml in your project root to customize behavior:

version: 1
disable:
  - T5  # skip coverage metrics check
severity:
  R1: suggestion  # downgrade Cognitive Overload for this domain
ignore:
  - "**/*.generated.*"
  - "**/vendor/**"

GitHub: https://github.com/hyhmrright/brooks-lint — MIT licensed, free to use.

AI can help you write code faster, but it can't tell you whether you're building a cathedral or a tar pit. brooks-lint bridges that gap.

If you've used AI for code reviews, I'm curious: what's your biggest frustration with consistency? Drop it in the comments — I'd love to hear what decay risks you're seeing most.

If this was useful, a ❤️ or unicorn helps others find it.

I built a Claude Code plugin that anchors code reviews to 6 classic SE books

hyhmrright — Mon, 30 Mar 2026 12:49:28 +0000

If you've used Claude Code for code reviews, you've probably noticed something: the feedback is smart, but it's vague. "This function is too long." "Consider breaking this up." Great — but why? And what's the actual risk if you don't?

I built brooks-lint to fix this. It's a Claude Code plugin that anchors every finding to a specific chapter in one of six classic software engineering books.

The Problem with AI Code Reviews

Generic AI reviews are good at spotting syntax issues and surface-level smells. But they struggle to explain consequence — why a particular pattern is dangerous in the long run, not just aesthetically displeasing.

The result: developers nod, maybe fix the obvious stuff, and move on. The deeper structural decay continues.

What brooks-lint Does Differently

Every finding follows a four-part structure I call the Iron Law:

Symptom   → what the code is doing
Source    → which book + chapter describes this exact pattern
Consequence → what breaks if you ignore it
Remedy    → concrete fix

Example output:

Symptom: UserService has 847 lines and handles auth, billing, notifications, and user CRUD.

Source: Clean Architecture, Ch. 7 — SRP violation; responsibilities should have separate reasons to change.

Consequence: Any change to billing logic risks breaking auth; test isolation becomes impossible.

Remedy: Extract BillingService and NotificationService; keep UserService focused on identity only.

No vague advice. Just: here's the book, here's the chapter, here's exactly what goes wrong.

The Six Source Books

The plugin draws from six foundational texts:

Book	Focus
The Mythical Man-Month	Project complexity, conceptual integrity
Clean Code + Refactoring	Code-level smells and refactoring patterns
Clean Architecture	Dependency rules, component boundaries
Code Complete	Implementation craft, construction quality
The Pragmatic Programmer	DRY, orthogonality, adaptability
Domain-Driven Design	Ubiquitous language, bounded contexts

Four Review Modes

/brooks-lint:brooks-review   # PR review — what changed and what it risks
/brooks-lint:brooks-audit    # Architecture audit — structural health of the whole system
/brooks-lint:brooks-debt     # Tech debt — classify and prioritize what to fix
/brooks-lint:brooks-test     # Test quality — coverage gaps, fragile tests, wrong abstractions

The test quality mode (brooks-test) draws from xUnit Test Patterns, The Art of Unit Testing, and Google's Software Engineering book — it flags things like over-mocking, test logic duplication, and tests that verify implementation instead of behavior.

Eval Results

I ran an evaluation comparing reviews with and without the plugin on a set of intentionally seeded codebases:

94% of findings included a book citation and structured consequence analysis with the plugin
16% of findings had equivalent depth without it

The plugin doesn't make Claude smarter — it makes Claude accountable. When every finding has to cite a chapter, hand-wavy feedback can't survive.

Install

# Via plugin marketplace (recommended)
/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace

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

Why "Brooks"?

Fred Brooks wrote The Mythical Man-Month in 1975. Most of what he described — conceptual integrity, the second-system effect, the surgical team model — still shows up every week in production code. The plugin is named after him as a reminder that the hard problems in software aren't new, and the best answers to them are already written down.

GitHub: hyhmrright/brooks-lint

Happy to answer questions about how the skill detection works or how I structured the decay risk taxonomy.

Update (March 2026): Now on Gemini CLI Too

brooks-lint v0.5.2 now supports Gemini CLI as a first-class platform, in addition to Claude Code.

Gemini CLI install:

/extensions install https://github.com/hyhmrright/brooks-lint

Claude Code install:

/plugin marketplace add hyhmrright/brooks-lint
/plugin install brooks-lint@brooks-lint-marketplace

Both platforms use the same skill files — same decay risk framework, same Iron Law diagnostics, same book citations. The only difference is the entry point configuration. If you use both tools, one install covers both.

The extension is also listed on the official Gemini CLI extension gallery.