# /sdd:story-new

## Meta
- Version: 2.0
- Category: story-management
- Complexity: medium
- Purpose: Create new story with auto-populated template and place in backlog

## Definition
**Purpose**: Create a new story using project context and place it in the backlog folder for future development.

**Syntax**: `/sdd:story-new [story_id_number]`

## Parameters
| Parameter | Type | Required | Default | Description | Validation |
|-----------|------|----------|---------|-------------|------------|
| story_id_number | number | No | auto-increment | Story number (used as STORY-YYYY-NNN) | Positive integer |

## INSTRUCTION: Create New Story

### INPUTS
- story_id_number: Optional story number (auto-increments if not provided)
- Project context from `/docs/project-context/` directory
- User-provided story details (if not in project brief)

### PROCESS

#### Phase 1: Project Context Loading
1. **CHECK** if `/docs/project-context/` directory exists
2. IF missing:
   - SUGGEST running `/sdd:project-init` first
   - EXIT with initialization guidance
3. **LOAD** project context from:
   - `/docs/project-context/project-brief.md` - Existing story definitions, goals
   - `/docs/project-context/technical-stack.md` - Technology implementation requirements
   - `/docs/project-context/coding-standards.md` - Testing and quality requirements

#### Phase 2: Story ID Generation
1. **GENERATE** story ID in format `STORY-YYYY-NNN`:
   - YYYY = current year
   - NNN = sequential number (001, 002, etc.)

2. IF user provides story_id_number:
   - USE as basis: `STORY-YYYY-[story_id_number]`
   - EXAMPLE: Input "5" → "STORY-2025-005"

3. **CHECK** for existing IDs across all directories:
   - SCAN `/docs/stories/backlog/`
   - SCAN `/docs/stories/development/`
   - SCAN `/docs/stories/review/`
   - SCAN `/docs/stories/qa/`
   - SCAN `/docs/stories/completed/`
   - CHECK `/docs/project-context/project-brief.md` for planned stories

4. IF no specific number provided:
   - INCREMENT to next available number
   - ENSURE uniqueness across all locations

#### Phase 3: Story Information Gathering
1. **SEARCH** `/docs/project-context/project-brief.md` for story with generated ID
2. IF story exists in project brief:
   - EXTRACT comprehensive story details:
     * Story title and description
     * User scenarios and use cases
     * Technical implementation requirements
     * Acceptance criteria (pass/fail conditions)
     * Edge cases and error handling requirements
     * UI/UX considerations
     * Testing requirements and test scenarios
     * Integration points with other stories/systems
     * Dependencies on other stories

3. IF story NOT found in project brief:
   - **ASK** user for story title
   - **ASK** user for story description and purpose
   - **ASK** user for acceptance criteria
   - **ASK** user for technical approach (optional)
   - **ASK** user for dependencies (optional)

#### Phase 4: Story File Creation
1. **ENSURE** `/docs/stories/backlog/` directory exists
   - CREATE directory if missing
   - ADD `.gitkeep` file if directory was created

2. **CREATE** story file at `/docs/stories/backlog/[story-id].md`

3. **POPULATE** template with:
   - Story ID and title
   - Status: backlog
   - Today's date as "Started" date
   - Empty "Completed" date
   - Note: "(none - in backlog)" for branch
   - What & Why section (from project brief or user input)
   - Success Criteria (from project brief or user input)
   - Technical Notes with:
     * Approach (from project brief or user input)
     * Stack (auto-populated from technical-stack.md)
     * Concerns (from project brief edge cases or user input)
     * Dependencies (from project brief or user input)
   - Implementation Checklist (standard items)
   - Progress Log with creation entry
   - Test Cases (from project brief or default scenarios)
   - UI/UX Considerations (from project brief if applicable)
   - Integration Points (from project brief if applicable)
   - Rollback Plan section (empty template)
   - Lessons Learned section (empty template)

4. **REFERENCE** project context in template:
   - Pull technology stack from technical-stack.md
   - Note coding standards that will apply
   - Reference testing framework requirements
   - Include project goals and constraints from project-brief.md

#### Phase 5: Completion Summary
1. **DISPLAY** creation summary:
   ```
   ✅ Story Created
   ═══════════════════════════════════

   Story ID: [STORY-YYYY-NNN]
   Title: [Story Title]
   Location: /docs/stories/backlog/[story-id].md
   Status: backlog

   [If from project brief:]
   Source: Extracted from project brief
   - Acceptance criteria: [count] criteria defined
   - Test scenarios: [count] scenarios defined
   - Dependencies: [list or "None"]

   [If from user input:]
   Source: User-provided details
   - Ready for refinement before development
   ```

2. **SUGGEST** next steps:
   ```
   💡 NEXT STEPS:
   1. /sdd:story-start [story-id]     # Move to development and create branch
   2. /sdd:story-implement [story-id]  # Generate implementation code
   3. /sdd:project-status              # View all project stories
   ```

### OUTPUTS
- `/docs/stories/backlog/[story-id].md` - New story file with populated template
- `.gitkeep` file in `/docs/stories/backlog/` if directory was created

### RULES
- MUST generate unique story ID across all story directories
- MUST create backlog directory if it doesn't exist
- MUST auto-populate template with project context
- SHOULD extract story details from project brief if available
- SHOULD reference technical stack in story template
- NEVER create feature branch (stories start in backlog)
- ALWAYS add progress log entry for creation
- MUST include today's date as "Started" date

