Ss Refactoring

Refactoring

Use this skill when specs exist, tests pass, and the goal is to change code structure without changing behavior. The spec graph is the behavioral contract — it must stay green throughout.

Current Contract

Use the current CLI as the source of truth:

supersigil status  [--format json]
supersigil plan [] [--format json]
supersigil context  [--format json]
supersigil verify [--format terminal|json|markdown]
supersigil affected --since  [--format json]
supersigil verify

If the spec graph is missing, broken, or incomplete for the area being refactored, stop and hand the job to ss-retroactive-specification or ss-feature-specification first. Do not refactor code that has no behavioral contract.

Workflow

1. Establish the refactoring boundary.

Confirm with the user which module, subsystem, or code area is being restructured and what the structural goal is (extract module, rename abstraction, flatten hierarchy, etc.). Do not expand the boundary during the refactoring.

1. Snapshot the current verification state.

Run supersigil verify and supersigil status for all docs in the affected area. Record the current state: which criteria are covered, which tasks are done, which findings exist. This is the baseline — the refactoring must not make it worse.

1. Run all tests before changing anything.

Confirm the test suite passes. If tests fail before the refactoring starts, that is a bug, not a refactoring problem. Stop and address it separately.

1. Make structural changes in small, verifiable steps.

Move files, rename modules, extract types, reorganize imports — one logical change at a time. After each step, run the test suite to confirm behavior is preserved.

1. Update spec artifacts that reference moved code.

After structural changes, update:

• `` when source paths changed.
• `` when test file

paths changed.

• supersigil: {tag} comments if they moved to new files (tags

themselves should not change). Run supersigil verify after each spec edit.

1. Do not change criteria, requirements, or design intent.

The refactoring skill changes code structure and spec plumbing (paths, globs, tracked files). It does not change what the system does or what the specs say it should do. If the refactoring reveals that a criterion is wrong or missing, stop the refactoring for that area and hand it to ss-feature-specification.

1. Verify the refactoring preserved the contract.

Run supersigil verify and compare against the baseline snapshot. The refactoring is complete when:

• All tests still pass.
• verify findings are the same or better than the baseline.
• No new coverage gaps were introduced.
• supersigil affected --since HEAD shows only the docs you

intentionally updated.

1. End with a concrete summary.

Report what structural changes were made, which spec artifacts were updated (paths, globs, tracked files), and confirm the verification state matches or improves on the baseline.

Authoring Rules

• Do not change criterion IDs, document IDs, or task IDs during a

refactoring. These are stable references that other documents depend on.

• Do not change document statuses during a refactoring unless the

refactoring itself was the last remaining task for a status promotion.

• Update TrackedFiles and VerifiedBy paths to reflect the new

file locations. Use supersigil affected --since HEAD to find docs that need path updates.

• Keep supersigil: {tag} comment tags stable even when moving test

files. The tag is the stable identifier; the file location is not.

Failure Modes

• Do not refactor code that has no specs. Create specs first.
• Do not change behavior during a refactoring. If behavior needs to

change, that is a feature or bugfix, not a refactoring.

• Do not leave broken TrackedFiles or VerifiedBy paths behind.

verify will catch stale globs — fix them before claiming done.

• Do not skip the baseline snapshot. Without it, you cannot prove the

refactoring preserved the contract.

Handoff

If the refactoring reveals missing specs, suggest ss-retroactive-specification or ss-feature-specification. If the refactoring is preparation for a new feature, suggest ss-spec-driven-development or ss-feature-development for the next phase. If the user wants to continue with more structural changes, stay in this skill for the next bounded refactoring.

Source & license

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

• Author: jonisavo
• Source: jonisavo/supersigil
• License: Apache-2.0
• Homepage: https://supersigil.org

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