docs/templates/sprint_description_format.md

---
title: "Sprint Description Format (Sprint Planning PRD Style)"
type: "sprint_plan"
version: "1.0"
created_by: "AI Development Assistant"
last_updated: "<DATE>"
---

# Sprint Description Format Template

## 📊 Sprint Metadata
```yaml
sprint_id: "<MVP_NUMBER>_S<SPRINT_NUMBER>"
sprint_name: "<DESCRIPTIVE_SPRINT_NAME>"
mvp_parent: "<MVP_ID_AND_NAME>"
sprint_number: <SPRINT_NUMBER>
status: "planned|in_progress|completed|blocked"
priority: "critical|high|medium|low"
timeline:
  planned_start: "<YYYY-MM-DD>"
  planned_end: "<YYYY-MM-DD>"
  duration_estimate: "<X_hours|X_days>"
  actual_start: "<YYYY-MM-DD>"
  actual_end: "<YYYY-MM-DD>"
stakeholders:
  sprint_lead: "<NAME>"
  developers: ["<NAME1>", "<NAME2>"]
  reviewers: ["<NAME1>", "<NAME2>"]
  ai_assistant: "claude|cursor|other"
context:
  development_approach: "ai_assisted_coding"
  coding_standards: "ruff_black_mypy_pytest"
  commit_convention: "conventional_commits"
```

## 🎯 Sprint Goal & Value Proposition

### **Sprint Objective**
<!-- Single, clear statement of what this sprint achieves -->
**Primary Goal:** <ONE_SENTENCE_SPRINT_OBJECTIVE>

### **Problem Context**
**What We're Building On:** <PREVIOUS_SPRINT_OR_MVP_FOUNDATION>
**What We're Solving:** <SPECIFIC_PROBLEM_THIS_SPRINT_ADDRESSES>
**Why Now:** <TIMING_AND_PRIORITY_JUSTIFICATION>

### **Success Criteria**
**Demo-able Outcome:** <WHAT_CAN_BE_DEMONSTRATED_AT_SPRINT_END>
**Technical Milestone:** <KEY_TECHNICAL_ACHIEVEMENT>
**Quality Standard:** <MINIMUM_QUALITY_REQUIREMENTS>

## 🏗️ Technical Architecture & Implementation

### **Architecture Focus**
**Core Components:** <LIST_OF_MAIN_COMPONENTS_BEING_BUILT_OR_MODIFIED>
**Integration Points:** <HOW_NEW_COMPONENTS_INTEGRATE_WITH_EXISTING>
**Data Flow Changes:** <CHANGES_TO_DATA_FLOW_OR_PROCESSING>

### **Technical Approach**
```yaml
implementation_strategy: "<APPROACH_DESCRIPTION>"
design_patterns: ["<PATTERN1>", "<PATTERN2>"]
technology_choices:
  primary_languages: ["Python", "JavaScript"]
  frameworks: ["FastAPI", "Gradio", "etc"]
  testing_frameworks: ["pytest", "etc"]
  development_tools: ["ruff", "mypy", "black"]
```

### **Key Technical Decisions**
1. **Decision:** <TECHNICAL_DECISION_1>
   - **Rationale:** <WHY_THIS_DECISION>
   - **Alternatives:** <OTHER_OPTIONS_CONSIDERED>
   - **Impact:** <CONSEQUENCES_AND_BENEFITS>

2. **Decision:** <TECHNICAL_DECISION_2>
   - **Rationale:** <WHY_THIS_DECISION>
   - **Alternatives:** <OTHER_OPTIONS_CONSIDERED>
   - **Impact:** <CONSEQUENCES_AND_BENEFITS>

## 📋 Task Breakdown & Implementation Plan

### **Task Organization**
```yaml
total_tasks: <NUMBER>
task_methodology: "tdd_with_ai_assistance"
parallel_workstreams: <NUMBER>
task_size_target: "<SMALL|MEDIUM|LARGE> (X_hours each)"
```

### **Task List**
| Task ID | Task Name | Priority | Estimate | Dependencies | Owner | Type |
|---------|-----------|----------|----------|--------------|-------|------|
| <TASK_ID> | <TASK_NAME> | <HIGH|MED|LOW> | <X_hours> | [<DEP1>, <DEP2>] | <OWNER> | <TYPE> |
| <TASK_ID> | <TASK_NAME> | <HIGH|MED|LOW> | <X_hours> | [<DEP1>, <DEP2>] | <OWNER> | <TYPE> |
| <TASK_ID> | <TASK_NAME> | <HIGH|MED|LOW> | <X_hours> | [<DEP1>, <DEP2>] | <OWNER> | <TYPE> |

### **Task Details**

#### **Task <TASK_ID>: <TASK_NAME>**
```yaml
status: "todo|in_progress|done|blocked"
priority: "critical|high|medium|low"
estimated_hours: <NUMBER>
dependencies: ["<TASK_ID1>", "<TASK_ID2>"]
type: "foundation|feature|integration|testing|documentation"
```

**Objective:** <ONE_SENTENCE_TASK_OBJECTIVE>