## Story Template Structure

```markdown
# [STORY-ID]: [Title]

## Status: backlog
**Started:** [Today's Date]
**Completed:**
**Branch:** (none - in backlog)

## What & Why
[Story description and purpose]

## Success Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

## Technical Notes
**Approach:** [Implementation approach]
**Stack:** [Auto-populated from technical-stack.md]
**Concerns:** [Risks and edge cases]
**Dependencies:** [External services/libraries/other stories]

## Implementation Checklist
- [ ] Feature implementation
- [ ] Unit tests
- [ ] Integration tests
- [ ] Error handling
- [ ] Loading states
- [ ] Documentation
- [ ] Performance optimization
- [ ] Accessibility
- [ ] Security review

## Progress Log
- [Today]: Created story, added to backlog

## Test Cases
1. Happy path: [scenario]
2. Error case: [scenario]
3. Edge case: [scenario]

## UI/UX Considerations
[User interface and experience requirements]

## Integration Points
[Dependencies and integration with other systems]

## Rollback Plan
[How to rollback if issues arise]

## Lessons Learned
[To be filled when complete]
```

## Examples

### Example 1: Create from Project Brief
```bash
INPUT:
/sdd:story-new

OUTPUT:
→ Checking project context...
→ Generating story ID: STORY-2025-001
→ Found story definition in project brief

✅ Story Created
═══════════════════════════════════

Story ID: STORY-2025-001
Title: User Authentication System
Location: /docs/stories/backlog/STORY-2025-001.md
Status: backlog

Source: Extracted from project brief
- Acceptance criteria: 5 criteria defined
- Test scenarios: 8 scenarios defined
- Dependencies: None

💡 NEXT STEPS:
1. /sdd:story-start STORY-2025-001     # Move to development and create branch
2. /sdd:story-implement STORY-2025-001  # Generate implementation code
3. /sdd:project-status                  # View all project stories
```

### Example 2: Create with Specific ID
```bash
INPUT:
/sdd:story-new 10

OUTPUT:
→ Checking project context...
→ Using story ID: STORY-2025-010
→ Story not found in project brief, gathering details...

What is the story title?
> Add Dark Mode Toggle

What are you building and why?
> Implement a dark mode toggle in the settings page to allow users to switch between light and dark themes.

What are the acceptance criteria? (Enter each, then empty line when done)
> Toggle is visible in settings page
> Theme persists across sessions
> All UI components support both themes
>

✅ Story Created
═══════════════════════════════════

Story ID: STORY-2025-010
Title: Add Dark Mode Toggle
Location: /docs/stories/backlog/STORY-2025-010.md
Status: backlog

Source: User-provided details
- Ready for refinement before development

💡 NEXT STEPS:
1. /sdd:story-start STORY-2025-010      # Move to development and create branch
2. /sdd:story-implement STORY-2025-010   # Generate implementation code
3. /sdd:project-status                   # View all project stories
```

### Example 3: Auto-Increment ID
```bash
INPUT:
/sdd:story-new

OUTPUT:
→ Checking project context...
→ Found existing stories: STORY-2025-001 through STORY-2025-005
→ Auto-incrementing to: STORY-2025-006
→ Story not found in project brief, gathering details...

[Interactive prompts for story details...]

✅ Story Created
═══════════════════════════════════

Story ID: STORY-2025-006
Title: Payment Processing Integration
Location: /docs/stories/backlog/STORY-2025-006.md
Status: backlog
```

## Edge Cases

### No Project Context
- DETECT missing `/docs/project-context/` directory
- SUGGEST running `/sdd:project-init`
- OFFER to create story with minimal template
- WARN that template won't be auto-populated

### Duplicate Story ID
- DETECT ID conflict across all directories
- INCREMENT to next available number automatically
- LOG warning about skipped number
- ENSURE final ID is unique

### Empty Project Brief
- DETECT missing story definitions
- GATHER all details from user interactively
- CREATE story with user-provided information
- SUGGEST adding stories to project brief

### Malformed Project Brief
- DETECT parsing errors
- LOG warning about brief issues
- FALL BACK to user input mode
- CONTINUE with story creation

## Error Handling
- **Missing /docs/project-context/**: Suggest `/sdd:project-init` with guidance
- **Permission errors**: Report specific file/directory with access issue
- **Invalid story ID**: Sanitize and suggest corrected version
- **User cancels**: Clean up partial creation, exit gracefully

## Performance Considerations
- Story ID checking optimizes by scanning directories once
- Project brief parsing caches results for session
- Template population is fast (< 100ms typically)
- Interactive prompts allow user to control pace

## Related Commands
- `/sdd:project-init` - Initialize project structure first
- `/sdd:project-brief` - Create/update project documentation with stories
- `/sdd:story-start [id]` - Begin development on story
- `/sdd:story-implement [id]` - Generate implementation code
- `/sdd:project-status` - View all project stories

## Constraints
- ✅ MUST generate unique story ID
- ✅ MUST create story in backlog directory
- ⚠️ NEVER create feature branch (stories start in backlog)
- 📋 MUST auto-populate from project context when available
- 🔧 SHOULD extract from project brief before asking user
- 💾 MUST add creation entry to progress log
- 📅 MUST include today's date as "Started" date