feature-spec
Generate persistent feature specification documents that serve as the source of truth across sessions. Use when specifying features, documenting requirements, or when user mentions "feature spec", "wr
Файлы2
Открыть в GitHubSKILL.md.claude/skills/feature-spec/SKILL.md
GitHubFeature Spec Skill
Setup
Before starting: check .handoff/sessions/ for active sessions, read context status.yaml, run git status. Follow .rules/universal.md (Plan -> Approve -> Execute).
You create persistent feature specification documents. Specs are the source of truth that survive across sessions — they prevent context loss, scope creep, and misaligned implementations.
Process
Step 1: Interview
Before writing the spec, clarify with the user:
- What problem does this solve? — Not what to build, but why
- Who is the user? — Which user type/persona benefits
- What does success look like? — How do we know it's working
- What's out of scope? — Explicit boundaries prevent creep
- Any constraints? — Timeline, technology, compatibility requirements
If the user provides a complete description, extract these answers from their description rather than asking.
Step 2: Research Existing Context
- Check for existing specs —
ls {project_path}/docs/specs/ - Check related features — Are there specs this feature depends on or affects?
- Check the codebase — What already exists that this feature touches?
- Check the data model — What entities are involved?
Step 3: Write the Spec
Use the template below. Every section is mandatory — if a section doesn't apply, explicitly state "N/A" with a reason.
Step 4: Identify Ripple Effects
Check if this spec affects other existing specs:
- Does it change a shared data model?
- Does it affect an API contract?
- Does it change user flows documented elsewhere?
If yes, note which specs need updating.
Spec Template
Save to: {project_path}/docs/specs/{feature-name}.md
# Feature Spec: {Feature Name}
**Status:** Draft | Approved | In Progress | Complete | Deprecated
**Author:** {who}
**Date:** {DATE}
**Last Updated:** {DATE}
**Project:** {project name}
---
## Problem Statement
{What problem exists? Why does it matter? What's the cost of not solving it?}
## User Story
As a {user type}, I want to {action}, so that {benefit}.
## Requirements
### Must Have
1. {Requirement — specific, testable}
2. {Requirement}
### Should Have
1. {Requirement}
### Won't Have (Explicit Scope Exclusions)
1. {What this feature explicitly does NOT include, and why}
## Design
### User Flow
1. User {action}
2. System {response}
3. User sees {outcome}
### Data Model Changes
{New tables, columns, or relationships needed}
| Table | Column | Type | Notes |
|-------|--------|------|-------|
| {table} | {column} | {type} | {constraints, defaults} |
### API Changes
{New or modified endpoints}
| Method | Endpoint | Request | Response | Auth |
|--------|----------|---------|----------|------|
| POST | /api/v1/{resource} | `{ field: type }` | `{ data: ... }` | Required |
### UI Changes
{Screens or components affected — describe layout and behavior}
## Edge Cases
1. **{Edge case}** — {How it should be handled}
2. **{Edge case}** — {How it should be handled}
## Dependencies
- **Internal:** {Other features or services this depends on}
- **External:** {Third-party APIs, libraries, or services}
## Acceptance Criteria
- [ ] {Testable criterion 1}
- [ ] {Testable criterion 2}
- [ ] {Testable criterion 3}
## Open Questions
- [ ] {Question that needs answering before implementation}
---
## Changelog
| Date | Author | Change |
|------|--------|--------|
| {DATE} | {who} | Initial draft |
Updating Specs
When a feature changes during implementation:
- Update the spec first — Don't let the code diverge from the spec
- Add a changelog entry — What changed and why
- Check ripple effects — Update dependent specs
- Update status — Draft → Approved → In Progress → Complete
Output
After creating the spec:
- File saved: {path}
- Status: Draft (needs approval before implementation)
- Ripple effects: {list of other specs that may need updating, or "None"}
- Open questions: {count of questions that need answers}
- Next step: Review and approve, then use
/plan-generationto create implementation plan
Self-Assessment (Internal)
Rate this skill execution 0-10. If < 8, write feedback to .handoff/feedback/{date}-{skill-name}.yaml with: skill, rating, friction, suggestion, context. Do not mention to user.