skilldrop-cli 0.16.29 → 0.16.31

package/packs/dev-team/skills/refactor-plan/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: refactor-plan
+description: Plan paying down one piece of technical debt as a refactor that serves the goal it is blocking — characterisation tests on the riskiest behaviour first, then small steps each merged to main with main releasable after every one, pure refactors kept apart from the behaviour changes the goal needs, a scope fence, a stop point, a technique per step (extract, branch by abstraction, parallel change, strangler fig, mikado) and the clashes with in-flight feature work. Use when the user asks for a refactor plan, how to untangle, break up, replace or clean up a module without a rewrite, how to pay down a tech-debt item, "how do we refactor X without stopping feature work", "how do we get off X without a big bang", or wants a strangler-fig or mikado plan.
+---
+
+# refactor-plan
+
+You plan a refactor: work that pays down one piece of technical debt so that something the
+user wants becomes safe to do — add a shipping zone without fear, retire a vendor before its
+contract ends, let a batch worker import billing. The plan is a sequence of small steps, each
+one PR merged to main with main releasable after it, ending at the structure that goal needs.
+The team can stop after any step and the code is better than it was.
+
+Recording and ranking debt is `tech-debt-register`'s job; this skill starts from one item.
+Moving data or a schema with a backfill is `migration-plan`'s; when the payoff needs one, the
+plan stops at the code seam and names the migration as separate work.
+
+## How to respond
+
+**Four rules come before the steps and outrank them:**
+
+- **Lead with the answer.** The first two lines say the approach and the first step, in plain words: ✅ *"Put an interface in front of `SmsGateway`, build the new client behind it dark, and move message types over one flag at a time. Start with characterisation tests for `SmsGateway.send` in a new test file."* — ❌ a title, a target table, or a paragraph of context first.
+- **Match the size of the ask.** A question in chat ("how do we do this??", "plan how we untangle X") gets the plan in the reply: what the code shows, then a numbered sequence, one or two lines a step, each with its why. Write a full document only when the user asks for one (a file, "a proper plan", something to take to planning) or the work runs past about ten steps; then write the file and reply with the lead, the findings that change the plan, and where the file is. Never both at full length.
+- **Read what you were given, and use only that.** Open every file the user names and the callers it imports or is imported by. Report what is actually there, cited as `file:function`. Never say a file is unreadable without having tried to open it; if a read really fails, say which file and plan without it. No invented modules, baselines, vendors, volumes or dates. Callers or facts not in the input are checks to run (✅ *"grep for `price_order(` and `lines=`"*), not statements.
+- **Write for someone who has never heard of this skill.** No skill names, no scripts or paths from this folder, nothing about how the plan was produced. With a debt item to work on, state assumptions in a line and produce the plan; with nothing at all, ask for the debt item in one or two plain sentences.
+
+1. **Map the debt from the code.** The functions involved, every caller, and what each caller
+   relies on beyond the return value. Look for these four; they are what a plain read misses
+   and what breaks a refactor:
+   - **Contracts callers depend on:** mutation of an argument (✅ *"`exports/ledger.py:month_end` reads the rounding line back out of the `lines` list it passed to `price_order`, so `price_order` must keep appending to it"*), a return value that lies (✅ *"`SmsGateway.send` returns `True` from its `except`, so the retry in `alerts/notify.py:page_oncall` has never fired"*), ordering, side effects.
+   - **Copies outside the module:** duplicated constants or logic that bypass it and have drifted (a cron script with its own HTTP send, a report with its own `VAT_RATES`). Search every file in the input, scripts and reports included, for the module's constant and function names. Each goes inside or outside the fence by name; if outside, the plan does not claim the duplication is gone.
+   - **Test coverage as it is:** which paths existing tests reach (✅ *"the only test covers `format_message()`"*; ✅ *"`test_checkout.py` never imports `pricing.py`"*).
+   - **Stale signals:** a comment, TODO or open PR that says one thing while the code does another.
+
+2. **Start from the goal, and end at the structure it needs.** Name the user's stated goal and
+   the end state that delivers it — not the same code split across more files.
+   ✅ *"Goal: adding a shipping zone is a one-line data change. End state: zone rules live in
+   one table that `quote_shipping` reads; a new zone is a row plus a test."* — ❌ *"Extract
+   seven helpers from `quote_shipping` unchanged"* and stop. Then the target: one metric the team
+   can read (from the register item, or files touched per change, call sites on the old path,
+   forbidden imports), its baseline from the input or `not measured` with a step to measure it,
+   and a checkable **stop point** (✅ *"zero sends through the old gateway, the cron script
+   included"* — ❌ *"when the code is clean"*). Every step must move toward that end state;
+   a step that doesn't is cut.
+
+3. **Label every step `refactor` or `behaviour change`.** A refactor keeps output identical and
+   is proven by the pinned tests. A behaviour change the goal needs (moving rules into data
+   that changes a result, removing a mutation a caller relied on, surfacing errors that were
+   swallowed, switching traffic to a new provider) is its own step, placed after the refactor
+   that makes it safe, with the caller moved first and its own rollback. Behaviour changes the
+   goal does not need — renamed env vars, a fixed rounding bug, money as Decimal, a schema
+   change — go out of the plan to a ticket, a later parallel change or a migration. Bugs callers
+   depend on are pinned as they are: ✅ *"pin `send` returning `true` on failure; surfacing
+   failures is a later, deliberate step"* — ❌ *"fix it while writing the test."*
+
+4. **Characterisation tests first, on the riskiest behaviour.** Before any step touches
+   untested code, pin current output, starting with what has caused incidents or what the code
+   comments warn about (the register's incidents, branches with odd rules). Name each behaviour
+   to pin by function: inputs callers send, boundaries (empty, zero, rounding, ordering,
+   timezones), error paths, current bugs. An approval (golden-master) test over recorded
+   real-shape inputs when output is too wide to assert by hand. Pin at the narrowest seam that
+   runs without the current suite's infrastructure.
+   **An open PR on the same file never delays the tests.** Tests change no production code: put
+   them in a new test file so they can't conflict, and if the open PR changes the pinned
+   behaviour on purpose, its author updates the pinned value in that PR. ❌ *"Characterisation
+   tests for the zone rules after #212 merges"* leaves the incident-prone code bare for weeks.
+   Code already covered on the paths a step touches skips this step; say which tests cover it.
+
+5. **Cut steps by the one-PR rule.** One PR a reviewer reads in one sitting, merged within a
+   couple of days, main releasable after it. **Never mix a move with a change** (✅ *"PR A: move
+   `calculate_tax` to `orders/tax.py` unchanged, old name re-exports it. PR B: change it."*).
+   **No long-lived branch:** work that can't merge in days goes behind a seam, on main and dark.
+   Size the sequence against the delivery facts given (CI time and flake rate, deploys per week,
+   approval gates, a deadline): ✅ *"about two deploys a week leaves roughly N releases before
+   the deadline; each flag flip needs one, so flips start by week X"* — counted from the input,
+   never invented. Around a busy window (peak season, a launch), run the dark refactor steps
+   through it and schedule the behaviour-change steps after it.
+
+6. **Pick the technique per step and say why** in one clause. The catalogue, with rollback
+   for each, is in [`reference.md`](reference.md):
+
+   | Technique | Use when |
+   |---|---|
+   | Characterisation tests | The code a step touches has no tests on the paths callers use |
+   | Extract / inline / move | A cohesive piece can leave in one PR with callers unchanged |
+   | Branch by abstraction | A dependency many callers use must be replaced, and the swap takes more than one PR |
+   | Parallel change (expand–contract) | A signature, contract or data shape changes and callers move over several PRs |
+   | Strangler fig | A whole module is replaced piece by piece, with routing at its edge deciding old or new per call |
+   | Mikado method | Each attempted change breaks on prerequisites; the graph of what must change first is unknown |
+
+7. **Order for value early, stoppable everywhere.** After the tests, the first step is the one
+   that unblocks the work the user named, not the neatest one; say why it is first. Every step
+   leaves the code better on its own. A step that only pays off once a later one lands is merged
+   with it, or its pair is within the next two steps and the plan says two paths exist until then.
+
+8. **Coordinate with in-flight work.** For each open PR or planned feature, name the shared
+   `file:function` and pick one:
+   - **Land first** — a PR the business needs (peak season, a customer date) merges ahead; the refactor rebases.
+   - **Wait** — a *move or rewrite* of code an open PR edits starts after it merges. Tests and seams elsewhere carry on.
+   - **Fold in** — the feature PR does the extraction for its own area, as a separate commit, when one team owns both.
+   - **Through the seam** — a PR adding a new caller of the code being replaced is asked to call the new interface.
+   - **Freeze window** — hours, not weeks, announced, for a high-churn move nobody can work around.
+   The refactor absorbs the rebase cost, not the feature. With no in-flight list, say
+   `[assumption] no known clashes` and add "check open PRs on these files before each step".
+
+9. **Emit the plan in the shape rule two chose.**
+   - **Chat reply** (default): the two-line lead; "What the code shows" as three to six bullets
+     citing `file:function`; the numbered steps, each one or two lines — the change, the why,
+     `[refactor]` or `[behaviour change]`, and the clash or rollback when it matters; one line
+     each for target and stop point and for not touched; at most three questions under "To
+     confirm". Aim under about 50 lines.
+   - **Document** (asked for, or large): the skeleton in
+     [`templates/refactor-plan.md`](templates/refactor-plan.md), each step with change,
+     type, technique and why, verified by, rollback (the live side for any flag), risk, size,
+     owner role. Save it where the user asked; the reply is the lead, the findings and the path.
+   Either shape ends with the scope-creep rule in one line: *"Anything found during the work
+   that isn't in a step goes to the debt register as a new item."*
+
+**Non-interactive runs** (subagent, CI, headless): with no debt item, module or pain named at
+all, emit `BLOCKED: need the debt to pay down — the module or register item and what it costs
+the team`. Everything else degrades to `[assumption]`: a missing baseline becomes a measuring
+step, missing code means steps cite only the names given, a missing in-flight list becomes
+"no known clashes", a missing owner becomes a role.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md) — the technique catalogue: when each fits, the step shape, rollback and "which side is live", the failure mode of each
+- [`templates/refactor-plan.md`](templates/refactor-plan.md) — the chat shape and the document skeleton
+- [`examples/search-ranker.md`](examples/search-ranker.md) — worked example: a 600-line ranking function with a flag pile and an in-flight PR, as a chat reply and as a document
+
+## Quality bar
+
+- **The first two lines give the approach and the first step.** A chat question gets a chat-sized plan; a document only when asked or large.
+- **Every step serves the stated goal,** and the last step reaches the structure that goal needs.
+- **Every step is labelled refactor or behaviour change;** behaviour changes stand alone, after the refactor that makes them safe.
+- **Characterisation tests come first, on the incident-prone behaviour,** and no open PR leaves that behaviour unpinned.
+- **Caller contracts, copies outside the module and real test coverage are reported** from the files, cited `file:function`.
+- **Every in-flight clash has a decision,** and a must-land feature PR is never blocked.
+- **The scope fence and stop point exist;** new findings go to the register.
+- **Every file, function, metric and number is from the input.** Unknowns are checks to run.
+
+## When to use this skill
+
+- ✅ Planning how to pay down one register item, or one module everyone dreads changing
+- ✅ Breaking up a god class, a giant function or a tangled package without a rewrite
+- ✅ Replacing an internal dependency or a vendor client used from many call sites while features keep shipping
+- ✅ Making the case that a refactor can be done in small, stoppable steps instead of a quarter-long branch
+
+## When NOT to use this skill
+
+- ❌ Listing or ranking the debt in the first place — `tech-debt-register`
+- ❌ Moving data, changing a schema or switching platforms with a backfill — `migration-plan`
+- ❌ Writing the code for one of the steps — `feature-implement-loop`
+- ❌ Deciding the target architecture or recording why — `adr-generator` or `design-doc`
+- ❌ Reviewing a refactor PR that already exists — `pre-merge-review`
+- ❌ Splitting a feature into user stories — `user-story-splitter`
+
+## Anti-patterns to avoid
+
+- ❌ **The unrequested report.** Twelve thousand characters of tables in reply to "how do we do this??". The asker wanted the sequence and the first move.
+- ❌ **Same code, more files.** A plan that only moves code unchanged when the goal was "add a zone without fear". Seven helpers that each still hard-code the rules haven't made the next zone easier.
+- ❌ **Tests after the open PR.** Deferring characterisation tests until a feature PR merges, so the area with the incidents stays unpinned through the riskiest weeks.
+- ❌ **Quietly changing a contract.** Making a function pure, or making `send` honestly return `false`, without moving the callers that relied on the old behaviour first.
+- ❌ **Deleting the module and calling it done** while a script or report still carries its own copy.
+- ❌ **The rewrite in disguise.** "Step 1: build the new OrderService. Step 2: switch over."
+- ❌ **Fixing bugs mid-refactor.** The first unlabelled behaviour change makes every later test failure ambiguous.
+- ❌ **No stop point,** or a target nobody measured. "Easier to change" ends never.
+- ❌ **Claiming a file couldn't be read** without having opened it.

package/packs/dev-team/skills/refactor-plan/evals/eval_queries.json

@@ -0,0 +1,46 @@
+[
+  {
+    "query": "This 1,800-line OrderService is where every change goes wrong; plan how we untangle it without stopping feature work",
+    "should_trigger": true
+  },
+  {
+    "query": "TD-04 got approved for this quarter. Plan the refactor as small PRs we can ship one at a time",
+    "should_trigger": true
+  },
+  {
+    "query": "How do we break billing's dependency on the web package without a big-bang rewrite?",
+    "should_trigger": true
+  },
+  {
+    "query": "Give me a strangler-fig plan for replacing our legacy report builder module piece by piece",
+    "should_trigger": true
+  },
+  {
+    "query": "We want to stop calling the SMTP client from 14 places — plan the refactor with characterisation tests first",
+    "should_trigger": true
+  },
+  {
+    "query": "Go through our TODOs and incident notes and tell me which tech debt to pay down this quarter",
+    "should_trigger": false
+  },
+  {
+    "query": "Plan the cutover from MySQL to Postgres with a backfill and no downtime",
+    "should_trigger": false
+  },
+  {
+    "query": "Implement step 2 of the refactor plan: move calculate_tax into its own module with tests",
+    "should_trigger": false
+  },
+  {
+    "query": "Write an ADR for splitting the monolith into an orders service and a billing service",
+    "should_trigger": false
+  },
+  {
+    "query": "Review this refactoring PR before I merge it",
+    "should_trigger": false
+  },
+  {
+    "query": "Split the gift-card checkout epic into user stories",
+    "should_trigger": false
+  }
+]

package/packs/dev-team/skills/refactor-plan/evals/evals.json

@@ -0,0 +1,106 @@
+{
+  "skill_name": "refactor-plan",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "This 1,800-line OrderService is where every change goes wrong; plan how we untangle it without stopping feature work. The code is order_service.py, the register row is debt-register-row.md, coverage is in test-coverage.txt, and what's in flight is in-flight-prs.md.",
+      "assertions": [
+        "Opens with the approach and the first step in its first lines, and states the target with its baseline taken from the register row (9 of the last 12 order PRs touching order_service.py, or the 3.1-day against 1.2-day review time) and a checkable stop point",
+        "Characterisation tests come before any step that touches calculate_tax, refund or send_confirmation_email (0% coverage), and they pin the per-line tax rounding and the zero-price negative-quantity lines as they behave today rather than fixing them",
+        "No step is a rewrite or a long-lived branch: every step is one PR merged to main, and moves are separated from changes",
+        "Each step says what changes, why (naming the technique where it matters), which tests verify it, and whether it is a pure refactor or a behaviour change; any step that adds a flag or an abstraction says which side is live for rollback",
+        "Names the clash with #481 (apply_discounts, charge_payment) and #486 (send_confirmation_email) and decides how each is handled (land first, wait, fold in, route through the new seam, or a short freeze window), rather than moving that code under the open PRs; characterisation tests are not delayed by either PR",
+        "The scope fence keeps the confirmation-email-on-failed-payment behaviour (INC-715) and the rounding out of the refactor as behaviour changes, and says new findings go to the debt register",
+        "Says the plan can stop after any step with the code better than before, and gives a reason the first real step goes first (for example the planned partial refunds or the in-flight gift-card work)",
+        "Does not invent modules, metrics or numbers not in the input; every file and function cited exists in the four files",
+        "Answers at the size of the ask: the plan is in the reply as a numbered sequence of steps of a line or two each, not a long multi-section document, since no document was requested"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our Django app reads settings straight from os.environ in about 40 places and every test has to monkeypatch the environment. I want a plan to move everything behind one settings object. While we're at it, let's rename all the env vars to a consistent APP_ prefix.",
+      "assertions": [
+        "Produces the plan without asking questions first, with its assumptions tagged [assumption] at the top",
+        "Pulls the env var rename out of the refactor as a behaviour change, and either sends it to its own later parallel change (read both names, then drop the old) or to a separate ticket, instead of folding it into the steps",
+        "Uses 'about 40 direct os.environ reads' as the baseline and does not invent other measured numbers such as test times or file counts; anything else to measure is marked not measured",
+        "Introduces the settings object first and moves call sites over in batches of one PR each, so main stays releasable between batches",
+        "Characterisation tests pin how values are parsed today (defaults when unset, how strings like 'false' or '0' are read) before call sites move",
+        "The stop point is zero direct os.environ reads outside the settings object, enforced by a check in CI or a test",
+        "Does not invent file names, module names or settings that the prompt did not mention"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We want the nightly batch worker to import billing directly, but billing imports from web all over the place. imports.txt has the import graph and register.md has the debt row (TD-11). Plan the refactor. Also, invoices.total_cents should become a decimal column, so fold that in too.",
+      "assertions": [
+        "Builds the order from imports.txt as a prerequisite graph (mikado-style or explicit dependency order): the goal, the import edges blocking it, and which edges change cleanly first, with the reason",
+        "States the target as the count of billing-to-web imports in imports.txt (seven) going to zero, or the four in invoices.py and dunning.py that block the worker as the first milestone, with the final stop point enforced by an import check in CI",
+        "Puts characterisation tests for billing/proration.py before any step that changes it, because the register row says it has no tests, and relies on tests/billing/ for invoices and dunning",
+        "Sequences the edges that block worker/nightly.py (in billing/invoices.py and billing/dunning.py) before the proration and tax edges the worker doesn't need, and says the plan can stop with the worker unblocked and the code better",
+        "Pulls the invoices.total_cents column change out of the refactor as a schema change with data to migrate, to be planned separately as a migration, and does not fold it into any step",
+        "Every step cites the specific import line or file from imports.txt it removes, and states its rollback",
+        "Does not invent modules, functions, metrics or numbers beyond imports.txt and register.md"
+      ]
+    },
+    {
+      "id": 4,
+      "held_out": "2026-10-20",
+      "prompt": "I'm tech lead on the billing squad. I want a proper refactor plan for DEBT-14 in docs/tech-debt-register.md, i.e. build_invoice in src/billing/invoice.py. Goal: adding a tax region or a pricing rule should stop being a week of fear. No rewrite, and we can't freeze feature work; open PRs are in docs/open-prs.md. Callers I know about are preview_invoice in the same file and src/partners/statement.py; the only billing tests we have are tests/billing/test_payments.py. Please write the plan to docs/refactor-plan-debt-14.md so I can take it to planning on Thursday.",
+      "assertions": [
+        "Spots that src/partners/statement.py depends on build_invoice mutating the caller-supplied line_items list (it reads the appended tax line back from its own `lines` list, not from the returned invoice), and the plan either keeps that side effect working or moves that caller off it in its own step before the mutation is removed. It does not quietly make build_invoice pure.",
+        "Spots that reports/monthly_revenue.py has its own copied TAX_RATES and tax logic, which has already drifted (no US-TX, no EU reverse-charge rule). The plan puts it explicitly inside or outside the scope fence, and does not claim the refactor removes duplicated tax logic if the report is left out.",
+        "Puts characterisation tests for build_invoice first, before any extraction, and says they must cover the existing branches (short-period proration, annual anniversary month, included seats/annual add-on discount, usage tiers, each coupon type including expiry, tax-exempt and reverse charge, non-GBP conversion, credit notes, rounding). They pin current output, float-rounding quirks included. Notes that test_payments.py gives no coverage of invoice.py.",
+        "Deals with the clash with PR #412 (tax block and TAX_RATES, committed to customers for 1 Nov): it sequences the tax-block work after #412 merges, or otherwise avoids conflicting edits to that block while #412 is open. It also mentions draft PR #420 touching the add-ons block.",
+        "Keeps DEBT-15 (float to Decimal money) and any change to rounding or tax results out of scope as separate work, and states that every step preserves behaviour, i.e. invoice output is unchanged.",
+        "Breaks the work into small, separately mergeable PRs, each leaving main releasable. Each step names a specific technique that fits it, e.g. extract function per section (plan, add-ons, usage, coupons, tax, currency, credit note), or parallel change / expand-contract for the line_items parameter or the signature with 9 parameters.",
+        "Sets a measurable target with a baseline taken from the files (e.g. build_invoice is about 165 lines with 9 parameters and 0 tests; or the register's '2 incidents in Q3' / 'most of a sprint per tax region') or marked as 'to measure'. It also defines an explicit stop point where the refactor is finished.",
+        "Invents no facts: no made-up cyclomatic-complexity numbers, coverage percentages, incident counts, team sizes or dates beyond those in the inputs, and no claims that callers, modules or tests exist beyond those shown. New modules it proposes are clearly labelled as proposed. Unknowns, such as other callers of build_invoice, appear as checks to run (e.g. grep for build_invoice and line_items=), not as stated facts."
+      ]
+    },
+    {
+      "id": 5,
+      "held_out": "2026-10-20",
+      "prompt": "ok so we're moving off the old smtp relay to the new email provider, relay contract ends end of Q1. LegacyMailer has to die but i really dont want a big bang, peak season is coming and #88 needs to land. how do we do this?? stuff is in src/notify, see open-prs.txt and ci-notes.md. we'll write the new provider client ourselves, its just an HTTP API",
+      "assertions": [
+        "Flags that LegacyMailer.send returns true even when sending fails (the catch block returns true), and that src/orders/onOrderShipped.ts has a retryQueue branch on !sent that has never fired as a result. Warns that a new client which honestly returns false (or throws) would change behaviour, with possible retries or duplicate emails. Keeps the current semantics at the seam and treats surfacing errors as a separate, deliberate change.",
+        "Finds that scripts/nightly-digest.js has its own copy of the SMTP send and renderer, bypasses LegacyMailer, and skips the suppression list. Brings it into the plan, since the relay can't be switched off while it exists, and does not treat deleting legacyMailer.ts as finishing the migration.",
+        "Proposes an incremental migration through a seam (branch by abstraction and/or strangler fig): an interface the callers depend on, the new HTTP-provider implementation behind it, a per-template or per-caller switch via flag/config with a quick rollback, and legacy code deleted only once traffic on it is zero.",
+        "Lists the LegacyMailer behaviours that need characterisation tests before the swap: comma-splitting and lowercasing recipients, suppression-file filtering (and returning true when all recipients are suppressed), bccOps, per-template subjects including the 'there' fallback, missing vars rendering as empty, sendBulk's sequential 200ms pacing. Notes the existing test only covers render().",
+        "Handles each in-flight PR that matters: #88 (adds a template and subject inside legacyMailer.ts; must land for peak) is allowed to land first or is accommodated, not blocked. #91 (rewrites loadTemplate/templates to MJML) is flagged as a clash with the template-rendering step. #93 (new mailer.send caller for magic_link) is told to go through the new seam.",
+        "Sizes and sequences the steps against ci-notes.md (about 38 min e2e that flakes about 1 in 6, manual prod approval, about 2 deploys a week) and the end-of-Q1 deadline. Each step is its own small PR leaving main releasable. Includes a measurable target and stop point, e.g. templates or call sites still on the relay going from a baseline counted in the files to 0, or relay send volume reaching 0, before the contract ends.",
+        "Invents no facts: no named email vendor or specific API endpoints, no email volumes, error rates, team size or calendar dates beyond 'end of Q1', and no claim of call sites beyond those in the files. Unknowns (other callers of mailer, the provider's suppression handling, which templates are highest volume) are raised as questions or checks.",
+        "Delivers a usable plan in this reply despite the vague request, asking at most a few targeted questions, and recommends neither a big-bang cutover nor a feature freeze."
+      ]
+    },
+    {
+      "id": 6,
+      "held_out": "2026-10-20",
+      "prompt": "I need a refactor plan for InvoiceService in billing-service (billing-service/src/main/kotlin/billing/InvoiceService.kt). It's become a god class: JPA queries, native SQL and all our invoice rules (totals, tax, late fees, payment state) in one place. ADR-007 (docs/adr-007-persistence.md) commits us to moving off Hibernate to jOOQ in Q1, and I want the business rules pulled out before that starts so the ORM swap really is persistence-only. We can't freeze feature work on this service; what's open right now is in docs/open-prs.md. The existing tests are in billing-service/src/test/kotlin/billing/. Please write the plan as a sequence of PRs I can hand to the team.",
+      "assertions": [
+        "Flags that DunningJob.run() mutates invoices returned by findOverdue (status, dunningLevel, lastDunnedOn) without saving them, relying on Hibernate dirty checking inside @Transactional, and makes the plan handle it (an explicit save step or a test pinning that the changes persist) before findOverdue moves behind a non-JPA interface or the ORM changes.",
+        "Notices that InvoicePdfRenderer.taxFor is a copy of computeLineTax but rounds HALF_UP instead of HALF_EVEN, and does not silently merge the two as a behaviour-preserving step: it either fences the renderer out of scope or raises the mismatch as a decision for finance/the team (ADR-007 says tax rules are not to change).",
+        "Puts characterisation tests ahead of moving the untested logic, naming at least applyLateFees (grace days, exemption, the daysLate/30 multiplier, only raising the fee) and per-line tax rounding, since the existing tests only cover createInvoice; and says these tests should not need a database once the rules are extracted, or explains how they move from @SpringBootTest to plain unit tests.",
+        "Sequences around PR #412: does not start moving applyLateFees until #412 (approved, expected to merge this week) has landed, or explicitly rebases onto it; and names PR #415 (credit notes, changes void, about 3 weeks out) as a clash to coordinate with, e.g. by agreeing where issueCreditNote should live.",
+        "Sets a target taken from ADR-007's precondition, such as: invoice rule code has no jakarta.persistence imports and no EntityManager dependency, with the baseline read from the current file and a stop point at that precondition; the jOOQ migration itself is explicitly outside the scope fence, as are tax and late-fee rule changes.",
+        "Each step is a separate, small PR that leaves main releasable and behaviour unchanged, and each names a concrete technique that fits it (e.g. extract a pure InvoiceCalculator / late-fee policy, introduce a repository port in front of the EntityManager queries as branch by abstraction, parallel change for the findOverdue callers). It does not propose a rewrite or a long-lived branch.",
+        "Treats markPaid's native customer balance update (Customer.balance is mapped read-only) as persistence that has to stay atomic with the invoice save, and keeps it on the persistence side rather than moving it into the rules code.",
+        "Invents no modules, files, metrics, dates or numbers that are not in the provided files (no made-up coverage percentages, line counts, team sizes or PR numbers); anything new it proposes, such as a class name, is clearly labelled as a proposal."
+      ]
+    },
+    {
+      "id": 7,
+      "held_out": "2026-10-20",
+      "prompt": "web/src/components/CheckoutPanel.tsx is a nightmare. what's the plan? we ship nov 3 btw, open stuff is in notes/open-work.md",
+      "assertions": [
+        "The answer is short and easy to scan, matching a casual one-line question: a brief plan of a handful of steps, not a long formal document with many sections, and it does not ask a string of clarifying questions before giving a plan.",
+        "Respects the release: nothing beyond adding tests or trivial, zero-risk changes goes into CheckoutPanel before the 30 Oct code freeze / 3 Nov v4.8 release, and the structural refactor starts after release (or the plan explains why a specific step is safe to land before freeze).",
+        "Puts gift cards PR #231 (in v4.8, rewrites the totals block and submit(), expected merge by 28 Oct) ahead of any refactor of the same code, so the refactor does not conflict with it; and mentions #236 (address autocomplete, parked until after release) as touching the address section the plan would move.",
+        "Spots that MiniCart.tsx duplicates the totals maths but differs from CheckoutPanel (it rounds the discount per line instead of on the subtotal, and its free-shipping test is >= 5000 where CheckoutPanel uses > 5000), links this to WEB-512's 1p mismatch, and treats unifying them as a deliberate behaviour change needing a decision on which is correct, not a behaviour-preserving step.",
+        "Spots that OrderReview.tsx reads the 'checkout_draft' localStorage entry that CheckoutPanel writes (including total), and keeps that contract unchanged (or pins it with a test) when draft or totals logic is moved into a hook or module.",
+        "Asks for characterisation tests before moving logic, because the only existing test is a single snapshot: at least totals with a promo and the free-shipping threshold, and the draft write, as plain tests on behaviour rather than more snapshots.",
+        "Gives a target and stop point tied to something real in the input, for example WEB-530 (pay-by-bank in Q1 needs the payment step to stop assuming card fields) or pulling the totals and validation into pure functions, and says what is out of scope (e.g. not a redesign of the checkout flow).",
+        "Invents no files, metrics, dates or numbers not in the provided files; any count it quotes (e.g. how many useState calls there are or the file's length) matches the actual file, and proposed new hooks or modules are clearly labelled as proposals."
+      ]
+    }
+  ]
+}

package/packs/dev-team/skills/refactor-plan/evals/files/1/debt-register-row.md

@@ -0,0 +1,5 @@
+# Tech debt register — Checkout team (fictional), extract
+
+| ID | Item | Where | Cost today (evidence) | Fix size | Decision | Trigger | Owner |
+|---|---|---|---|---|---|---|---|
+| TD-04 | `OrderService` does pricing, tax, stock, payment, email, cancel, refund and finance export in one 1,812-line class; every order change edits it | `orders/order_service.py` | 9 of the last 12 merged order PRs touched `order_service.py`; median review time for those PRs 3.1 days against a team median of 1.2 days; INC-702 (tax totals wrong after a discount change, Aug) and INC-715 (confirmation emails sent for failed payments, Sep) | L | Pay now | A third incident traced to `order_service.py` | Checkout team |

package/packs/dev-team/skills/refactor-plan/evals/files/1/in-flight-prs.md

@@ -0,0 +1,7 @@
+# Open PRs touching orders/ (fictional)
+
+- **#481 Gift cards at checkout** (Checkout team) — edits `OrderService.apply_discounts` and `OrderService.charge_payment`. Expected to merge next week.
+- **#486 Send order mail through the notifications service** (Platform team) — replaces `smtp_client.send` in `OrderService.send_confirmation_email`; adds `notifications/client.py`. In review.
+- **#490 Finance export: add VAT number column** (Finance tooling) — edits `OrderService.export_for_finance`. Draft, no date.
+
+Planned next quarter (not started): partial refunds, which needs changes to `OrderService.refund`.

package/packs/dev-team/skills/refactor-plan/evals/files/1/order_service.py

@@ -0,0 +1,74 @@
+# orders/order_service.py  (Lantern Outfitters web shop, fictional)
+# Excerpt: the full file is 1,812 lines. Signatures are complete; bodies shown only where
+# they matter. Elided bodies are marked "...".
+
+from decimal import Decimal, ROUND_HALF_UP
+
+from orders.models import Order, OrderLine
+from infra import stock_db          # direct DB client
+from infra import payments_gateway  # third-party SDK wrapper
+from infra import smtp_client       # sends mail synchronously
+from finance.csv_writer import write_row
+
+
+class OrderService:
+    """Creates, prices, pays for, fulfils, cancels, refunds and exports orders."""
+
+    def create_order(self, customer, cart, promo_code=None):
+        order = Order(customer=customer)
+        for item in cart.items:
+            order.lines.append(OrderLine(sku=item.sku, qty=item.qty, unit_price=item.price))
+        self.apply_discounts(order, promo_code)
+        self.calculate_tax(order)
+        self.reserve_stock(order)
+        result = self.charge_payment(order)
+        self.send_confirmation_email(order)   # sent even when result.ok is False
+        order.status = "paid" if result.ok else "payment_failed"
+        order.save()
+        return order
+
+    def apply_discounts(self, order, promo_code):
+        for line in order.lines:
+            if line.qty <= 0:
+                # Returns flow builds negative-qty lines and relies on them pricing at zero.
+                line.price = Decimal("0")
+                continue
+            line.price = line.unit_price * line.qty
+        if promo_code:
+            ...  # 140 lines: percentage, fixed-amount, buy-x-get-y, staff discount
+
+    def calculate_tax(self, order):
+        rate = Decimal("0.20")
+        total_tax = Decimal("0")
+        for line in order.lines:
+            # Rounds per line, not per order. Invoices issued since 2021 depend on this.
+            line_tax = (line.price * rate).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
+            line.tax = line_tax
+            total_tax += line_tax
+        order.tax = total_tax
+
+    def reserve_stock(self, order):
+        for line in order.lines:
+            stock_db.execute("UPDATE stock SET reserved = reserved + %s WHERE sku = %s",
+                             (line.qty, line.sku))
+
+    def charge_payment(self, order):
+        ...  # 210 lines: retries, 3-D Secure, gateway error mapping
+        return payments_gateway.charge(order.customer.payment_token, order.total())
+
+    def send_confirmation_email(self, order):
+        body = self._render_confirmation(order)
+        smtp_client.send(to=order.customer.email, subject="Your order", body=body)
+
+    def _render_confirmation(self, order):
+        ...  # 180 lines of string templating
+
+    def cancel_order(self, order):
+        ...  # calls stock_db directly, then payments_gateway.void, then smtp_client.send
+
+    def refund(self, order, lines):
+        ...  # builds negative-qty lines, calls apply_discounts and calculate_tax, then
+             # payments_gateway.refund and smtp_client.send
+
+    def export_for_finance(self, orders, path):
+        ...  # 260 lines: one CSV row per order line via finance.csv_writer.write_row

package/packs/dev-team/skills/refactor-plan/evals/files/1/test-coverage.txt

@@ -0,0 +1,14 @@
+Coverage for orders/order_service.py (from tests/orders/test_order_service.py)
+
+OrderService.create_order             71%
+OrderService.apply_discounts          38%
+OrderService.calculate_tax             0%
+OrderService.reserve_stock            55%
+OrderService.charge_payment           64%
+OrderService.send_confirmation_email   0%
+OrderService._render_confirmation      0%
+OrderService.cancel_order             22%
+OrderService.refund                    0%
+OrderService.export_for_finance       80%
+
+tests/orders/test_order_service.py: 46 tests, 6m40s in CI (starts a real stock database container)

package/packs/dev-team/skills/refactor-plan/evals/files/3/imports.txt

@@ -0,0 +1,22 @@
+# Imports from billing/ into web/ (fictional Quillrow app), generated by grep on main
+# Goal: billing/ imports nothing from web/, so the nightly batch worker (worker/nightly.py)
+# can import billing without starting the web framework.
+
+billing/invoices.py:4     from web.request_context import current_tenant
+billing/invoices.py:5     from web.templates import render_pdf
+billing/proration.py:3    from web.settings import BILLING_ROUNDING
+billing/proration.py:9    from web.request_context import current_tenant
+billing/dunning.py:2      from web.mailer import send_mail
+billing/dunning.py:3      from web.templates import render_email
+billing/tax.py:6          from web.settings import TAX_REGION
+
+# Imports inside web/ that the above pull in
+web/request_context.py    imports web.app (starts the framework on import)
+web/templates.py          imports web.app
+web/mailer.py             imports web.templates
+web/settings.py           no web imports
+
+# Callers of billing from outside billing/
+web/views/invoices.py     billing.invoices.issue_invoice
+web/views/plans.py        billing.proration.prorate
+worker/nightly.py         (wants) billing.dunning.run_dunning, billing.invoices.issue_invoice

package/packs/dev-team/skills/refactor-plan/evals/files/3/register.md

@@ -0,0 +1,3 @@
+| ID | Item | Where | Cost today (evidence) | Fix size | Decision | Trigger | Owner |
+|---|---|---|---|---|---|---|---|
+| TD-11 | `billing` imports from `web`, so anything that imports billing starts the web app | `billing/` | The nightly dunning job runs as an HTTP call to a hidden admin endpoint because the batch worker can't import billing; that endpoint timed out on 3 nights in September and dunning emails went out a day late. `billing/proration.py` has no tests; `billing/invoices.py` and `billing/dunning.py` are covered by `tests/billing/`. | M | Pay now | Another missed dunning run | Billing team |

package/packs/dev-team/skills/refactor-plan/evals/files/4/docs/open-prs.md

@@ -0,0 +1,6 @@
+# Open PRs (billing repo) — snapshot 2026-10-19
+
+- #412 "EU B2B reverse charge: check seller country, add NL/ES/IT rates" — author: dev-b — touches `src/billing/invoice.py` (tax block + TAX_RATES), +88/-14. Target: merge this sprint, customer commitment for 1 Nov.
+- #415 "Bump pytest to 8.x" — touches `requirements-dev.txt` only.
+- #418 "Partner statements: add CSV download" — touches `src/partners/statement.py`, `src/partners/views.py`.
+- #420 "Annual plans: support mid-year seat true-ups" — draft — touches `src/billing/invoice.py` (add-ons block).

package/packs/dev-team/skills/refactor-plan/evals/files/4/docs/tech-debt-register.md

@@ -0,0 +1,7 @@
+# Tech debt register — billing squad
+
+| ID | Item | Pain | Owner | Raised |
+|----|------|------|-------|--------|
+| DEBT-09 | Payment retries use sleep() in request thread | Slow checkout under load | payments | 2025-11 |
+| DEBT-14 | `src/billing/invoice.py::build_invoice` is one giant function with 9 keyword args; no unit tests | Every pricing change touches it; 2 billing incidents in Q3 traced to edits here (wrong proration, coupon applied after tax). Adding a new tax region took a dev most of a sprint. | billing | 2026-07 |
+| DEBT-15 | Float money arithmetic throughout billing | Cent-level mismatches finance fixes by hand monthly | billing | 2026-07 |

package/packs/dev-team/skills/refactor-plan/evals/files/4/reports/monthly_revenue.py

@@ -0,0 +1,44 @@
+"""Finance's monthly revenue report. Run by cron on the 2nd of each month.
+
+Recomputes tax per invoice so the report can split revenue by region.
+"""
+
+import csv
+import sys
+
+from billing.db import invoices_between, fetch_customer
+
+# copied from billing/invoice.py so the report doesn't need the whole
+# billing import chain (2023)
+TAX_RATES = {
+    "GB": 0.20,
+    "DE": 0.19,
+    "FR": 0.20,
+    "IE": 0.23,
+    "US-CA": 0.0725,
+    "US-NY": 0.04,
+}
+
+
+def tax_for(customer, subtotal):
+    if customer["country"] == "US":
+        region = "US-" + (customer.get("state") or "")
+    else:
+        region = customer["country"]
+    rate = TAX_RATES.get(region, 0.0)
+    if customer.get("tax_exempt"):
+        rate = 0.0
+    return region, round(subtotal * rate, 2)
+
+
+def main(start, end, out=sys.stdout):
+    writer = csv.writer(out)
+    writer.writerow(["invoice_id", "region", "subtotal", "tax"])
+    for inv in invoices_between(start, end):
+        customer = fetch_customer(inv["customer_id"])
+        region, tax = tax_for(customer, inv["subtotal"])
+        writer.writerow([inv["id"], region, inv["subtotal"], tax])
+
+
+if __name__ == "__main__":
+    main(sys.argv[1], sys.argv[2])