Retroactive Specification
Use this skill to reverse-engineer Supersigil specs from existing code. Drive the process, but do not silently decide intent when the evidence is ambiguous.
Current Contract
Use the current CLI as the source of truth for the spec graph:
supersigil new <type> <feature>
supersigil schema [--format json]
supersigil verify
supersigil ls [--format json]
supersigil context <id> [--format json]
supersigil plan [<id_or_prefix>] [--format json]
supersigil verify [--format terminal|json|markdown]
supersigil status [<id>] [--format json]
supersigil affected --since <ref> [--format json]
Use references/source-gathering.md for the evidence order and the standard ambiguity questions.
Workflow
Scope one bounded area before reading broadly.
Ask the user which module, feature, API surface, or service boundary to capture.
Propose a traversal order if the area is still too large.
Do not attempt the whole repository at once.
Gather sources of truth before reading implementation details.
Read existing docs first.
Then read public APIs, types, and tests.
Read internal implementation last.
Treat tests as evidence, not authority.
Existing tests are strong input for observed behavior.
They are not proof that the behavior is intended if the user or docs disagree.
Ask clarifying questions only where intent matters.
Use questions to separate intended behavior, legacy behavior, and obvious bugs.
When behavior looks accidental, call that out instead of baking it into the spec silently.
Draft the spec graph incrementally.
Start with supersigil new when scaffolding helps.
Keep every authored document in status: draft.
Produce requirement docs first, then add design and tasks docs only where they clarify the scoped area.
Reconnect existing evidence to the graph.
Use VerifiedBy strategy="tag" or strategy="file-glob" to connect real tests.
Add TrackedFiles only when the owning source paths are concrete and helpful.
Run supersigil verify after every spec write.
Use supersigil verify to expose specification debt.
Coverage gaps, missing test mappings, stale globs, and status inconsistencies are part of the output, not noise to hide.
Keep the docs in status: draft until the user has reviewed what the recovered graph actually says.
End each bounded area with a gap report.
Summarize what the code does, what is now captured in specs, what lacks tests, and what still needs human intent decisions.
Authoring Rules
- Work one bounded area at a time.
- Prefer existing docs and tests over inference from internals alone.
- Capture current behavior explicitly, but flag questionable or legacy behavior instead of normalizing it.
- Keep criterion IDs, document IDs, and task IDs stable once introduced.
- Use
VerifiedBy only with real tags or real file globs.
- Do not promote statuses optimistically during recovery work.
Failure Modes
- Do not attempt to specify the whole project in one pass.
- Do not assume code is correct just because it exists.
- Do not assume tests are current if the surrounding docs or user intent disagree.
- Do not hide ambiguity; surface it and ask.
- Do not present draft recovered specs as final truth.
Handoff
If the user wants to continue implementing against the recovered specs, suggest ss-feature-development.
If the recovered work reveals a planned refactor or behavior change, suggest ss-spec-driven-development.
If the change is purely structural (reorganize code, no behavior change), suggest ss-refactoring.
Stale Spec Refresh
Use this mode when specs already exist but may have drifted from the code.
This is not greenfield recovery — it is reconciliation.
Identify stale documents.
Run supersigil affected --since <ref> to find docs whose tracked files
have changed since the last known-good state.
Run supersigil status <id> on each affected doc to see current health.
Run supersigil verify to surface coverage gaps and status inconsistencies.
Triage the affected set.
For each affected document, determine whether:
- The spec is still accurate and only
TrackedFiles timestamps changed.
- The spec needs minor updates (new criteria, updated globs, evidence repair).
- The spec is materially wrong and needs a full re-examination.
Update incrementally.
For minor updates, edit the existing docs in place. Keep them at their
current status unless the change is structural enough to warrant a
demotion back to draft.
For material changes, demote to status: draft, apply the standard
recovery workflow (steps 2–7 above) scoped to the affected area, and
re-verify.
Ask about intent changes.
When code changes contradict existing criteria, ask the user whether the
spec or the code is authoritative. Do not silently update the spec to
match the code.
End with a reconciliation summary.
Report which docs were updated, which were left unchanged, which have
unresolved intent questions, and the current supersigil verify state.
1---2name: ss-retroactive-specification3description: Use when code exists but Supersigil specs do not, or when existing specs have gone stale. Activates when the user wants to document current behavior, baseline before a refactor, add spec coverage to a brownfield module, or reconcile drifted specs with the codebase.4---56# Retroactive Specification78Use this skill to reverse-engineer Supersigil specs from existing code. Drive the process, but do not silently decide intent when the evidence is ambiguous.910## Current Contract1112Use the current CLI as the source of truth for the spec graph:1314```bash15supersigil new <type> <feature>16supersigil schema [--format json]17supersigil verify18supersigil ls [--format json]19supersigil context <id> [--format json]20supersigil plan [<id_or_prefix>] [--format json]21supersigil verify [--format terminal|json|markdown]22supersigil status [<id>] [--format json]23supersigil affected --since <ref> [--format json]24```2526Use [references/source-gathering.md](references/source-gathering.md) for the evidence order and the standard ambiguity questions.2728## Workflow29301. Scope one bounded area before reading broadly.31 Ask the user which module, feature, API surface, or service boundary to capture.32 Propose a traversal order if the area is still too large.33 Do not attempt the whole repository at once.34352. Gather sources of truth before reading implementation details.36 Read existing docs first.37 Then read public APIs, types, and tests.38 Read internal implementation last.39403. Treat tests as evidence, not authority.41 Existing tests are strong input for observed behavior.42 They are not proof that the behavior is intended if the user or docs disagree.43444. Ask clarifying questions only where intent matters.45 Use questions to separate intended behavior, legacy behavior, and obvious bugs.46 When behavior looks accidental, call that out instead of baking it into the spec silently.47485. Draft the spec graph incrementally.49 Start with `supersigil new` when scaffolding helps.50 Keep every authored document in `status: draft`.51 Produce requirement docs first, then add design and tasks docs only where they clarify the scoped area.52536. Reconnect existing evidence to the graph.54 Use `VerifiedBy strategy="tag"` or `strategy="file-glob"` to connect real tests.55 Add `TrackedFiles` only when the owning source paths are concrete and helpful.56 Run `supersigil verify` after every spec write.57587. Use `supersigil verify` to expose specification debt.59 Coverage gaps, missing test mappings, stale globs, and status inconsistencies are part of the output, not noise to hide.60 Keep the docs in `status: draft` until the user has reviewed what the recovered graph actually says.61628. End each bounded area with a gap report.63 Summarize what the code does, what is now captured in specs, what lacks tests, and what still needs human intent decisions.6465## Authoring Rules6667- Work one bounded area at a time.68- Prefer existing docs and tests over inference from internals alone.69- Capture current behavior explicitly, but flag questionable or legacy behavior instead of normalizing it.70- Keep criterion IDs, document IDs, and task IDs stable once introduced.71- Use `VerifiedBy` only with real tags or real file globs.72- Do not promote statuses optimistically during recovery work.7374## Failure Modes7576- Do not attempt to specify the whole project in one pass.77- Do not assume code is correct just because it exists.78- Do not assume tests are current if the surrounding docs or user intent disagree.79- Do not hide ambiguity; surface it and ask.80- Do not present draft recovered specs as final truth.8182## Handoff8384If the user wants to continue implementing against the recovered specs, suggest `ss-feature-development`.85If the recovered work reveals a planned refactor or behavior change, suggest `ss-spec-driven-development`.86If the change is purely structural (reorganize code, no behavior change), suggest `ss-refactoring`.8788## Stale Spec Refresh8990Use this mode when specs already exist but may have drifted from the code.91This is not greenfield recovery — it is reconciliation.92931. Identify stale documents.94 Run `supersigil affected --since <ref>` to find docs whose tracked files95 have changed since the last known-good state.96 Run `supersigil status <id>` on each affected doc to see current health.97 Run `supersigil verify` to surface coverage gaps and status inconsistencies.98992. Triage the affected set.100 For each affected document, determine whether:101 - The spec is still accurate and only `TrackedFiles` timestamps changed.102 - The spec needs minor updates (new criteria, updated globs, evidence repair).103 - The spec is materially wrong and needs a full re-examination.1041053. Update incrementally.106 For minor updates, edit the existing docs in place. Keep them at their107 current status unless the change is structural enough to warrant a108 demotion back to `draft`.109 For material changes, demote to `status: draft`, apply the standard110 recovery workflow (steps 2–7 above) scoped to the affected area, and111 re-verify.1121134. Ask about intent changes.114 When code changes contradict existing criteria, ask the user whether the115 spec or the code is authoritative. Do not silently update the spec to116 match the code.1171185. End with a reconciliation summary.119 Report which docs were updated, which were left unchanged, which have120 unresolved intent questions, and the current `supersigil verify` state.
jonisavo