refine

Files (3)

• SKILL.md
• openai.yaml · agents/
• mutations.md · references/

SKILL.md (first lines)

# Refine

The change works; now **make it right, make it fast**. You are the fresh eyes the author could not be: find what breaks the spec, then improve the code while the acceptance tests hold its behavior still.

Your inputs are the spec, or the request when there is none, the diff range, and the assertion changes the delivery listed. Load `strategic-programming`.

## Round

### Review

Read the spec and its sources yourself; the spec, not the diff, is your oracle. Review the whole affected flow, including code the diff did not touch that depends on what changed. Look through these lenses:

- **Behavior:** each example and what must never happen; each `capture` example against what the delivery captured, such as the screen against the chosen prototype; the spec's state space when it has one; each dependency's failures, restarts, retries, and duplicates; every consumer of a name, value, or seam whose meaning changed; the policy existing peers apply, such as validation, authorization, and guards, that the new behavior should inherit.
- **Tests:** each test against `strategic-programming`'s test value reference; stand-ins that differ from the real target; assertion changes that weakened an example; sleeps, wall-clock dependence, and flakiness; tests that CI will not run.
- **Mutations:** prove the tests by breaking the code, as [mutations](references/mutations.md) describes: in the first round, every target; later, only what the previous round added.
- **Right:** the `strategic-programming` lenses, the accepted program design when the spec points to one (the diff follows it, or the delivery names each departure), the project's coding standards, duplicated policy, dead code, scaffolding left from making it work, and temporary labels in durable files.
- **Fast:** the spec's budgets, and work the change made needlessly slow, such as extra round trips, queries, renders, or suite time.

A finding needs a concrete scenario reachable from input the product accepts, or a mutation that stayed green. Drop the rest. Sort what survives:

- **Blocker:** the change breaks an example or something that must never happen, loses data, exposes security, or turns a gate or CI check red. Missing or flawed evidence does not break an example unless it hides a defect.
- **Fix:** a real defect, a quality problem the change introduced, or a gap in the evidence, such as a missing or mistimed capture.
- **Follow-up:** real, but outside the change's scope.

On a large change, when the harness allows, split the review by area across fresh reviewers and give the tests and mutations their own reviewer.

### Improve

Fix blockers first, then fixes. A behavior fix comes with a test that fails without it. Keep structural changes in their own commits, separate from behavior changes, and run the tests before and after each. The acceptance tests' assertions stay as they are.

When several findings share a cause, fix the cause as `strategic-programming` orders it.

### Next round

Only blockers start another round, up to three in all. Its review, with fresh eyes when the harness allows, covers the final state of what the previous round changed and its callers. When a review finds no blocker, make its fixes, run the gates, and finish.

A sound spec and a sound delivery converge within three rounds. If the third review still finds a blocker, stop: the flow failed, not just the code. Report the blockers and what let them through, such as a missing example, a wrong decision, or a gap in the environment.

## Report

Leave for the pull request: the rounds, each blocker and fix with how it was resolved, mutations and their results, checks added with the defects they generalize, and the follow-ups.

## Done

The last review found no blocker and its fixes are made, every example still has a test that goes red without it, the project's gates pass on the final state, and the report is ready for `ship`.

From taecontrol/skills, MIT.

More from taecontrol/skills