spec-creation

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}]`

Acceptance Criteria Patterns

User Action Criteria

- [ ] User can {action} -> {result}
- [ ] When user {triggers}, system {responds}
- [ ] User receives {feedback} after {action}

Data Criteria

- [ ] Data persists after {action}
- [ ] User can only see their own {data type}
- [ ] {field} validates {constraint}

Error Criteria

- [ ] Invalid input shows {error message}
- [ ] Network failure shows retry option
- [ ] Unauthorized access returns 401

Pattern Discovery for Specs

Before writing any spec:

# Find existing patterns
ls patterns_library/

# Search for similar implementations
grep -r "similar feature" app/ lib/

# Check existing specs for format
ls specs/

Spec Quality Checklist

Before submitting spec:

• All acceptance criteria are testable (can verify pass/fail)
• Pattern references point to existing patterns
• Success validation command is runnable
• Demo script is step-by-step reproducible
• Logical commits follow SAFe format
• Ticket referenced

Output Locations

Output Type	Location
Impl specs	specs/SPEC-{{TICKET_PREFIX}}-{number}-{description}.md
Requirements	docs/agent-outputs/requirements/{{TICKET_PREFIX}}-*.md
ADRs	docs/adr/ADR-{number}-{description}.md

Evidence for Ticket System

After spec approval:

**BSA Spec Evidence**

**Spec**: specs/SPEC-{{TICKET_PREFIX}}-{number}-{description}.md
**Status**: Approved by [reviewer]

**Deliverables**:
- [x] Acceptance criteria defined
- [x] Pattern references added
- [x] Demo script created
- [x] Ready for implementation

Authoritative References

• Spec Template: docs/archive/specs/spec_template.md
• Pattern Library: patterns_library/README.md
• Planning Guide: docs/team/PLANNING-AGENT-META-PROMPT.md
• SAFe Workflow: CONTRIBUTING.md