A Refactoring Brief That Combines Spoken Context with Exact Code

When you ask an AI coding tool to refactor something, the explanation and the identifiers need different kinds of precision. You can explain why duplicated logic is becoming awkward in ordinary speech. A filename, exported function or boundary value is better supplied as exact text.

A useful brief combines both. It tells the tool what should change, what must keep behaving the same way and what you want back for review. You can dictate the explanatory parts or type the entire packet. Neither method requires a particular app.

Split the request into explanation and exact text

Use speech for the reasoning you would give a colleague: where the duplication came from, what makes it inconvenient and why you want a small change now. Use typing or paste for the objects that determine the work.

The typed material does not need to be a repository dump. Give the smallest relevant sample and enough location information to find its real counterpart. Remove secrets and unrelated customer data before pasting anything.

Copy a blank refactor brief

Reason for the change:
[What is awkward, and why change it now?]

Current behavior:
[What callers receive today, including units and boundaries.]

Exact symbols and locations:
- [path] :: [symbol] :: [role]
- [path] :: [symbol] :: [role]

Requested change:
[One change with a visible end state.]

Files that may change:
- [file]

Behavior that must remain unchanged:
- [invariant]

Out of scope:
- [nearby improvement to leave alone]

Return for review:
[Diff, explanation, proposed checks and any checks actually run.]

Action requested now:
[Explain a plan / prepare a patch / apply the scoped change.]

Fill the last line deliberately. A request for a plan should not quietly become permission to edit files. If a tool cannot find an exact symbol, ask it to identify the mismatch rather than substituting something with a similar name.

A fictional fee-rule extraction

The following miniature store and code are invented for this exercise. They are not CueSpec code or a recorded AI run.

Suppose src/billing/totals.js contains two callers with the same fee rule:

export function invoiceTotalCents(subtotalCents, deliveryCents) {
  const serviceCents = subtotalCents >= 5000 ? 0 : 300;
  return subtotalCents + deliveryCents + serviceCents;
}

export function checkoutTotalCents(subtotalCents, deliveryCents) {
  const serviceCents = subtotalCents >= 5000 ? 0 : 300;
  return subtotalCents + deliveryCents + serviceCents;
}

Your spoken context might be: “These two places use the same fee rule. I'd like one place to maintain it, without redesigning billing or changing what customers are charged.” That gives a reason, but it leaves the tool to guess the exact boundary and the intended size of the change.

Add this symbol map:

Then give a completed request:

Extract the shared service-fee calculation into serviceFeeCents in
src/billing/service-fee.js. Have both existing functions in
src/billing/totals.js call it.

For this exercise, inputs are non-negative integer amounts in cents.
Preserve the current rule: subtotalCents >= 5000 means a zero service
fee; a smaller subtotal means 300 cents. Delivery remains a separate
amount added to the total. Do not change the existing function names,
parameter order or returned units.

Allowed files:
- src/billing/totals.js
- src/billing/service-fee.js (new internal module)
- test/billing/totals.test.js (focused checks, if this test file exists)

Leave public barrel exports, validation policy, dependencies, currency
conversion and unrelated formatting alone. If the test file is absent,
report that before choosing a different test location.

Prepare a patch for review. Return the diff, the cases you would check,
and the actual outcome of each check you ran. Identify anything not run.

The small helper may need a module export so the existing file can import it. Keeping the public barrel exports unchanged is more precise than saying “no new exports” while also requesting a separate module.

See what the request changed

This is a comparison of two instructions, not a code diff or an execution transcript:

- Clean up the billing code and make it reusable.
+ Extract only the repeated service-fee rule into serviceFeeCents.
+ Preserve >= 5000, the 300-cent fee and both existing caller signatures.
+ Limit changes to the named files; leave public exports and validation alone.
+ Return a reviewable patch and distinguish proposed checks from checks run.

The first added line names the operation. The second protects behavior. The third prevents “cleanup” from expanding into a redesign. The fourth makes the returned evidence useful without treating an attractive explanation as proof.

Review the boundary before the elegance

For this invented rule, these are expected examples to turn into checks:

They are arithmetic expectations from the example, not recorded passing tests. When reviewing an actual patch, check that both callers use the helper, that the threshold did not become > 5000, and that the diff contains no unrelated changes. Read the stated check results separately from the proposed cases.

Once the packet is clear, your next instruction can be short because the exact objects and boundaries are already in the conversation. If you use CueSpec to prepare the spoken portion, its guide to mixing speech with technical identifiers explains the editable-draft route. The packet works just as well when typed into your existing coding tool.