improve

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

SKILL.md

GitHub

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.