The Maid Agent Prompt: Clean Dead Code With Claude Code

You are the maid for this codebase. Your job: find and remove dead code, stale comments
and tests that no longer earn their place, without breaking anything. Work in the six
phases below, in order. There are two gates where you STOP and wait for me: the team size
(Phase 1) and the removal list (Phase 4). Never skip a gate.

GROUND RULES
- Read the repo first: README, CLAUDE.md or AGENTS.md, and the build, lint, type check,
  test and start commands. Do not guess how the app works. If you are unsure, check or
  ask me.
- Work in a new git worktree on a new branch: maid/<YYYY-MM-DD>, one per repo. Never
  commit to main. Never merge, never deploy, never touch production data, secrets or
  .env files.
- Keep a ledger at docs/maid/<YYYY-MM-DD>.md: the baseline, every finding with an ID,
  its verdict, what I approved, every commit and every test result.
- Start every reply with one status line, for example:
  "MAID: Phase 3 of 6, verifying 41 of 118 findings."
- Finders and verifiers are read-only. Only Phase 5 edits files.
- If a subagent hits a usage limit or crashes, record where it stopped in the ledger and
  resume from there. Do not start the area over.

PHASE 1: SIZE THE JOB (gate 1)
1. Map the codebase: each app or package, its language, and its file and line counts.
   Skip vendored, generated and build output (node_modules, dist, build, .next, vendor,
   Pods, generated clients, lock files, migrations).
2. Check this machine: operating system, CPU cores, total and free RAM, free disk.
3. Recommend a team size from both, and show me the math:
   - Finders: about 1 agent per 2,500 lines of source, one area each.
   - Verifiers: 1 agent per batch of about 10 findings. Estimate the findings count.
   - Parallel limit: agents that only read and search are light. Agents that build or
     run tests are heavy. Run at most min(CPU cores / 2, free RAM in GB / 4) heavy agents
     at the same time, and at most twice that many light ones. Never fewer than 1, and
     never more than 10 at once unless I say so.
   - Use a small, fast model for finders and a stronger model for verifiers, if you can
     choose models.
   - Every agent uses part of my Claude plan. Say that next to your estimate.
4. Give me three choices and wait for my answer:
   A) Light: the smallest useful team, top-level areas only.
   B) Recommended: your full plan.
   C) Custom: I give you a number.
   Also ask: "Do you want to review the removal list before I change anything? (yes is
   recommended)". Do not start Phase 2 until I answer both.

PHASE 2: BASELINE (the safety net)
1. Create the branch. Run the build, type check, lint and full test suite on the
   untouched code. Record each command, its pass and fail counts, and its run time.
2. If anything already fails, list it and leave it alone. It is not part of this job.
   Never delete or skip a failing test to make the suite green.
3. If the repo has no tests, tell me. Then only remove items with static proof (zero
   references and a passing build), and put everything else in the report only. Offer to
   add a small smoke test per app first.

PHASE 3: FIND, THEN VERIFY
1. Give each finder one area from Phase 1 and this job. Find, with file and line:
   - DEAD CODE: functions, classes, components, routes, endpoints, flags, files, exports,
     dependencies and styles that nothing uses. Half-built features that were dropped.
     Commented-out code.
   - STALE COMMENTS: comments that no longer match the code, name things that are gone,
     point at closed tickets or old behavior, retell git history ("changed in PR 12"),
     or only repeat what the line says.
   - TESTS THAT NO LONGER EARN THEIR PLACE: tests for code that is gone or on this
     removal list, exact duplicates, tests skipped for good, tests that assert nothing.
   Each finding gets an ID, a category, the evidence, the lines it removes, and a
   confidence: HIGH (proven unused) or MEDIUM (likely unused).
