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 <id> [--format json]
supersigil plan [<id_or_prefix>] [--format json]
supersigil context <id> [--format json]
supersigil verify [--format terminal|json|markdown]
supersigil affected --since <ref> [--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
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.
Snapshot the current verification state.
Run supersigil verify and supersigil status <id> 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.
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.
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.
Update spec artifacts that reference moved code.
After structural changes, update:
<TrackedFiles paths="..."> when source paths changed.<VerifiedBy strategy="file-glob" paths="..."> 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.
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.
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.
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.
1---2name: ss-refactoring3description: Use when restructuring code that has Supersigil specs and behavior must not change. Activates for module extraction, file moves, renames, hierarchy flattening, or any structural cleanup. Keeps specs, criteria, tracked files, and verification evidence valid throughout.4---56# Refactoring78Use this skill when specs exist, tests pass, and the goal is to change9code structure without changing behavior. The spec graph is the behavioral10contract — it must stay green throughout.1112## Current Contract1314Use the current CLI as the source of truth:1516```bash17supersigil status <id> [--format json]18supersigil plan [<id_or_prefix>] [--format json]19supersigil context <id> [--format json]20supersigil verify [--format terminal|json|markdown]21supersigil affected --since <ref> [--format json]22supersigil verify23```2425If the spec graph is missing, broken, or incomplete for the area being26refactored, stop and hand the job to `ss-retroactive-specification` or27`ss-feature-specification` first. Do not refactor code that has no28behavioral contract.2930## Workflow31321. Establish the refactoring boundary.33 Confirm with the user which module, subsystem, or code area is being34 restructured and what the structural goal is (extract module, rename35 abstraction, flatten hierarchy, etc.).36 Do not expand the boundary during the refactoring.37382. Snapshot the current verification state.39 Run `supersigil verify` and `supersigil status <id>` for all docs40 in the affected area.41 Record the current state: which criteria are covered, which tasks42 are done, which findings exist.43 This is the baseline — the refactoring must not make it worse.44453. Run all tests before changing anything.46 Confirm the test suite passes. If tests fail before the refactoring47 starts, that is a bug, not a refactoring problem. Stop and address48 it separately.49504. Make structural changes in small, verifiable steps.51 Move files, rename modules, extract types, reorganize imports — one52 logical change at a time.53 After each step, run the test suite to confirm behavior is preserved.54555. Update spec artifacts that reference moved code.56 After structural changes, update:57 - `<TrackedFiles paths="...">` when source paths changed.58 - `<VerifiedBy strategy="file-glob" paths="...">` when test file59 paths changed.60 - `supersigil: {tag}` comments if they moved to new files (tags61 themselves should not change).62 Run `supersigil verify` after each spec edit.63646. Do not change criteria, requirements, or design intent.65 The refactoring skill changes code structure and spec plumbing66 (paths, globs, tracked files). It does not change what the system67 does or what the specs say it should do.68 If the refactoring reveals that a criterion is wrong or missing,69 stop the refactoring for that area and hand it to70 `ss-feature-specification`.71727. Verify the refactoring preserved the contract.73 Run `supersigil verify` and compare against the baseline snapshot.74 The refactoring is complete when:75 - All tests still pass.76 - `verify` findings are the same or better than the baseline.77 - No new coverage gaps were introduced.78 - `supersigil affected --since HEAD` shows only the docs you79 intentionally updated.80818. End with a concrete summary.82 Report what structural changes were made, which spec artifacts were83 updated (paths, globs, tracked files), and confirm the verification84 state matches or improves on the baseline.8586## Authoring Rules8788- Do not change criterion IDs, document IDs, or task IDs during a89 refactoring. These are stable references that other documents depend on.90- Do not change document statuses during a refactoring unless the91 refactoring itself was the last remaining task for a status promotion.92- Update `TrackedFiles` and `VerifiedBy` paths to reflect the new93 file locations. Use `supersigil affected --since HEAD` to find docs94 that need path updates.95- Keep `supersigil: {tag}` comment tags stable even when moving test96 files. The tag is the stable identifier; the file location is not.9798## Failure Modes99100- Do not refactor code that has no specs. Create specs first.101- Do not change behavior during a refactoring. If behavior needs to102 change, that is a feature or bugfix, not a refactoring.103- Do not leave broken `TrackedFiles` or `VerifiedBy` paths behind.104 `verify` will catch stale globs — fix them before claiming done.105- Do not skip the baseline snapshot. Without it, you cannot prove the106 refactoring preserved the contract.107108## Handoff109110If the refactoring reveals missing specs, suggest `ss-retroactive-specification`111or `ss-feature-specification`.112If the refactoring is preparation for a new feature, suggest113`ss-spec-driven-development` or `ss-feature-development` for the next phase.114If the user wants to continue with more structural changes, stay in this115skill for the next bounded refactoring.
jonisavo