vanity-engineering-review

Reviews codebases, architectures, PRs, and technical plans for vanity engineering — code and systems built for the developer's ego, resume, or intellectual pleasure rather than delivering user or business value. Triggers on: "review this code", "is this over-engineered", "code review", "architecture review", "complexity audit", "vanity check", "is this necessary", "simplify this", "tech debt review", or any request to evaluate whether code or architecture is justified by actual requirements. Als

364stars50forksUpdated 7/30/2026

Code Review #software-quality #refactoring #code-review #technical-debt #architecture

Security Assessment

Safe(95/100)

Security Score95/100

About vanity-engineering-review

vanity-engineering-review is a diagnostic code-review skill that evaluates codebases, architectures, pull requests, and technical plans for "vanity engineering" -- code and systems built for the developer's ego, resume, or intellectual pleasure rather than to deliver user or business value. Its core premise is that the only legitimate purpose of engineering is to solve a problem someone actually has, and that complexity added beyond that (abstractions nobody traverses, microservices serving one endpoint, custom frameworks replicating existing tools, over-modeled type systems) is entropy disguised as craftsmanship. It explicitly does not oppose quality or rigour, only engineering that satisfies the builder rather than the user.

The review runs in phases. First it establishes a requirement anchor -- who uses the system, what it must do, its actual (not projected) scale, real constraints, and the maintaining team size -- because vanity complexity can only be judged against genuine need. It then runs a detection scan against a bundled detection-patterns reference, scoring each finding on a Vanity Severity scale from V0 (cosmetic) to V3 (compounding). It produces a structured assessment including a Requirement-to-Complexity Ratio, up to seven top findings with severity, rationale, and simpler alternatives, a vanity-debt estimate in maintenance hours, and one deliberately uncomfortable question. Finally it generates a project-specific kill-criteria framework from a bundled template, organized into Tier 1 hard-kill conditions, Tier 2 review triggers with a default-to-kill bias, and Tier 3 soft-go criteria that a component must earn to continue.

It targets engineers, tech leads, and reviewers doing codebase audits, PR reviews, RFC and architecture evaluations, technology-selection decisions, refactoring debates, and complexity-related post-mortems. It can also nudge activation when it detects unnecessary abstraction, premature optimization, or resume-driven technology choices in shared code. This is a read-and-reason review helper that produces assessments and frameworks rather than modifying code.

FAQ

What exactly is 'vanity engineering'?

Code, architecture, and technical decisions built to impress rather than to ship -- complexity added for the developer's ego, resume, or intellectual pleasure that increases maintenance cost without proportional user value. The skill measures the gap between what a codebase does and what it is engineered to do.

How does it score findings?

Each finding gets a Vanity Severity from V0 (cosmetic, harmless) through V1 (drag), V2 (structural), to V3 (compounding, which forces other code to be more complex and is flagged as urgent). It also computes a Requirement-to-Complexity Ratio from 1 to 10, where most production systems should score 2-4.

What are 'kill criteria' and why generate them?

Kill criteria are pre-committed conditions for shutting down a component, organized into hard-kill triggers, review triggers with a default-to-kill bias, and soft-go criteria a component must earn to survive. They counteract sunk-cost, addition bias, and effort-justification so stopping decisions become automatic and ego-independent.

When should this review be applied?

For codebase audits, pull request reviews, architecture proposals or RFCs, technology-selection decisions, refactoring plans, rebuild debates, and post-mortems where complexity contributed to failure. It can also self-nudge when it spots unnecessary abstraction or resume-driven choices in shared code.

Does it change my code?

No. It produces a structured assessment, a vanity-debt estimate, top findings with simpler alternatives, a hard question, and a project-specific kill-criteria framework. It reads and reasons about code and plans rather than editing them.