spec-creation

Spec Creation Skill

TEMPLATE: This skill uses {{PLACEHOLDER}} tokens. Replace with your project values before use.

Purpose

Guide spec creation with clear acceptance criteria, pattern references for execution agents, and testable success validation commands.

When This Skill Applies

• Creating implementation specs
• Breaking down user stories
• Defining acceptance criteria
• Adding pattern references for execution
• Creating demo scripts for validation
• Translating business requirements to technical specs

Stop-the-Line Conditions

FORBIDDEN Patterns

# FORBIDDEN: Missing acceptance criteria
## Implementation
Just do the thing.

# FORBIDDEN: No pattern reference
## Technical Approach
Build it however you want.

# FORBIDDEN: No success validation
## Done Criteria
Looks good to reviewer.

CORRECT Patterns

# CORRECT: Clear acceptance criteria
## Acceptance Criteria
- [ ] User can click button -> modal appears
- [ ] Modal shows validation errors for empty fields
- [ ] Successful submission shows success toast

# CORRECT: Pattern reference for execution
## Pattern Reference
- **UI Pattern**: `patterns_library/ui/modal-form.md`
- **API Pattern**: `patterns_library/api/crud-endpoint.md`
- **RLS Pattern**: `patterns_library/security/rls-user-data.md`

# CORRECT: Success validation command
## Success Validation
{{CI_VALIDATE_COMMAND}}

Spec Template (MANDATORY)

Every spec must include:

# SPEC-{{TICKET_PREFIX}}-{number}: {Feature Name}

## Summary
{One paragraph describing the feature}

## User Story
As a [user type], I want [goal] so that [benefit].

## Acceptance Criteria
- [ ] {Testable criterion 1}
- [ ] {Testable criterion 2}
- [ ] {Testable criterion 3}

## Pattern References
- **UI**: `patterns_library/ui/{pattern}.md`
- **API**: `patterns_library/api/{pattern}.md`
- **Database**: `patterns_library/database/{pattern}.md`
- **Security**: Follow RLS patterns in `docs/database/RLS_IMPLEMENTATION_GUIDE.md`

## Success Validation Command
{validation command}

## Demo Script
1. Navigate to {page}
2. Click {button}
3. Observe {expected behavior}
4. Verify {success indicator}

## Logical Commits
1. `feat(scope): implement data model [{{TICKET_PREFIX}}-{number}]`
2. `feat(scope): add API endpoint [{{TICKET_PREFIX}}-{number}]`
3. `feat(scope): create UI component [{{TICKET_PREFIX}}-{number}]`
4. `test(scope): add unit tests [{{TICKET_PREFIX}}-{number}]`