Ss Reverse Spec

---
name: ss-reverse-spec
description: Reverse-engineers OpenSpec source-of-truth capability specs from an existing (brownfield) codebase, either as a full baseline sweep or for a single capability. Bootstraps the openspec/ skeleton first if the project doesn't have one yet. Use this to give a legacy repository a meaningful starting spec instead of an empty openspec/specs/ directory.
---

# 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

| Mode | Trigger | Output |
|------|---------|--------|
| Baseline | `--baseline` | scan the repo, generate specs for every capability found |
| Single capability | a capability name | generate or update one capability spec |

## 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`:

```markdown
# 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