Ss Reverse Spec

Reverse OpenSpec Baseline

Generate source-of-truth specs under openspec/specs/ from existing code. This is how a brownfield repository gets a meaningful capability snapshot instead of starting from an empty openspec/specs/ directory.

Inputs

One of:

• --baseline — scan the whole repository and generate specs for every capability found
• a single capability name — generate or update just that one spec

Optional: --include <path> / --exclude <path> to scope the scan.

Step 0: Ensure the OpenSpec Skeleton Exists

Check whether openspec/specs/ and openspec/changes/ already exist. If this repository has no OpenSpec structure yet, create it first by following ../ss-references/openspec-skeleton.md, then continue below. If the skeleton already exists, skip straight to the requested mode.

Modes

Process: Baseline Mode

Step 1: Discover Capability Candidates

Collect signals from:

• README.md, an application-overview doc, and docs/
• controller / handler / route files
• service / domain layer names
• OpenAPI paths
• database migration or DDL table names

Cluster the candidates into kebab-case business noun phrases. For each candidate, list the evidence files that back it.

Step 2: User Confirmation Gate

Show the candidate list with evidence and ask the user to confirm merges, splits, renames, or removals. Do not generate baseline specs until capability ownership is confirmed.

Step 3: Reverse-Engineer Requirements

For each confirmed capability, inspect only the relevant files:

• public API / controller / handler behavior
• service or domain behavior
• DTO / schema validation
• error handling visible to callers
• relevant tests

Write observable behavior only. Do not include implementation details — cache choice, table names, internal algorithms — unless callers can actually observe them.

Step 4: Write Source-of-Truth Specs

Write openspec/specs/<capability>/spec.md:

# Capability: <capability>

> Baseline - reverse-engineered by the `ss-reverse-spec` skill.
> Generated at commit: <sha>
> Date: <YYYY-MM-DD>
> This baseline may be incomplete. It gets corrected over time through Phase 0 deltas
> generated by the `ss-plan` skill.

## Purpose

<one paragraph>

## Requirements

### Requirement: <name>
The system SHALL ...

#### Scenario: <name>
- **WHEN** ...
- **THEN** ...

Every Requirement MUST have at least one Scenario and direct evidence in code.

Step 5: Self-Review

Check for:

• duplicate Requirements across capabilities
• orphan code paths that don't belong to any capability
• Requirements that read like historical bugs rather than intended behavior
• missing edge cases that are visible in code or tests

Single Capability Mode

If openspec/specs/<capability>/spec.md already exists, ask the user to choose one of:

• overwrite it, keeping a .bak backup
• output a diff for manual merge
• stop

Output

Report:

• number of capabilities generated
• Requirement count
• orphan code list, if any
• files written
• a reminder that baseline specs are AI-reverse-engineered and need human review before commit