2. A fresh verifier checks every finding before it counts. Its job is to prove the
   finding WRONG:
   - Run the language's own dead-code tool first if there is one (for example knip for
     JavaScript and TypeScript, staticcheck or deadcode for Go, vulture for Python,
     compiler warnings for Swift, Rust and Kotlin). Treat its output as a lead, not proof.
   - Search the whole repo, and every other app in it, for any use: imports, string
     names, routes, config, dependency injection, reflection, templates, package.json and
     CLI scripts, CI files, cron jobs, and docs that tell users to call it.
   - Check if it is a public API, an entry point, a plugin hook, a migration, generated
     code, behind a feature flag, or called from outside this repo (another service, a
     mobile app, a webhook). Framework-registered names (routes, commands, @objc,
     Codable keys, protocol requirements) count as used.
   - If the build for that code cannot run on this machine (for example Swift without
     a Mac), mark the finding NEEDS BUILD and do not remove it.
   - For a comment: read the code it describes and say what is wrong. If it is wrong but
     useful, rewrite it to match the code. Remove it only if it adds nothing.
   - For a test: name the code it covers. If that code stays, the test stays, unless an
     identical test covers the same thing.
   Verdict per finding: CONFIRMED, DOWNGRADED (to MEDIUM) or REJECTED, with the reason.
3. Never remove: license headers, lint and type directives (eslint-disable,
   @ts-expect-error, # type: ignore, noqa, pragmas), "why" comments that still hold, doc
   comments on public APIs, TODOs that link an open ticket, text that a test checks
   for, and anything a verifier could not prove.

PHASE 4: SHOW ME THE BILL (gate 2)
Write the removal list to the ledger and show me a summary:
- a table per category and per area: findings, files, lines to remove, HIGH vs MEDIUM
- total lines to remove and the percent of the codebase that is
- the 10 largest removals, one line each
- anything that touches a public API, the database, auth or payments, flagged apart
Then ask me to choose:
A) Apply all CONFIRMED items.
B) Apply HIGH confidence items only.
C) Let me pick by category, area or ID.
D) Report only. Change nothing.
If I said no to review in Phase 1, apply HIGH confidence only. Still stop here for any
batch over 500 lines and for anything flagged above.

PHASE 5: CLEAN IN SMALL BATCHES
1. Group the approved items into batches of one area and one category each, under about
   300 changed lines per batch.
2. For each batch: make the change, then run the build, type check, lint and full test
   suite.
3. Compare with the baseline. The passing test count may drop only by the exact number of
   tests I approved for removal. On any new failure, new warning or build error: revert
   that batch, mark its items REJECTED with the error, and go on to the next batch.
4. Commit each batch as soon as it passes, with the finding IDs in the message. Never
   leave a passed batch uncommitted: a usage limit can end the run at any time.
5. When every batch is done, run the full suite once more. Start the app if you can, and
   walk its main paths once to confirm it still works.

PHASE 6: REPORT
1. Push the branch and open one pull request per area with gh pr create. Each PR lists
   its finding IDs, lines removed, and the before and after test results. Do not merge.
2. Give me the final report: lines removed per category, comments fixed vs removed,
   tests removed, findings rejected and why, the PR links, and any real bugs you found
   on the way (list them, do not fix them in this run).

You are the daily maid for this codebase. Clean only what changed since your last visit.
Same rules as a full maid run, with a small scope and no new features.

1. Read docs/maid/ for the date of the last maid run. If there is none, use the last
   24 hours.
2. Scope: the files changed since that date (git log --since), plus the files that import
   them. Nothing else.
3. Check this machine first. Use at most 3 agents: one finder, one verifier, one cleaner.
   Use fewer if free RAM is low.
4. Create the branch maid/daily-<YYYY-MM-DD>. Run the build and full test suite, and
   record the baseline.
5. Find and verify the same three things as a full run: dead code, stale comments and
   tests that no longer earn their place. The verifier tries to prove each finding wrong.
6. Apply HIGH confidence items only, in one batch, under 200 changed lines. Put anything
   bigger, and every MEDIUM item, in the report for me and do not change it.
7. Run the build and full test suite again. If anything new fails, revert the batch and
   report the error.
8. Commit, push and open one PR. Write a 5-line note to docs/maid/<YYYY-MM-DD>.md: files
   checked, items removed, items left for me, test results, PR link. Never merge.
9. If nothing needs cleaning, say "Clean. Nothing to remove." and change nothing.