**Implementation Approach:**
- **Files to Modify:** [`<FILE1>`, `<FILE2>`, `<FILE3>`]
- **Key Classes/Functions:** <LIST_OF_MAIN_CODE_ENTITIES>
- **Testing Strategy:** <HOW_THIS_TASK_WILL_BE_TESTED>

**Acceptance Criteria:**
- [ ] <SPECIFIC_TESTABLE_CRITERION_1>
- [ ] <SPECIFIC_TESTABLE_CRITERION_2>
- [ ] <SPECIFIC_TESTABLE_CRITERION_3>
- [ ] Code quality gates passed (`ruff check`, `mypy`, `pytest`)

**AI Assistant Guidance:**
```
For Claude/Cursor IDE:
- Focus areas: <SPECIFIC_CODING_FOCUS>
- Key patterns to follow: <DESIGN_PATTERNS_OR_CONVENTIONS>
- Testing approach: <TDD_STRATEGY_FOR_THIS_TASK>
- Integration points: <HOW_TO_CONNECT_WITH_EXISTING_CODE>
```

#### **Task <TASK_ID>: <TASK_NAME>**
<!-- Repeat task template for each task -->

## 🧪 Testing & Quality Strategy

### **Testing Approach for This Sprint**
```yaml
unit_testing:
  framework: "pytest"
  coverage_target: ">=80%"
  mock_strategy: "<MOCKING_APPROACH_FOR_SPRINT>"
  tdd_approach: "write_tests_first_with_ai_assistance"
integration_testing:
  scope: "<INTEGRATION_AREAS_TO_TEST>"
  critical_flows: ["<FLOW1>", "<FLOW2>"]
  automation_level: "manual|automated|hybrid"
manual_testing:
  ui_testing: "<UI_TESTING_APPROACH>"
  edge_cases: ["<EDGE_CASE1>", "<EDGE_CASE2>"]
  browser_compatibility: "<BROWSER_TESTING_SCOPE>"
```

### **Quality Gates for Sprint**
- [ ] **Code Quality:** All tasks pass ruff linting and mypy type checking
- [ ] **Test Coverage:** Sprint additions maintain >=80% overall coverage
- [ ] **Functionality:** All acceptance criteria verified through testing
- [ ] **Integration:** New components integrate seamlessly with existing system
- [ ] **Performance:** No regression in performance metrics
- [ ] **Documentation:** Code changes are properly documented

### **Definition of Done (Sprint Level)**
- [ ] All sprint tasks completed and merged
- [ ] Sprint objective demonstrated and validated
- [ ] Quality gates passed for all new code
- [ ] Documentation updated (README, API docs, code comments)
- [ ] CI/CD pipeline green with all checks passing
- [ ] Sprint retrospective completed and lessons captured

## 🔄 Dependencies & Assumptions

### **Prerequisites (What We Need Before Starting)**
- **Previous Sprint Deliverables:** <LIST_OF_REQUIRED_COMPLETIONS>
- **External Dependencies:** <LIST_OF_EXTERNAL_REQUIREMENTS>
- **Environment Setup:** <ANY_SPECIAL_SETUP_REQUIREMENTS>
- **Access/Permissions:** <REQUIRED_ACCESS_OR_CREDENTIALS>

### **Dependencies Within Sprint**
```yaml
critical_path_tasks: [<TASK_ID1>, <TASK_ID2>, <TASK_ID3>]
parallel_workstreams:
  stream_1: [<TASK_ID1>, <TASK_ID2>]
  stream_2: [<TASK_ID3>, <TASK_ID4>]
blocking_dependencies:
  - task: <TASK_ID>
    blocks: [<TASK_ID1>, <TASK_ID2>]
    reason: "<WHY_THIS_BLOCKS_OTHERS>"
```

### **Assumptions**
- **Technical Assumptions:** <LIST_OF_TECHNICAL_ASSUMPTIONS>
- **Resource Assumptions:** <ASSUMPTIONS_ABOUT_AVAILABLE_RESOURCES>
- **External Service Assumptions:** <ASSUMPTIONS_ABOUT_EXTERNAL_DEPENDENCIES>
- **Timeline Assumptions:** <ASSUMPTIONS_ABOUT_TIMING_AND_AVAILABILITY>

## ⚠️ Risk Assessment & Mitigation

### **Risk Matrix**
| Risk | Probability | Impact | Mitigation Strategy | Contingency Plan |
|------|-------------|--------|-------------------|------------------|
| <RISK_DESCRIPTION> | <LOW|MED|HIGH> | <LOW|MED|HIGH> | <MITIGATION_APPROACH> | <FALLBACK_PLAN> |
| <RISK_DESCRIPTION> | <LOW|MED|HIGH> | <LOW|MED|HIGH> | <MITIGATION_APPROACH> | <FALLBACK_PLAN> |

### **Technical Risks**
- **Integration Complexity:** <RISK_DESCRIPTION> → <MITIGATION_STRATEGY>
- **API Dependencies:** <RISK_DESCRIPTION> → <MITIGATION_STRATEGY>
- **Performance Issues:** <RISK_DESCRIPTION> → <MITIGATION_STRATEGY>

