# Phase 03S: Sprint Planning

## Entry Gate

```bash
devforgeai-validate phase-check ${SPRINT_ID} --workflow=sprint --from=01 --to=03S --project-root=.
```

## Contract

PURPOSE: Execute complete sprint planning workflow including story validation, capacity calculation, sprint document creation, and story status updates. Sprint Planning mode only.
REQUIRED SUBAGENTS: sprint-planner, dependency-graph-analyzer
REQUIRED ARTIFACTS: Sprint file created, stories updated to "Ready for Dev"
STEP COUNT: 7 mandatory steps

## Reference Loading [MANDATORY]

```
# No required references for this phase. Self-contained — operates on
# story files (dynamic-path) and delegates to sprint-planner,
# dependency-graph-analyzer, and file-overlap-detector subagents; no
# static skill reference, context file, or memory entry Read in
# mandatory steps.
```

---

## Mandatory Steps

### Step 1: Sprint Number Discovery

EXECUTE: Use sprint ID from context marker (set by /create-sprint command via sprint-preflight CLI).
```
sprint_id = from "**Sprint ID:**" context marker
IF sprint_id empty:
  # Fallback: use CLI directly (no Glob)
  result = Bash(command="devforgeai-validate sprint-preflight --project-root=. --format=json 2>&1")
  sprint_id = parse result.next_sprint_id from JSON
Display: "Sprint: {sprint_id}"
```

VERIFY: sprint_id is set and follows Sprint-N format.
RECORD: `devforgeai-validate phase-record ${SPRINT_ID} --workflow=sprint --phase=03S --step=3S.1 --project-root=.`

### Step 2: Validate Selected Stories

EXECUTE: Verify all selected stories exist and are in Backlog/Ready for Dev status.
The /create-sprint command already collected stories via sprint-preflight CLI. Validate from context:
```
selected_ids = from "**Selected Stories:**" context marker
valid_stories = []
invalid_stories = []

FOR story_id in selected_ids:
  # Read story file directly (path from sprint-preflight JSON, no Glob needed)
  story_file = "devforgeai/specs/Stories/${story_id}*.story.md"
  Read(file_path=story_file)
  
  status = extract "status:" from frontmatter
  IF status not in ["Backlog", "Ready for Dev"]:
    invalid_stories.append("{story_id}: Status is '{status}'")
  ELSE:
    valid_stories.append(story_id)

IF invalid_stories:
  AskUserQuestion: "{len(invalid_stories)} stories invalid. Continue with {len(valid_stories)}?"
  
IF len(valid_stories) == 0: HALT -- "No valid stories for sprint."
```

VERIFY: At least 1 valid story.
RECORD: `devforgeai-validate phase-record ${SPRINT_ID} --workflow=sprint --phase=03S --step=3S.2 --project-root=.`

### Step 2.5: Dependency Chain Validation [Gate 0S]

EXECUTE: Validate dependency chains for selected stories.
```
# Collect dependencies from story frontmatter (already read in Step 2)
stories_with_deps = [s for s in valid_stories where depends_on is not empty]

IF stories_with_deps is empty:
  Display: "Step 2.5: No dependencies — PASS"
  SKIP to VERIFY

# Invoke dependency-graph-analyzer (graceful fallback if unavailable)
result = Task(subagent_type="dependency-graph-analyzer",
  description="Sprint dependency validation for Gate 0S",
  prompt="Validate dependencies for sprint. Selected: {valid_stories}. Dependencies: {stories_with_deps}")

IF result is None OR ERROR:
  Display: "WARN: dependency-graph-analyzer unavailable — proceeding without validation"
  result = {"status": "PASS"}

IF result.status == "BLOCKED":
  AskUserQuestion: "Dependency issues found. Remove blocking stories, proceed with exception, or HALT?"
```

VERIFY: Dependency validation executed.
RECORD: `devforgeai-validate phase-record ${SPRINT_ID} --workflow=sprint --phase=03S --step=3S.3 --project-root=.`

### Step 2.6: File Overlap Detection [Gate 0S]

