Chapter 07 / 07

Plan

Judge the proposed repair’s files, completion criteria, dependencies, and source references against the fee defect.

What you should leave with

Shared intuition: the report explains the problem; the plan proposes the work and checks needed to repair it.
Shared language: criteria describe completion, dependencies describe order, and source references preserve where the work came from. Those source references are the plan's provenance.
Shared behavior: compare the proposed files and criteria with the defect, then require test evidence before calling the repair complete.

Step 1 of 5

Start from the defect

We have a defect report that explains the fee error and limits the repair.
Plan reads that report and asks an architect agent to propose tasks for the repair.
For this defect, the intended work is already clear: use the existing rounding helper in capture and run the existing fee test.
We’ll check whether the proposed tasks actually describe that work.

Source references

Fixture: specs/defects/capture-fee-truncates-instead-of-rounding-half-up.md, lines 14–24 and 39–41.

Look at applyRate before we send the report to the planner.
It multiplies the amount by the rate, rounds the absolute result, and restores the sign.
Its comment states the half-up rule for positive and negative amounts.
The helper already exists, and RISK-02 already checks the two required fee/net splits.
We need the service to use this helper; reading the helper and running the test doesn’t require editing either file.

Source references

Fixture: src/domain/money.ts, lines 38–45;
test/service.test.ts, lines 107–115;
src/payments/service.ts, lines 118–120.

export const applyRate = (amount: Minor, rate: number): Minor => {
  const raw = amount * rate;
  const sign = raw < 0 ? -1 : 1;
  return minor(sign * Math.round(Math.abs(raw)));
};

Step 2 of 5

Run defect-driven Plan

We’ll put the new repair tasks under payments-fee-repair.
That keeps the original payments Task 1 and its evidence available while we plan the repair.
The defects option names the report to read; the feature option names the task set to write.
Both matter because Plan replaces the task files under the selected feature.

speed plan --feature payments-fee-repair \
  --defects specs/defects/capture-fee-truncates-instead-of-rounding-half-up.md

Source references

Before the live demo, check that payments-fee-repair is available for this repair.
Use a prepared teaching copy for repeat runs.
SPEED: lib/cmd/plan.sh, lines 479–527 and 1283–1308.
The overwrite guard blocks an existing task set with no defect-sourced tasks unless force is requested.
It isn’t a general guarantee that every existing task set is protected.

Step 3 of 5

Trace how tasks are created

The command resolves the defect path and reads the report’s contents.
It doesn’t take the normal spec-planning route that loads the product, tech, design, and test specs.
Normally it uses the primary tech spec’s name to find the test catalog.
With a defect report as input, that step is skipped.
That’s why our report states the rounding requirement and names the test to run.
The new-spec vision check is skipped too: the comment explains that a defect repair isn’t a proposal for a new spec.

Source references

SPEED: lib/cmd/plan.sh, lines 388–403, 479–527, 634–655, and 668–685.

Plan puts the defect text and its exact path into the architect’s message, along with the gathered code context.
The role file tells the architect how to turn that input into a task plan.
The message requires each proposed task to reference its source defect file.
That gives us a concrete check later: every task in this repair should point back to the fee report.
If the checked inputs match a cached architect result, Plan can reuse it; otherwise it calls the provider and parses the returned JSON.

Source references

SPEED: lib/cmd/plan.sh, lines 883–918, assembles the message or reads the cache;
lines 100–111 and 126–151 prepare the provider call and parse the result;
lines 1125–1133 run the architect phase.
agents/architect.md, lines 1–20, defines the role and its planning contract.

The writer turns those proposed tasks into JSON records.
Acceptance criteria describe what must be true when a task is complete; dependencies name tasks that must finish first.
The writer preserves those fields, the model, and declared files, then adds the current base commit and source references.
When a reference matches the fee report, it copies the source defect path and any declared failure-class or evidence fields.
Those fields retain their source values; planning doesn’t strengthen the evidence they refer to.
The new tasks start as pending work.

Source references

SPEED: lib/cmd/plan.sh, lines 1323–1372;
lib/tasks.sh, lines 14–58;
lib/cmd/plan.sh, lines 346–380, matches the defect reference and attaches its metadata.

Step 4 of 5

Review scope and criteria

Open the generated task records and start with the files they propose to change.
The implementation change should be in the service, using applyRate without modifying the shared money helper.
Verification should run the existing RISK-02 test without rewriting its assertions.
Then read the criteria against the report: the capture must use the required rounding and produce the expected fee/net splits.
“Fix rounding” alone wouldn’t say enough to check completion.
Any dependencies should represent actual prerequisites, and no task should decide refund idempotency as part of this repair.

Walkthrough notes

Fixture sources for that comparison:
specs/defects/capture-fee-truncates-instead-of-rounding-half-up.md, line 41;
src/payments/service.ts, lines 118–120;
src/domain/money.ts, lines 38–45;
test/service.test.ts, lines 107–115.

Step 5 of 5

Check provenance and completion

Finally, check the source reference on each task.
It should name the fee defect we supplied, so we can explain why that work belongs in the repair.
A task numbered one under payments-fee-repair is a new record, separate from source Task 1 under payments.
The proposed plan still needs our review before execution.
Creating the task records hasn’t changed the fee calculation or closed the defect.

Shared intuition: the report explains the problem; the plan proposes the work and checks needed to repair it.
Shared language: criteria describe completion, dependencies describe order, and source references preserve where the work came from.
Those source references are the plan’s provenance.
Shared behavior: compare the proposed files and criteria with the defect, then require test evidence before calling the repair complete.

Preparation and evidence notes

Presenter notes: Plan has been inspected in source, not executed for this lesson preparation.
Generated output under .speed/features/payments-fee-repair/tasks/ still needs verification.
After the live preparation run, name every actual JSON file and its line range beside the comparison above.
No task count, identifier, wording, or generated criterion is asserted here as checked output.
Use the actual current output; don’t present a suggested task as a generated one.
Keep defect-driven behavior distinct from spec-mode planning: the payments test catalog isn’t automatically injected in this mode.
Check scope and source references before delivery, and keep the fee repair separate from retry coverage and refund policy.

Carry forward

A plan proposes pending work. Require the actual repair and test evidence before calling the fee defect resolved.

What must the fee-repair plan include, what is outside its scope, and what evidence would establish completion?

Help me reason through this

Use applyRate in the service and run the existing RISK-02 test. Keep the shared helper, test assertions, and refund policy outside this bounded repair.

Your explanation is saved in this browser.