Clean MVP: $ARGUMENTS

MVP-stage discipline: if code is not reachable from a live entry point, delete it. No back-compat shims, no deprecated aliases, no "just in case" abstractions — anything needed later can be recovered from git history. This skill SWEEPS and APPLIES deletions; it does not redesign what stays (/refactor) and does not judge architecture (/arch-health).

$ARGUMENTS optionally scopes the sweep to a file, directory, or module; empty = the whole source tree per PROJECT.md → Architecture.

Phase 0 — Load profile

1. Read .claude/PROJECT.md — Commands (test, lint, format), Architecture (source layout, layers, entry points), and Conventions notes. If missing or still TEMPLATE, fall back to the root CLAUDE.md (always in context) when it carries the commands/architecture — note you're running without a kit profile; only if neither has them, STOP and tell the user to run /bootstrap first.
2. Read the installed rules in .claude/rules/* whose paths match the sweep scope — they define the stack's idioms (module-export conventions, DI/registry patterns, intentional extension points). Use them; never assume a stack.
3. If CONTEXT.md exists, read it so findings are named in the project's vocabulary.

Phase 1 — Sweep categories

Scan the scope for each category. Grep-driven; read a file in full before judging its symbols.

1. Unused imports/symbols — run the lint command from PROJECT.md if it detects unused imports; otherwise grep per symbol.
2. Dead functions/classes/types — definitions with zero call sites outside their own file. A test-only caller means: check whether the tested behavior still matters; if not, both go.
3. Back-compat shims & legacy wrappers — deprecated/legacy/compat markers, old-name aliases, thin wrappers that only forward to a newer unit, re-exports kept "for compatibility", deprecation-warning calls, _old/_legacy names.
4. Stale TODO/FIXME/HACK/XXX/TEMP — done → delete the comment; actionable now → fix or file to the backlog location in PROJECT.md; the hack itself removable → remove code + comment.
5. Commented-out code — delete; git history is the archive.
6. YAGNI abstractions — single-use helpers → inline; single-implementation interfaces → concrete (unless a documented extension point per the rules/ADRs); never-varied config options → hardcode; feature flags pinned to one value → remove flag + dead branch.
7. Unreachable code — statements after return/throw/break, branches that can never run, handlers for errors the guarded block cannot produce.
8. Empty & pass-through files — value-free re-export files (per the stack's module-export idiom in the installed rules), empty modules, 100%-delegating wrappers, empty test files.

Loop until dry. Dead code has no known count, and each deletion can orphan more code (the sole caller of X was itself dead). So the sweep iterates: after applying a batch (Phase 5), re-run the categories over the affected areas — freshly orphaned symbols are new findings. Stop when 2 consecutive passes surface nothing new. Dedup each pass against everything already seen (including findings refuted by the Proof-of-Deadness gate or by the user) — not just against deleted items, or refuted candidates re-surface every pass and the loop never converges. Track the seen-set as symbol@file in a scratch list.

Phase 2 — Proof of Deadness

Nothing counts as dead until ALL of these pass. Record the evidence per finding:

• Zero references: grep the symbol/file name across the whole source tree — no call sites, imports, or mentions outside the definition itself.
• Not an entry point: not registered as a CLI command, route, job, handler, or plugin per the entry points named in PROJECT.md → Architecture.
• Not dynamically referenced: grep for the name as a string — reflection/dynamic dispatch, DI-container or registry keys, config/serialized-data keys, template references.
• Not exported surface: not part of the module's public export per the stack's export idiom (installed rules) with plausible external consumers.
• Not fresh WIP: git log --oneline -10 -- <file> shows no recent work suggesting the code is mid-flight rather than abandoned.

Any box unchecked → the finding is at best Medium/High risk and must pass the Decision Gate; if evidence is genuinely ambiguous, keep it and note why.

Phase 3 — Findings table (before ANY deletion)

Present the full table BEFORE editing anything — evidence first, deletions second:

Risk levels:

• Low — zero references anywhere, all proof boxes checked → may proceed after the table.
• Medium — referenced only by tests, or indirectly via string/dispatch patterns.
• High — user-visible (command, endpoint, documented behavior), exported surface, or plausibly referenced dynamically/by config.

Phase 4 — Decision Gate

For every Medium/High finding, confirm via AskUserQuestion before deleting — batched (one question per group of related findings, options like "delete all / keep these / review one by one"), never one prompt per item. Low-risk findings may proceed without a prompt, but only after the Phase-3 table was shown. Never auto-delete anything user-visible.

Phase 5 — Apply & verify

1. Apply approved deletions with Edit (whole files: remove via Bash), smallest safe batches first.
2. Run the format command from PROJECT.md (skip and note if n/a).
3. Run the test command from PROJECT.md. Failures mean the "dead" code was live — restore the offending batch, mark the finding refuted, and investigate before continuing.
4. No test command (n/a): say so explicitly — nothing pins behavior, so EVERY batch (including Low-risk) needs the user's explicit go-ahead via the Decision Gate, and recommend /test to add coverage first.
5. Sanity check: the diff should be net-negative lines; a sweep that grows the codebase went wrong.

Persist to the artifact

(Mandatory when $ARGUMENTS or the session brief names a plan, card or spec file.) Follow ../implement/reference/work-log.md. Keep a ledger on disk from the first phase and record deviations the moment they are decided. Before the final reply, append ## Clean-MVP Log — <date> — <verdict> to that file; its ### Result is the Phase-3 findings table (each row's action and proof of deadness) and the net line change. Anything you could not observe yourself goes under Re-check later, with its command and today's baseline: a post-deploy log grep, a soak count, a UI gesture. The chat output is a copy of the log, never the only record. No planning artifact → skip this section.

Finish with a copy-paste commit suggestion for the touched files, plus the plan/card file the log was appended to — explicit paths only (never -A, ., or a directory; a path stages its deletion too). Never run git add/commit/push yourself; the user runs it.

Hard rules

• Evidence before edits. The Phase-3 table with per-item Proof-of-Deadness comes BEFORE any deletion; an unproven finding is a guess, not a candidate.
• Gate the risky ones. Medium/High findings require batched AskUserQuestion confirmation — never one-by-one spam, never silent deletion of user-visible or exported surface.
• Verify, never publish. Run format + test from PROJECT.md after applying; never git add/commit — suggest the command as text.
• Facts from PROJECT.md. Commands, layout, entry points, and idioms come from the profile and installed rules — never assume a stack.
• Delete, don't improve. Restructuring survivors is /refactor's job; this skill only removes what's dead.

See also

• /refactor — cleans and improves the current diff (includes small-scale dead-code removal within changed files); this skill sweeps the whole tree and only deletes.
• /arch-health — ranks architecture-level rot (shallow modules, layer violations) and proposes; run it when the problem is design, not cruft.
• /code-review — hunts correctness/security bugs in a diff; this skill never judges correctness of what remains.