Understand And Refactor

Understand and refactor

First session on an unfamiliar product repo. Map, then change. Do not edit until the map names the highest-ROI targets — unless the user passed a path so narrow the map is that path.

$ARGUMENTS is the scope: a path or subsystem, and/or --report-only. Default scope is the current workspace. --report-only maps and ranks; it does not edit.

Hard gates

• Behavior stays the same unless the user asked for a behavior change. This skill is structure, not features.
• Prefer existing docs over re-exploring: AGENTS.md, CLAUDE.md, CONTEXT.md, ADRs, handoffs/, README.
• A failed lookup is not a missing record. Prove the search can find something before reporting nothing.
• Do not invent product rules, betting thresholds, or deploy steps. Point at the file that already owns them.
• Do not add a library that duplicates one already in the repo. Search package.json / imports first.

1. Scope

• Named path / subsystem → that tree only.
• No path → whole workspace, but still start at the product surface the user cares about (app entry, API, pipeline) rather than listing every folder.
• --report-only present → stop after §4. No edits, no commits.

2. Map (write this down)

Read docs first. Then the repo:

1. Top-level layout and what each tree is for.
2. Runtime entry points (CLI, workers, HTTP, UI routes, schedulers).
3. Data flow for the main job: who writes, who reads, which store/key, which combiner.
4. Shared modules vs one-off copies.
5. Test / verify command that actually runs.

Keep the map short. Names, paths, arrows. Not a tour.

If a code-graph / memory MCP is available for this repo, use it before a repo-wide grep for symbols. Grep for exact string literals.

3. Rank problems

Only four buckets. Drop anything that is taste, renaming-for-renaming, or a rewrite of a working seam:

Score each candidate:

• Blast radius — files/callers touched
• Payoff — fewer lies, fewer copies, cheaper hot path, safer change later
• Proof — how you will know it worked (test, metric, or both)

Highest ROI = high payoff, bounded blast radius, a proof. Skip “clean up the whole layer.”

4. Report

Print:

1. Map — entries, data flow, stores.
2. Ranked list — 3–7 items, ROI first, with proof.
3. Do not touch — sacred files / hard rules found in docs.
4. First move — the one change you would make this session.

--report-only ends here.

5. Apply (not --report-only)

Do the first move, then the next only if it is still the highest ROI after the first lands.

• One logical change per commit-sized chunk.
• Existing tests run; add a characterization test before moving a seam that has none.
• Hunt regressions on sibling readers of any fact you moved.
• Stop when the ranked list’s remaining items are speculative or out of scope.

Done

The map is still accurate. The edits match the ranked list. Proof ran. No drive-by refactors outside the list.