target_path = $ARGUMENTS
If no target path provided, ask for one. This skill requires a concrete scope — "the whole repo" produces shallow findings.
Purpose
Every line of code is a liability — read, understood, maintained, debugged, migrated. This skill makes maintenance cost visible and challenges code that doesn't earn its keep.
This is not a correctness review or a style review. The question: should this code exist at all, and if so, at this size?
Reconnaissance
Before spawning reviewers, build the brief they all share:
- Map the scope — file count, total LOC, directory structure, entry points
- Identify the feature set — what user-facing capabilities does this code provide? List concretely.
- Detect the stack — languages, frameworks, key dependencies
- Find existing docs — any stated purpose or architecture rationale
Teammates
Spawn all three from ${CLAUDE_SKILL_DIR}/agents/ in parallel. All are read-only — analysis only, no edits. Each gets the full brief plus all file paths in the target.
| Teammate |
Agent file |
Lens |
| YAGNI Enforcer |
yagni.md |
What here solves a problem nobody actually has? |
| Cost Auditor |
cost-auditor.md |
What's the maintenance burden vs. the value delivered? |
| Alternatives Scout |
alternatives.md |
What existing libraries, services, or simpler architectures could replace this? |
Synthesis
Credibility Filter
Discard findings that fail any of these:
- Evidence-based — references specific files, line counts, complexity metrics, or usage patterns. Speculation is not a finding.
- Proportionate — a 30-line utility being "unnecessary" isn't worth reporting; a 500-line abstraction wrapping a 10-line operation is. The model's instinct is to report everything it finds — resist this. Only surface findings where the cost/value mismatch is material.
- Alternative-bearing — "delete this" is not actionable. "Replace this 400-line custom parser with
{library}" is.
- Honest about migration cost — removing/replacing code has a cost too. Acknowledge it.
Discard findings where the reviewer misunderstood the feature's purpose. Discard findings about code that's necessary but could be slightly shorter — that's refactoring territory, not razor territory.
Severity
| Level |
Meaning |
| CUT |
Maintenance cost clearly exceeds value. Concrete alternative exists. |
| SHRINK |
Feature is justified but implementation is 3-10x larger than necessary. |
| QUESTION |
Unclear whether this earns its keep. Needs user context — state the specific question. |
| KEEP |
Reviewers challenged it and it survived. Note what was challenged and why it stood — this builds trust that the review is fair, not just aggressive. |
Report Structure
- Scope summary — what was reviewed (files, LOC, features)
- Headline — one sentence: lean, reasonable, or bloated?
- CUT list — what to remove/replace, with alternatives and estimated LOC reduction
- SHRINK list — what to simplify, with the simpler approach sketched
- QUESTION list — what needs user context (state the specific question)
- KEEP list — what survived the challenge
- If starting fresh — knowing what we know now, what's the minimal architecture delivering the same capabilities?
Stop after the report. Do not implement changes unless asked.
Failure Modes
- Drive-by severity inflation. The model tends to rate everything CUT or SHRINK to look thorough. A report with zero KEEP items signals the review failed, not that the code is bad. Calibrate: most well-maintained codebases have more KEEP than CUT.
- Ignoring migration cost. "Replace with library X" sounds clean until you account for the API surface, test rewrite, and behavior differences. Every recommendation must acknowledge what the switch costs.
- Misreading domain code as over-engineering. Domain-specific abstractions (workflow engines, rule systems, protocol handlers) look like speculative architecture to a generalist reviewer. When code serves a domain you don't fully understand, classify as QUESTION, not CUT.
1---2name: razor3description: Use when questioning whether code in a folder should exist, whether a solution is over-engineered, or where maintenance cost can be cut.4---5
6target_path = $ARGUMENTS
7
8If no target path provided, ask for one. This skill requires a concrete scope — "the whole repo" produces shallow findings.
9
10## Purpose
11
12Every line of code is a liability — read, understood, maintained, debugged, migrated. This skill makes maintenance cost visible and challenges code that doesn't earn its keep.
13
14This is not a correctness review or a style review. The question: **should this code exist at all, and if so, at this size?**
15
16## Reconnaissance
17
18Before spawning reviewers, build the brief they all share:
19
201. Map the scope — file count, total LOC, directory structure, entry points
212. Identify the feature set — what user-facing capabilities does this code provide? List concretely.
223. Detect the stack — languages, frameworks, key dependencies
234. Find existing docs — any stated purpose or architecture rationale
24
25## Teammates
26
27Spawn all three from `${CLAUDE_SKILL_DIR}/agents/` **in parallel**. All are **read-only** — analysis only, no edits. Each gets the full brief plus all file paths in the target.
28
29| Teammate | Agent file | Lens |
30|----------|-----------|------|
31| YAGNI Enforcer | `yagni.md` | What here solves a problem nobody actually has? |
32| Cost Auditor | `cost-auditor.md` | What's the maintenance burden vs. the value delivered? |
33| Alternatives Scout | `alternatives.md` | What existing libraries, services, or simpler architectures could replace this? |
34
35## Synthesis
36
37### Credibility Filter
38
39Discard findings that fail any of these:
40
41- **Evidence-based** — references specific files, line counts, complexity metrics, or usage patterns. Speculation is not a finding.
42- **Proportionate** — a 30-line utility being "unnecessary" isn't worth reporting; a 500-line abstraction wrapping a 10-line operation is. The model's instinct is to report everything it finds — resist this. Only surface findings where the cost/value mismatch is material.
43- **Alternative-bearing** — "delete this" is not actionable. "Replace this 400-line custom parser with `{library}`" is.
44- **Honest about migration cost** — removing/replacing code has a cost too. Acknowledge it.
45
46Discard findings where the reviewer misunderstood the feature's purpose. Discard findings about code that's necessary but could be slightly shorter — that's refactoring territory, not razor territory.
47
48### Severity
49
50| Level | Meaning |
51|-------|---------|
52| **CUT** | Maintenance cost clearly exceeds value. Concrete alternative exists. |
53| **SHRINK** | Feature is justified but implementation is 3-10x larger than necessary. |
54| **QUESTION** | Unclear whether this earns its keep. Needs user context — state the specific question. |
55| **KEEP** | Reviewers challenged it and it survived. Note what was challenged and why it stood — this builds trust that the review is fair, not just aggressive. |
56
57### Report Structure
58
591. **Scope summary** — what was reviewed (files, LOC, features)
602. **Headline** — one sentence: lean, reasonable, or bloated?
613. **CUT list** — what to remove/replace, with alternatives and estimated LOC reduction
624. **SHRINK list** — what to simplify, with the simpler approach sketched
635. **QUESTION list** — what needs user context (state the specific question)
646. **KEEP list** — what survived the challenge
657. **If starting fresh** — knowing what we know now, what's the minimal architecture delivering the same capabilities?
66
67**Stop after the report. Do not implement changes unless asked.**
68
69### Failure Modes
70
71- **Drive-by severity inflation.** The model tends to rate everything CUT or SHRINK to look thorough. A report with zero KEEP items signals the review failed, not that the code is bad. Calibrate: most well-maintained codebases have more KEEP than CUT.
72- **Ignoring migration cost.** "Replace with library X" sounds clean until you account for the API surface, test rewrite, and behavior differences. Every recommendation must acknowledge what the switch costs.
73- **Misreading domain code as over-engineering.** Domain-specific abstractions (workflow engines, rule systems, protocol handlers) look like speculative architecture to a generalist reviewer. When code serves a domain you don't fully understand, classify as QUESTION, not CUT.
majiayu000