ss-retroactive-specification

name	ss-retroactive-specification
description	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.

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

1. 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.

2. Gather sources of truth before reading implementation details. Read existing docs first. Then read public APIs, types, and tests. Read internal implementation last.

3. 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.

4. 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.

5. 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.

6. 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.

7. 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.

8. 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.

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.