### **Timeline Risks**
- **Task Estimation:** <RISK_DESCRIPTION> → <MITIGATION_STRATEGY>
- **Blocking Dependencies:** <RISK_DESCRIPTION> → <MITIGATION_STRATEGY>
- **External Delays:** <RISK_DESCRIPTION> → <MITIGATION_STRATEGY>

## 📈 Progress Tracking & Metrics

### **Daily Progress Indicators**
```yaml
completion_metrics:
  - tasks_completed: "<NUMBER>/<TOTAL>"
  - hours_spent: "<ACTUAL>/<ESTIMATED>"
  - code_lines_added: "<NUMBER>"
  - tests_written: "<NUMBER>"
quality_metrics:
  - test_coverage: "<PERCENTAGE>"
  - linting_errors: "<NUMBER>"
  - type_coverage: "<PERCENTAGE>"
velocity_metrics:
  - tasks_per_day: "<AVERAGE>"
  - blockers_encountered: "<NUMBER>"
  - ai_assist_efficiency: "<QUALITATIVE_ASSESSMENT>"
```

### **Sprint Burndown Tracking**
- **Day 1 Target:** <COMPLETION_PERCENTAGE_AND_TASKS>
- **Day 2 Target:** <COMPLETION_PERCENTAGE_AND_TASKS>
- **Day 3 Target:** <COMPLETION_PERCENTAGE_AND_TASKS>
- **Final Target:** <SPRINT_COMPLETION_CRITERIA>

### **Success Metrics**
- **Primary KPI:** <MAIN_SUCCESS_MEASURE>
- **Quality KPI:** <QUALITY_SUCCESS_MEASURE>
- **Velocity KPI:** <PRODUCTIVITY_SUCCESS_MEASURE>

## 🔗 Deliverables & Handoffs

### **Sprint Deliverables**
```yaml
code_deliverables:
  - component: "<COMPONENT_NAME>"
    files: ["<FILE1>", "<FILE2>"]
    status: "created|modified|refactored"
documentation_deliverables:
  - document: "<DOC_NAME>"
    type: "api|user|technical"
    status: "created|updated"
testing_deliverables:
  - test_suite: "<TEST_SUITE_NAME>"
    coverage: "<PERCENTAGE>"
    type: "unit|integration|e2e"
```

### **Integration Points**
- **With Previous Sprints:** <HOW_THIS_BUILDS_ON_PREVIOUS_WORK>
- **With Parallel Work:** <HOW_THIS_INTEGRATES_WITH_CONCURRENT_DEVELOPMENT>
- **For Next Sprint:** <WHAT_THIS_ENABLES_FOR_FUTURE_WORK>

### **Handoff Documentation**
- **Technical Handoff:** `docs/sprints/mvp<N>_s<N>_technical_summary.md`
- **User Guide Updates:** `docs/user/mvp<N>_s<N>_features.md`
- **API Changes:** `docs/api/mvp<N>_s<N>_api_updates.md`
- **Known Issues:** `docs/sprints/mvp<N>_s<N>_known_issues.md`

## 📚 Resources & References

### **Development Resources**
- **Code Standards:** `.cursor/rules/` directory
- **Testing Patterns:** `tests/` directory examples
- **Architecture Docs:** `docs/architecture/`
- **API Documentation:** `docs/api/`

### **AI Assistant Resources**
- **Cursor Rules:** `.cursor/rules/python_development.mdc`
- **Code Patterns:** `docs/patterns/` directory
- **Testing Helpers:** `tests/helpers/` directory

### **External References**
- **Framework Documentation:** <LINKS_TO_RELEVANT_DOCS>
- **Best Practices:** <LINKS_TO_BEST_PRACTICE_GUIDES>
- **Technical Specifications:** <LINKS_TO_SPECS>

---

## 📝 Template Usage Guidelines

### **When to Use This Format**
- Sprint planning sessions
- Task breakdown and estimation
- Risk assessment and mitigation planning
- Progress tracking and daily standups
- Sprint retrospectives and lessons learned

### **Customization Instructions**
1. Replace all `<PLACEHOLDER>` values with sprint-specific information
2. Adjust task count and structure based on sprint complexity
3. Add sprint-specific sections (e.g., UI design, data migration)
4. Update risk assessment based on sprint-specific challenges
5. Ensure dependencies and assumptions are accurately captured

### **Integration with Development Workflow**
- Use this document for sprint planning meetings
- Reference task details during daily development
- Track progress against defined metrics
- Use for sprint retrospectives and continuous improvement
- Link to individual task files in `docs/tasks/mvp<N>/`

### **AI Assistant Integration**
- Include AI assistant guidance in each task
- Use for prompt engineering and context setting
- Reference for code quality and testing standards
- Integrate with Cursor IDE workflows

---

**Document Status:** Template  
**Next Review:** Before sprint planning  
**Approval Required:** Sprint Lead + MVP Owner