EXECUTE: Detect file overlaps between selected stories.
```
result = Task(subagent_type="file-overlap-detector",
  description="Sprint file overlap detection",
  prompt="Analyze file overlaps for: {valid_stories}. Mode: pre-flight.")

IF result is None OR ERROR:
  Display: "WARN: file-overlap-detector unavailable — proceeding"
  result = {"status": "PASS"}

IF result.status in ["WARNING", "BLOCKED"]:
  AskUserQuestion with overlap details and options
```

VERIFY: File overlap check executed.
RECORD: `devforgeai-validate phase-record ${SPRINT_ID} --workflow=sprint --phase=03S --step=3S.4 --project-root=.`

### Step 2.7: Multi-Sprint + Feature Cohesion [Gate 0S]

EXECUTE: Check for multi-sprint conflicts and incomplete feature sets.
```
# Part A: Multi-sprint — check if any story already has a sprint field != Backlog
FOR story_id in valid_stories:
  sprint_field = extract "sprint:" from already-read frontmatter
  IF sprint_field not in ["Backlog", "null", "", sprint_id]:
    multi_sprint_blocked.append(story_id)

IF multi_sprint_blocked:
  AskUserQuestion: "Multi-sprint conflict for {multi_sprint_blocked}. Remove, proceed, or HALT?"

# Part B: Feature cohesion — only if single epic linked
IF EPIC_ID set and not "Multiple":
  Read epic file, check Target Sprints section for partial feature sets
  IF cohesion warnings: AskUserQuestion with options
```

VERIFY: Both checks executed or gracefully skipped.
RECORD: `devforgeai-validate phase-record ${SPRINT_ID} --workflow=sprint --phase=03S --step=3S.5 --project-root=.`

### Step 3: Calculate Capacity

EXECUTE: Sum story points from valid stories.
```
# Points already available from sprint-preflight JSON and story reads
total_points = sum of valid_stories points
Display: "Capacity: {total_points} pts (target: 20-40)"

IF total_points > 40: AskUserQuestion "Over capacity. Proceed?"
IF total_points < 20: AskUserQuestion "Under capacity. Proceed?"
```

VERIFY: Capacity checked.
RECORD: `devforgeai-validate phase-record ${SPRINT_ID} --workflow=sprint --phase=03S --step=3S.6 --project-root=.`

### Step 4: Invoke Sprint-Planner Subagent

EXECUTE: Delegate sprint document creation.
```
Task(subagent_type="sprint-planner",
  prompt="Create sprint document for {sprint_id}.
    Sprint Name: {SPRINT_NAME}
    Stories: {valid_stories}
    Total Points: {total_points}
    Duration: {DURATION} days
    Start Date: {START_DATE}
    Epic: {EPIC_ID}
    Output: Write to devforgeai/specs/Sprints/{sprint_id}.md")
```

VERIFY: Sprint file created.
```
Read(file_path="devforgeai/specs/Sprints/{sprint_id}.md", limit=5)
IF read fails: HALT -- "Sprint file not created."
```
RECORD: `devforgeai-validate phase-record ${SPRINT_ID} --workflow=sprint --phase=03S --step=3S.7 --subagent=sprint-planner --project-root=.`

### Step 5: Update Story Statuses

EXECUTE: Update all valid stories to "Ready for Dev" and set sprint field.
```
FOR story_id in valid_stories:
  Edit story frontmatter:
    status: Backlog → status: Ready for Dev  (or status: In Development if already Ready)
    sprint: Backlog → sprint: {sprint_id}
```

VERIFY: All stories updated.
```
FOR story_id in valid_stories:
  Read story frontmatter, confirm status and sprint fields updated
```
RECORD: (included in phase-complete below)

### Step 6: Generate Sprint Summary

EXECUTE: Display summary for return to calling command.
```
Display:
  Sprint: {sprint_id}
  Name: {SPRINT_NAME}
  Stories: {len(valid_stories)} ({total_points} pts)
  Duration: {DURATION} days
  File: devforgeai/specs/Sprints/{sprint_id}.md
```

VERIFY: Summary displayed.

## Exit Gate

```bash
devforgeai-validate phase-complete ${SPRINT_ID} --workflow=sprint --phase=03S --checkpoint-passed --project-root=.
```
