Reference — generated from the toolkit

Source of truth: toolkit/skills/refactor-to-standard/spec.md. Edit it there; this page is regenerated on build.

Skill: refactor-to-standard

• Owner: AI + Engineering
• Version: 0.1.0
• Lifecycle: draft
• Phase: refinement

Trigger

The hotspot pass in the Refinement playbook, or any module breaching the coding standards — over-ceiling complexity, swallowed exceptions, dead abstractions — behind existing tests. Brings code that predates the standards (or slipped past them) up to standard without changing what it does.

Inputs → outputs

• Inputs: a module plus the tests that cover it, the scaffold's lint/complexity config, and coverage data.
• Outputs: a behaviour-preserving refactor PR — complexity under the ceilings, error handling to standard, dead abstractions removed — with all pre-existing tests green and any new characterisation tests included. Each fixed violation listed against the lint rule it satisfies.

Procedure

1. Coverage first. Where coverage is thin on the code being touched, invoke characterisation-tests to pin current behaviour before changing anything.
2. Confirm the test suite is green at the start — that green is the baseline contract.
3. Refactor in small steps with tests run between each: bring per-function complexity under the ceiling, replace non-standard error handling (no swallowed exceptions — handle or propagate with context), remove single-caller abstractions and reimplemented stdlib.
4. No behaviour changes. Public contracts, outputs and error semantics stay identical. Anything that looks like a bug is flagged for a human — a fix is a separate, reviewable change, never smuggled into a refactor.
5. Emit one PR per module, small enough to review, through the merge gate like any change.

Guardrails & permissions

• Behaviour-preserving by definition — a red test aborts the step; the skill never edits a test to make a refactor pass. Test-file diffs in the PR are additions only (new characterisation tests).
• No new dependencies — per the coding standards' dependency rule; refactoring uses what's present.
• Works on a short-lived branch per the branching conventions; merge is human-reviewed.
• Standard agent guardrails; no production access.

Failure modes

• Behaviour change hidden by thin coverage (mitigated: characterisation-first rule; mutation testing on golden fixtures).
• Test bent to fit the refactor (mitigated: hard guardrail above; any modified test line fails review automatically).
• Churn without benefit — rewriting code that already met the standard (mitigated: every change in the PR must map to a named lint/standards violation).

Golden scenarios

Scenario	Input	Expected output	Pass criterion
Over-complex function	fixture breaching the complexity ceiling	refactor under ceiling, tests green	behaviour identical (mutation-checked)
Swallowed exception	fixture with a catch that hides failure	error propagated with context	seeded failure now surfaces; tests green
Dead abstraction	single-caller wrapper layer	layer removed, call site simplified	tests green; public contract unchanged
Thin coverage	fixture module with low coverage	characterisation tests land before refactor commits	test commits precede refactor commits