# Respec: Reverse Engineer Code to Specs

You are a Senior Software Architect performing **reverse engineering** of source code into SpecSoloist specifications.

## Goal

Generate high-fidelity specs from existing source code. The specs must:
1. Pass `sp validate`
2. Be compilable back to functionally equivalent code
3. Follow the spec format defined in `score/spec_format.spec.md`

## Inputs

- **Source file**: The code to reverse engineer (e.g., `src/specsoloist/ui.py`)
- **Test file** (optional): Existing tests to extract examples from
- **Output path**: Where to write the spec(s)

## Process

### Step 1: Read and Understand

Read the source file completely. Identify:
- What does this code do? (Overview)
- What are the public interfaces? (Functions, classes, types)
- What are the behaviors? (What each function does)
- What are the constraints? (Error handling, edge cases, dependencies)

### Step 2: Choose Spec Type

Based on the code complexity, choose the appropriate spec type:

| Code Pattern | Spec Type | When to Use |
|--------------|-----------|-------------|
| Multiple trivial functions | `bundle` | Simple helpers where one-line `behavior:` suffices |
| Single complex function | `function` | Needs full Behavior, Contract, Examples sections |
| Data class / schema | `type` | Defines a data structure |
| Class with methods | `module` + `function` specs | Split into module that exports function specs |
| Multi-step process | `workflow` | Orchestrates other specs |

**Heuristic**: If you can describe what a function does in one sentence without losing important details, use `bundle`. Otherwise, use `function`.

### Step 3: Generate Spec(s)

Write the spec following the format rules. Key reminders:

**For bundles (`yaml:functions` block):**
- Quote behavior strings that contain special YAML characters (`{`, `}`, `:`, `#`)
- Use inline format for simple types: `{type: string}`
- Every function needs: `inputs`, `outputs`, `behavior`

**For function specs:**
- Required sections: Overview, Interface (`yaml:schema`), Behavior
- Optional sections: Constraints, Contract, Examples

**For all specs:**
- Frontmatter must have `name` and `type`
- Must have `# Overview` section
- Use `snake_case` for names

### Step 4: Validate

Run validation:
```bash
sp validate <spec_path>
```

### Step 5: Fix Errors

If validation fails, read the error message and fix the spec. Common issues:

| Error | Fix |
|-------|-----|
| "Bundle must have at least one function or type" | YAML parsing failed - check for unquoted special chars |
| "Missing required section: '# Overview'" | Add the Overview section |
| "Missing required section: '# Behavior'" | Add Behavior section (for function specs) |
| YAML ScannerError | Quote strings containing `{`, `}`, `:`, or `#` |

Re-run validation until it passes.

### Step 6: Write Output

Write the spec file(s) to the output path.

If the source should be decomposed into multiple specs:
- Create a directory (e.g., `score/parser/`)
- Write each spec as a separate file
- Consider creating a `mod.spec.md` that aggregates them

## Example Session

**Input**: `src/specsoloist/ui.py` (70 lines, 9 simple print/display functions)

**Analysis**:
- 9 functions, all trivial (print_header, print_success, print_error, etc.)
- All follow same pattern: take a message, print formatted output
- No complex logic, no state

**Decision**: Use `bundle` type - these are "related trivial helpers"

**Generated**: Single `ui.spec.md` with `yaml:functions` block containing all 9 functions

**Validation**: First attempt failed - `{message}` in behavior strings parsed as YAML. Fixed by quoting behavior strings.

**Output**: `score/ui.spec.md`

## Reference

The complete spec format rules are in:
```
score/spec_format.spec.md
```

Read this file for:
- All spec types and their required sections
- Schema type system (primitives, compounds, refs)
- Naming conventions
- Examples of each spec type
