---
description: Create a feature specification document
argument-hint: <feature-slug>
allowed-tools: Bash, Read, Write, Edit, Glob, Grep
---

Create a specification for feature: $ARGUMENTS

## Instructions

### 1. Load Feature Context

```bash
sdlc feature show $ARGUMENTS --json
```

Parse the output to understand the feature current phase, metadata, and any existing artifacts.

### 2. Check for Existing Spec

Read `.sdlc/features/$ARGUMENTS/spec.md` if it exists. If a draft already exists, build on it rather than starting from scratch.

### 3. Gather Codebase Context

Search the codebase for patterns, modules, and systems relevant to this feature. Understand what exists before specifying what should change.

### 4. Write the Specification

Write to `.sdlc/features/$ARGUMENTS/spec.md` with this structure:

```markdown
# Feature: [Title]

## Problem Statement
[What problem does this solve? Who has this problem?]

## User Stories
- As a [role], I want [capability] so that [benefit]

## Acceptance Criteria
- [ ] [Criterion 1 - testable, specific]
- [ ] [Criterion 2]
- [ ] [Criterion N]

## Technical Constraints
[Platform limits, API compatibility, performance requirements]

## Dependencies
[What must exist or be true before this can be built]

## Out of Scope
[Explicitly excluded from this feature]

## Open Questions
[Unresolved decisions that need input]
```

### 5. Register the Artifact

```bash
sdlc artifact create $ARGUMENTS spec
```

The classifier will detect the spec exists and determine the next action (typically awaiting approval).

### 6. Report

Summarize what was specified, list acceptance criteria count, and note any open questions that need human input.

## Critical Rules

- NEVER skip loading feature context first
- ALWAYS include acceptance criteria -- they drive QA later
- NEVER approve your own spec -- it requires human approval
- ALWAYS list open questions rather than making assumptions
- ALWAYS search the codebase before writing constraints
