Skip to main content
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​

ScenarioInputExpected outputPass criterion
Over-complex functionfixture breaching the complexity ceilingrefactor under ceiling, tests greenbehaviour identical (mutation-checked)
Swallowed exceptionfixture with a catch that hides failureerror propagated with contextseeded failure now surfaces; tests green
Dead abstractionsingle-caller wrapper layerlayer removed, call site simplifiedtests green; public contract unchanged
Thin coveragefixture module with low coveragecharacterisation tests land before refactor commitstest commits precede refactor commits