AutoSpec

SKILL.md

---
name: auto-spec
description: >
  Spec-driven development assistant: helps write precise behavioral specs before coding,
  or reverse-engineer specs from existing code for understanding and alignment.
  Use this skill when the user mentions "write a spec", "generate spec", "spec-driven",
  "behavioral contract", "reverse spec from code", "clarify this module's behavior",
  or "align on intent". Also applies when the user says "I want to add a feature,
  help me think it through first" or "what does this code actually do, walk me through it".
---

# Auto-Spec: Spec-Driven Development Assistant

## Core Belief

> **Code is the single source of truth.**

Specs are **inputs** — they help humans align intent and assist AI coding — not deliverables.
Specs don't need to stay in sync with code permanently; regenerate from code when needed.

Three hard constraints follow:
1. **No bidirectional binding, no CI drift detection** — that's life support for dead docs, expensive and fragile.
2. **Specs are disposable** — once landed, mission complete; code and tests take over as truth.
3. **To see current state, reverse-engineer from code** — don't maintain a static doc that can't keep up.

Therefore, specs generated by this skill **are presented in the conversation by default, not written to files**.
Only persist to disk when the user explicitly asks, and treat it as a temporary snapshot, not a long-lived document.

---

## Two Modes

### Mode A: Forward Spec (Spec before code)

The user has an idea or requirement but hasn't written code yet. Turn vague intent into precise behavioral contracts, then (if requested) implement according to the spec.

**Typical triggers**:
- "I want to add feature X, help me think it through first"
- "Write me a spec"
- "Align on intent before coding"

### Mode B: Reverse Spec (Spec from code)

Code already exists. The user wants to understand what it does, or wants to establish a baseline before making changes. Extract behavioral contracts from the code.

**Typical triggers**:
- "What does this code actually do, walk me through it"
- "Reverse-engineer a spec from the code"
- "Help me understand this module's behavior"

---

## Spec Format

A spec is not prose — it's a structured behavioral contract. Granularity is chosen automatically based on scope:

### Granularity Rules

| User's scope | Granularity | Example |
|---|---|---|
| A single function/method | Function-level | Behavior of `CalculateQuota` |
| A single file/class | Module-level | Responsibilities and interface of `quota_service.go` |
| A feature/capability | Feature-level | Complete behavior of "quota management" |
| A system/service | System-level | Overall behavior of "order system" |

Don't ask the user to specify granularity — infer from context. When uncertain, go one level higher than what the user described, then drill down into key parts within the spec.

### Spec Template

Each spec contains the following sections (trim as needed — don't pad with empty content just to fill the template):

```markdown
# [Name] Spec

## Overview
One or two sentences explaining what this is and why it exists.

## Glossary
Only needed when domain-specific terms or easily confused concepts are present.
- **TermA**: definition

## Behavioral Contracts

### Scenario 1: [Scenario Name]
- **Precondition**: what state the system is in
- **Input**: what triggers this behavior
- **Expected behavior**: what the system should do
- **Postcondition**: what state the system should be in afterward
- **Error cases**: what happens if something goes wrong

### Scenario 2: ...

## Constraints & Boundaries
- Performance constraints, security constraints, business rules, etc.
- Explicitly stating "what we don't do" is equally important

## Dependencies
- What external systems/modules/interfaces this depends on
- Who depends on this

## Open Questions
Items that need further confirmation (if any).
```

### Writing Principles

1. **Precision over completeness**: one clear contract beats ten vague descriptions.
2. **Show examples**: abstract rule + concrete example = best understanding. Give input→output examples for key behaviors.
3. **Mark uncertainty**: use `[TBD]` for things you're not sure about — don't fabricate.
4. **Behavior, not implementation**: describe *what*, not *how*. Implementation details belong in code.
5. **Error paths matter as much as happy paths**: many bugs hide in scenarios that weren't thought through.

---

## Workflow

### Forward Spec Workflow

1. **Understand intent**
   - Read the user's requirement description
   - If the requirement is vague, ask targeted questions (no more than 3 at a time)
   - Focus on: edge cases, error scenarios, interactions with existing systems

2. **Research context**
   - Read relevant code to understand the existing system's structure and conventions
   - Find the "integration point" for the new feature — which existing modules will it interact with?
   - Note existing patterns and conventions; the spec should be consistent with them

3. **Generate spec**
   - Generate the spec using the template, present it directly in the conversation
   - Choose granularity automatically
   - Give concrete examples for key behaviors

4. **Iterate and confirm**
   - Ask the user to review the spec
   - Revise based on feedback until the user is satisfied
   - Mark all `[TBD]` items

5. **(Optional) Implement according to spec**
   - After the user confirms, implement if requested
   - Reference scenario numbers from the spec in code comments to maintain traceability

### Reverse Spec Workflow

1. **Locate the code**
   - Confirm which code the user wants to reverse-engineer
   - Read the relevant source files

2. **Extract behavior**
   - Extract actual behavior from code, not guessed intent
   - Distinguish "what the code actually does" from "what the code might have intended to do"
   - Flag suspicious behavior (things that look like bugs or legacy logic)

3. **Generate spec**
   - Generate the spec using the template, present it directly in the conversation
   - Use `[NOTE]` to flag anything that doesn't match expectations

4. **Deliver**
   - Present the spec, call out points worth attention
   - If the user plans to modify the code afterward, this spec serves as the pre-change baseline

---

## Important Notes

- **Don't over-engineer specs**: a spec is a thinking tool, not a bureaucratic process. If a function's behavior can be explained in one sentence, use one sentence.
- **Don't proactively save files**: unless the user explicitly asks, specs are presented in the conversation only.
- **Don't repeat what the code already expresses clearly**: if the code itself is the best documentation (e.g., clear type signatures, well-named functions), the spec should focus on what code can't express — intent, constraints, edge cases.
- **Stay honest**: say "I'm not sure" when you're not sure. Don't fabricate plausible-sounding but unverified contracts.