Improve

---
name: improve
description: "Critique any plan, architecture decision, or implementation approach. Research-first — gives SHIP IT / IMPROVE IT / RETHINK IT / KILL IT verdict. Usage: /improve <topic>"
---

# Skill: /improve
# Technical Design Critic

Research-first — never critique from zero.

```
subject → find best references → extract patterns → critique → verdict + fixes
```

---

## When to run proactively

Suggest `/improve` when:
- A design proposal is being elevated to active work
- A new interface or API contract is being designed
- A non-trivial architectural decision needs validation before implementation

Say: "This is new design — want me to run /improve on it before we build?"

---

## Procedure

### Step 1 — Understand the subject

- What is it? (interface design, algorithm, API shape, data model, config structure)
- What problem does it solve?
- What's the current proposal?

### Step 2 — Research

**Internal first:**
- Read `CLAUDE.md` for architecture constraints and conventions
- Read any proposal or decision files (`.proposals.md`, `docs/architecture.md`, ADRs)
- Read the affected source files directly

**External if needed:** look for established patterns in the domain (official docs, RFCs,
well-known library conventions). Reference specific sources — not vague "best practices."

### Step 3 — Structured critique

#### 3A — Architecture alignment
- Does this respect the project's layer boundaries and separation of concerns?
- Does it follow Dependency Inversion (interfaces defined near consumers)?
- Does it introduce circular dependencies or tight coupling?

#### 3B — Flaws and risks
- What can go wrong?
- Worst-case: data corruption, silent failure, resource leak, blocked request, security hole?
- What assumptions are being made that could be wrong?

#### 3C — Best-practice gap
- How does this compare to established patterns in this domain?
- What are production systems doing that this is missing?
- What is being overengineered?

#### 3D — Simplicity (YAGNI / KISS)
- Can this be simpler?
- What is the minimum viable version?
- What can be cut without losing core value?

#### 3E — Testability
- Can this be tested in isolation (without real DB, external API, network)?
- Are the interfaces narrow enough to mock easily?

#### 3F — Security
- Any user input reaching file paths, shell, or external calls unvalidated?
- Any new configuration that could leak secrets?

### Step 4 — Improvement proposals

For each issue found:

```
ISSUE     : [what's wrong or missing]
REFERENCE : [who does it better and how]
FIX       : [specific change to make]
IMPACT    : [what improves]
EFFORT    : Low / Medium / High
```

### Step 5 — Verdict and score

| Dimension | Score (1–10) | Notes |
|-----------|-------------|-------|
| Architecture alignment | | |
| Correctness | | |
| Simplicity | | |
| Best-practice match | | |
| Testability | | |
| Security | | |
| **Overall** | | |

- **SHIP IT** (8+) — good enough, minor tweaks only
- **IMPROVE IT** (5–7) — solid foundation, fix specific issues before building
- **RETHINK IT** (3–4) — core approach has problems, consider alternatives
- **KILL IT** (<3) — doesn't serve the goals, redirect energy elsewhere

### Step 6 — Apply or propose

- **SHIP IT / IMPROVE IT** → apply fixes directly.
- **RETHINK IT** → present 2–3 alternatives with pros/cons and references.
- **KILL IT** → explain clearly why; suggest where energy should go instead.

---

## Rules

- Research before critiquing. Opinions without references are noise.
- Reference specific sources — "RFC 7231 §6.5" not "REST best practices."
- Score honestly. Inflated scores waste time.
- If the subject has project-specific context (CLAUDE.md conventions, known constraints),
  apply it — don't critique things that are intentional project decisions.