Make Improvement

make-improvement

Change the structure, not the behaviour. The entire discipline is staying green while you move: an "improvement" that quietly changes what the code does is a bug you shipped on purpose. The thing you're improving almost always is an existing concept, so Gate A here is mostly find it and lock it down. For new behaviour use implement-feature; for a defect use fix-bug; to open the PR, create-pr.

When this applies

Refactors, performance work, readability cleanups, renames, extracting or consolidating shared code, and tech-debt paydown — any change whose success is defined by "behaves exactly the same, but better".

Write a note first

Invoke write-notes and record your answers to this form before you change anything:

• Goal: Describe what will improve (structure / performance / clarity) and the exact behaviour that must stay identical.
• Current shape: Walk through how the code works today — trace the path you'll restructure and name its callers.
• The concept: Describe the duplication you're collapsing or the primitive you're extracting, and where the single canonical version will live.
• Safety net: Describe how you've pinned today's behaviour — which test covers it, or the characterization test you wrote and watched pass first.
• Baseline: For a performance change, describe what you measured and the number you'll compare against.
• Risks & unknowns: What behaviour might you change by accident? Describe where you're least confident and how you'd notice a regression.

Gate A — before you change anything

Tick every box before the first edit — you have not earned the right to refactor until they hold:

• [ ] Stated what you're improving and why — the goal is structure / performance / clarity,

explicitly not new behaviour. If "improve" hides a feature or a fix, split it into its own change and commit.

• [ ] Felt the status quo — and measured it. You know exactly what the code does today; for a

performance change you baselined it first (no speedup claim without a before-number).

• [ ] Found the existing concept you're consolidating or extracting to — improving turns two

divergent copies into one canonical one, never adds a third.

• [ ] Discovered the house conventions from the tooling and the neighbours, so the improved code

still matches the project and passes its gate.

• [ ] Locked behaviour with a passing test first. If the code wasn't covered, you wrote the

characterization test, watched it pass, and only then refactored — your safety net for every step.

• [ ] Mapped the blast radius — every caller of what you're restructuring.

Do the work in reversible steps

• Small steps, green throughout. Move in increments that each keep the suite passing; commit each

coherent step so any one is trivially revertible.

• Never fold in a feature or a fix. Spot a bug mid-refactor? Note it and handle it separately — a

mixed commit is impossible to review or revert cleanly.

• For performance: one change, re-measure, keep what the numbers justify. Don't stack speculative

optimizations; prove each.

Gate B — before you call it done

Tick every box, or mark it N/A with a reason. An unticked box means not done.

• [ ] Behaviour is unchanged — the locking tests still pass, untouched.
• [ ] Performance claims are backed by before/after numbers, not vibes (or N/A).
• [ ] Reuse is actually achieved — the duplication is gone, not relocated.
• [ ] Docs and comments that described the old structure are updated — no stale "why".
• [ ] The gate is green — the project's format/lint/typecheck/test command passes.

Then take it to a clean PR with create-pr.

Patterns

• Refactor or feature — never both in one commit. The mix is the single most common way a

"harmless cleanup" ships a regression.

• Make it work, make it right, make it fast — in that order, proving each with the suite before

the next.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tale-project
• Source: tale-project/tale
• License: MIT
• Homepage: https://tale.dev

Install and usage instructions live in the source repository linked above.