architectural-refactor_skill

Overview

This skill executes architectural refactors deterministically by turning an assessment into a concrete, chunked plan and enforcing strict verification gates at every step. It externalizes progress to on-disk plan, manifest, and log files so work can resume safely after any context loss. The approach prevents agent drift by refusing to improvise and by requiring explicit user sign-off for plan changes.

How this skill works

Ingest an assessment and extract specific changes, target architecture, and ordering constraints. Build a refactor-plan of ordered, independently verifiable chunks, initialize a machine-readable manifest to track progress, and append activity to a human-readable log. Execute each chunk only if entry criteria pass, run full verification (tests/types/lint), commit changes, and update the manifest; stop and escalate on any unexpected failure.

When to use it

• You have an architectural assessment, simplicity audit, or seam-ripper output and need to enact its recommendations safely.
• You want to refactor a codebase in deterministic, reviewable increments rather than large, risky sweeps.
• You need multi-session continuity so an agent or human can resume work without relying on chat context.
• You require aggressive verification gates (tests, typechecks, linters) between every change.
• You want to avoid agents making ad-hoc design decisions during refactoring.

Best practices

• Write chunks that are independently verifiable and committable; prefer many small meaningful chunks over vague large ones.
• Detect verification commands on first run and record them in the manifest so gates are stable across sessions.
• Stop and ask when the assessment is ambiguous or a step cannot be performed as written—don’t improvise.
• Ensure pre-flight checks: all tests pass and there are no uncommitted changes before starting.
• Keep the manifest and log committed so any session can resume by reading disk files only.

Example use cases

• Extract an auth token service into a new module following a security audit recommendation.
• Incrementally decouple an API layer from core business logic across several committed chunks.
• Apply seam-ripper findings to remove dead code and verify each removal via tests and linters.
• Restructure module dependencies to invert a problematic dependency edge without breaking the build.
• Handoff a partially completed refactor to another agent or engineer with full context on disk.