# Backlog Grooming Workflow

**Project**: {{ project.name }}
**Workflow**: Backlog Grooming
**Purpose**: Refine and prioritize backlog items for upcoming sprints

## Output Formatting Requirements

**IMPORTANT**: Use actual Unicode emojis in reports, NOT GitHub-style shortcodes:
- ✅ Ready for sprint | ⚠️ Needs refinement | ❌ Not ready
- 🔴 High priority | 🟡 Medium | 🟢 Low
- 📋 User story | 🐛 Bug | 🔧 Technical debt

## Overview

This workflow analyzes unrefined backlog items, assigns business value scores, identifies missing requirements, and prepares items for sprint planning.

## Prerequisites

- Access to {{ work_tracking.platform }}{% if work_tracking.platform == 'azure-devops' %} ({{ work_tracking.organization }}){% endif %}

- Backlog items in "New" or "Proposed" state
- Understanding of project priorities and business goals

## Initialize Work Tracking

```python
# Initialize work tracking adapter (auto-selects Azure DevOps or file-based)
import sys
sys.path.insert(0, ".claude/skills")
from work_tracking import get_adapter

adapter = get_adapter()
print(f"📋 Work Tracking: {adapter.platform}")
```

## Workflow Steps

### Step 0: Epic Detection and Decomposition

**Detect Epic-sized items in backlog:**

```python
# Query for Epics and large items
epics = adapter.query_work_items(
    filters={
        'System.State': ['New', 'Proposed'],
        'System.WorkItemType': ['{{ work_tracking.work_item_types.epic or "Epic" }}']
    }
)

# Also find items with large story point estimates (>30 pts)
{% if work_tracking.custom_fields.story_points %}
large_items = adapter.query_work_items(
    filters={
        'System.State': ['New', 'Proposed'],
        '{{ work_tracking.custom_fields.story_points }}': '>30'
    }
)
epics.extend([item for item in large_items if item not in epics])
{% endif %}

print(f"📦 Found {len(epics)} Epic-sized items requiring decomposition")
for epic in epics:
    print(f"  WI-{epic['id']}: {epic.get('title', 'Untitled')} [{epic.get('type', 'Unknown')}]")
```

**For each Epic, decompose into Features and Tasks:**

{% if config.is_agent_enabled('senior-engineer') %}
**Call `/senior-engineer` agent for each Epic:**

```
## YOUR TASK: Decompose Epic into Features and Tasks

Analyze the following Epic and break it down into a hierarchy of Features and Tasks.

### Epic Details
- ID: {epic['id']}
- Title: {epic['title']}
- Description: {epic['description']}
- Business Value: {epic.get('business_value', 'Not specified')}
{% if work_tracking.custom_fields.story_points %}
- Story Points: {epic.get('story_points', 'Not estimated')}
{% endif %}

### Decomposition Requirements

1. **Feature Extraction**: Identify 3-7 Features that comprise this Epic
   - Each Feature should represent a cohesive capability that is measurable, testable, and valuable
   - Features should be independently deliverable
   - Estimate story points for each Feature (5-20 pts ideal)

2. **Task Breakdown**: For each Feature, identify 2-5 Tasks that implement the Feature
   - Each Task should be a specific, actionable work item (1-5 story points)
   - Include implementation tasks, testing tasks, and deployment tasks
   - Tasks must have clear acceptance criteria
   - Exactly one task should request the complete implementation of the Feature code and comprehensive tests, and it should contain enough context for an engineer to implement both the code and the tests solely based on the Task description and, if any, attachments. The Task should include detailed function specification of each testable technical task for an engineer to implement. The tests should be falsifiable and comprehensive relative to the scope and goals of the Feature. The test type and requirements should be project-stage aware, be labelled according to the project's test classification taxonomy, and be designed to provide evidence that the feature was implemented completely.
   - Exactly one tasks should request the running of the tests created in the implementation task, collecting results, verifying falsifiable of the tests, confirming code coverage, and confirming feature coverage of the tests.
   - Deployment tasks if Feature requires deployment
   - All Tasks should be non-overlapping and completable within one sprint

3. **Dependency Analysis**: Identify dependencies between Features and Tasks
   - Which Features must be completed before others?
   - Which Tasks have dependencies on other Tasks?
   - Are there external dependencies (APIs, data, infrastructure)?

4. **Verification**: Ensure decomposition is complete
   - Sum of Task story points within each Feature should equal Feature estimate
   - Sum of Feature story points should approximate Epic estimate
   - All Epic acceptance criteria covered by Feature/Task breakdown
   - No orphaned requirements (everything has a Feature and Tasks)

### Output Format

Return JSON with Epic decomposition:
```json
{
  "epic_id": {epic['id']},
  "epic_title": "{epic['title']}",
  "features": [
    {
      "title": "Feature 1: User Authentication",
      "description": "Implement secure user authentication with OAuth2. Users need ability to log in using their existing Google or GitHub accounts instead of creating new credentials. System must issue JWT tokens for authenticated sessions and support token refresh for long-lived sessions.",
      "story_points": 13,
      "acceptance_criteria": [
        "Users can log in with Google/GitHub OAuth",
        "JWT tokens issued on successful auth",
        "Token refresh mechanism implemented",
        "Failed auth attempts logged and rate-limited",
        "User can revoke access tokens"
      ],
      "tasks": [
        {
          "title": "Implement OAuth2 integration and JWT token service",
          "description": "Integrate Google/GitHub OAuth providers and create JWT token generation service. Configure OAuth callback endpoints, implement JWT signing with RS256, and create token validation logic.",
          "story_points": 8,
          "acceptance_criteria": [
            "OAuth callback endpoints created for Google and GitHub",
            "Provider SDKs configured and tested",
            "JWT service generates valid tokens with user claims",
            "Token validation correctly rejects invalid/expired tokens",
            "Unit tests achieve >80% coverage for auth components"
          ]
        },
        {
          "title": "Run and verify authentication tests",
          "description": "Execute all authentication tests (unit, integration, security), verify test falsifiability, confirm code coverage meets standards, and validate feature completeness.",
          "story_points": 3,
          "acceptance_criteria": [
            "All unit tests pass for OAuth and JWT components",
            "Integration tests verify full OAuth flow",
            "Security tests confirm token validation robustness",
            "Code coverage meets project minimum (80%)",
            "Tests are falsifiable (can detect actual failures)"
          ]
        },
        {
          "title": "Deploy authentication service to staging",
          "description": "Deploy OAuth and JWT services to staging environment, configure environment variables, and verify functionality in staging.",
          "story_points": 2,
          "acceptance_criteria": [
            "Services deployed to staging environment",
            "OAuth providers configured with staging credentials",
            "Smoke tests pass in staging",
            "Monitoring and logging verified"
          ]
        }
      ],
      "dependencies": ["Database schema for user accounts"]
    }
  ],
  "total_story_points": 65,
  "verification": {
    "epic_estimate": {epic.get('story_points', 'N/A')},
    "decomposed_total": 65,
    "variance_percent": 8,
    "all_acceptance_criteria_covered": true,
    "missing_requirements": []
  }
}
```
```

**After agent completes:**

1. Parse Epic decomposition JSON
2. Verify decomposition quality (story points sum, acceptance criteria coverage)
3. Create work item hierarchy:

```python
epic_id = epic['id']
decomposition = agent_result  # JSON from agent

# Create Features under Epic
for feature_data in decomposition['features']:
    # Build comprehensive Feature description
    feature_description = f"""{feature_data['description']}

## Acceptance Criteria
{chr(10).join(f"- {ac}" for ac in feature_data['acceptance_criteria'])}

## Dependencies
{chr(10).join(f"- {dep}" for dep in feature_data.get('dependencies', [])) if feature_data.get('dependencies') else 'None'}

## Parent Epic
WI-{epic_id}: {epic['title']}

---
*Feature created via /backlog-grooming*
"""

    # Create Feature work item
    feature = adapter.create_work_item(
        work_item_type="{{ work_tracking.work_item_types.feature }}",
        title=feature_data['title'],
        description=feature_description,
        fields={
            'System.Parent': epic_id,  # Link to parent Epic
            'System.State': 'Proposed',  # Ready for sprint planning
            {% if work_tracking.custom_fields.story_points %}
            '{{ work_tracking.custom_fields.story_points }}': feature_data['story_points'],
            {% endif %}
            'System.Tags': 'epic-decomposed; ready-for-planning'
        }
    )

    print(f"  ✓ Created Feature WI-{feature['id']}: {feature_data['title']} ({feature_data['story_points']} pts)")

    # Create Tasks under Feature
    for task_data in feature_data.get('tasks', []):
        task_description = f"""{task_data['description']}

## Acceptance Criteria
{chr(10).join(f"- {ac}" for ac in task_data['acceptance_criteria'])}

## Parent Feature
WI-{feature['id']}: {feature_data['title']}

---
*Task created via /backlog-grooming*
"""

        task = adapter.create_work_item(
            work_item_type="{{ work_tracking.work_item_types.task }}",
            title=task_data['title'],
            description=task_description,
            fields={
                'System.Parent': feature['id'],  # Link to parent Feature
                'System.State': 'Proposed',  # Ready for sprint planning
                {% if work_tracking.custom_fields.story_points %}
                '{{ work_tracking.custom_fields.story_points }}': task_data['story_points'],
                {% endif %}
                'System.Tags': 'epic-decomposed; ready-for-sprint'
            }
        )

        print(f"    ✓ Created Task WI-{task['id']}: {task_data['title']} ({task_data['story_points']} pts)")

# Update Epic state
adapter.update_work_item(
    work_item_id=epic_id,
    state='Proposed',  # Mark as decomposed but not yet approved
    fields={'System.Tags': epic.get('tags', '') + ';decomposed'}
)

print(f"✅ Epic WI-{epic_id} decomposed into {len(decomposition['features'])} Features")
```

4. Verify hierarchy created correctly:

```python
# Query children of Epic
children = adapter.query_work_items(
    filters={'System.Parent': epic_id}
)

expected_count = len(decomposition['features'])
actual_count = len(children)

if actual_count != expected_count:
    print(f"⚠️  Verification failed: Expected {expected_count} Features, got {actual_count}")
else:
    print(f"✅ Verification passed: All {expected_count} Features created")

# Verify story points sum
{% if work_tracking.custom_fields.story_points %}
total_child_points = sum(
    child.get('fields', {}).get('{{ work_tracking.custom_fields.story_points }}', 0) or 0
    for child in children
)
epic_points = epic.get('fields', {}).get('{{ work_tracking.custom_fields.story_points }}', 0) or 0
variance = abs(total_child_points - epic_points) / epic_points * 100 if epic_points > 0 else 0

print(f"📊 Story Points - Epic: {epic_points}, Children: {total_child_points}, Variance: {variance:.1f}%")

if variance > 20:
    print(f"⚠️  High variance - review decomposition")
{% endif %}
```

{% endif %}

**If no Epics found, continue to Step 0.5.**

---

### Step 0.5: Detect and Handle Childless Work Items

**Check for orphaned Epics and Features that need decomposition:**

```python
# Find Epics without Features (childless Epics)
childless_epics = []
for epic in adapter.query_work_items(filters={'System.WorkItemType': ['{{ work_tracking.work_item_types.epic }}']}):
    children = adapter.query_work_items(filters={'System.Parent': epic['id']})
    if len(children) == 0 and epic.get('state') not in ['Done', 'Removed']:
        childless_epics.append(epic)

# Find Features without parent Epic (standalone Features that might need breakdown)
orphaned_features = []
for feature in adapter.query_work_items(filters={'System.WorkItemType': ['{{ work_tracking.work_item_types.feature }}']}):
    if not feature.get('parent') and feature.get('state') in ['New', 'Proposed']:
        # Check if this Feature is too large (>20 story points suggests it needs breakdown)
        {% if work_tracking.custom_fields.story_points %}
        story_points = feature.get('fields', {}).get('{{ work_tracking.custom_fields.story_points }}', 0) or 0
        if story_points > 20:
            orphaned_features.append(feature)
        {% endif %}

print(f"🔍 Found {len(childless_epics)} Epics needing decomposition")
print(f"🔍 Found {len(orphaned_features)} large Features needing breakdown")

# For childless Epics, decompose into Features (same process as Step 0)
for epic in childless_epics:
    print(f"\n📦 Decomposing childless Epic WI-{epic['id']}: {epic['title']}")
    # Use the same Epic decomposition logic from Step 0
    # Call /senior-engineer agent to break down Epic into Features
    # Create Features as children of the Epic

# Note: Orphaned Features stay as Features - they'll be broken into Tasks during /sprint-planning
# We just flag them for review
if orphaned_features:
    print(f"\n⚠️  Large Features found (will be broken into Tasks during sprint planning):")
    for feature in orphaned_features:
        print(f"  WI-{feature['id']}: {feature['title']}")
```

---

{% if config.is_agent_enabled('business-analyst') %}
### Step 1: Business Analyst - Backlog Analysis

1. **Read agent definition:** `.claude/agents/business-analyst.md`
2. **Task:** "Analyze the following backlog items and perform business value assessment:
   - Review each item for clarity and completeness
   - Assign business value scores (1-100)
   - Identify items that align with strategic goals
   - Flag items with missing acceptance criteria
   - Recommend prioritization"
3. **Spawn agent** using Task tool with model `{{ config.get_agent_model('analyst') }}`
4. **Query backlog items:**
{% if work_tracking.platform == 'azure-devops' %}
   ```bash
   # Get backlog items in New/Proposed state
   az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.TeamProject] = '{{ work_tracking.project }}' AND [System.State] IN ('New', 'Proposed') AND [System.WorkItemType] = '{{ work_tracking.work_item_types.story }}' ORDER BY [System.ChangedDate] DESC" --output json
   ```
{% else %}
   ```python
   # Get backlog items in New/Proposed state
   all_items = adapter.query_work_items()
   backlog_items = [
       item for item in all_items
       if item.get('state') in ['New', 'Proposed']
       and item.get('type') in ['User Story', 'Feature', '{{ work_tracking.work_item_types.story }}']
   ]

   print(f"📋 Backlog Items for Grooming ({len(backlog_items)}):")
   for item in backlog_items:
       print(f"  WI-{item['id']}: {item['title']} [{item['state']}]")
   ```
{% endif %}
5. **Display output** to user:
   - Read task result
   - Format business value assessments
   - Display recommendations
6. **Collect:**
   - Business value scores for each item
   - Priority recommendations
   - Gaps and missing information

{% endif %}
{% if config.is_agent_enabled('architect') %}
### Step 2: Project Architect - Technical Feasibility Review

1. **Read agent definition:** `.claude/agents/architect.md`
2. **Task:** "Review backlog items for technical feasibility and architecture implications:
   - Identify technical dependencies
   - Assess complexity and risk
   - Flag items requiring architecture decisions
   - Recommend technical spikes if needed
   - Estimate relative effort (T-shirt sizing)"
3. **Spawn agent** using Task tool with model `{{ config.get_agent_model('architect') }}`
4. **Input:** Backlog items from Step 1
5. **Display output** to user
6. **Collect:**
   - Technical risk assessments
   - Dependency mappings
   - Spike recommendations
   - Effort estimates (S/M/L/XL)

{% endif %}
### Step 3: Human Review & Approval Gate

**Instructions for User:**
1. Review the business value assessments and technical evaluations
2. Adjust priorities based on your knowledge
3. Confirm which items should be refined further
4. Type "proceed" to continue with updates

**Wait for user confirmation before proceeding.**

### Step 4: Update Work Items with Findings

1. **For each backlog item to update:**
   - Update {{ work_tracking.custom_fields.business_value or 'Business Value' }} field
   - Update {{ work_tracking.custom_fields.technical_risk or 'Technical Risk' }} field
   - Add refinement notes to description
   - Update state to "Ready" if complete

2. **Update work items with refinement data:**
   ```python
   # Update each refined item
   for item in refined_items:
       result = adapter.update_work_item(
           work_item_id=item['id'],
           state='Ready' if item.get('is_complete') else 'Proposed',
           fields={
               '{{ work_tracking.custom_fields.business_value or "Custom.BusinessValue" }}': item.get('business_value'),
               '{{ work_tracking.custom_fields.technical_risk or "Custom.TechnicalRisk" }}': item.get('technical_risk'),
           },
           verify=True
       )

       # Add grooming notes as comment
       if item.get('notes'):
           adapter.add_comment(
               work_item_id=item['id'],
               comment=f"Grooming notes: {item['notes']}"
           )

       print(f"  ✓ Updated WI-{item['id']}: {item.get('title', 'Unknown')}")
   ```

3. **Track progress:**
   ```python
   state.record_work_item_updated(item_id, {'action': 'refined'})
   ```

### Step 5: Generate Grooming Summary

Create summary report with:
- Total items reviewed
- Items moved to "Ready" state
- Items requiring more information
- Recommended items for next sprint
- Outstanding technical questions

## Success Criteria

- ✅ All backlog items have business value scores
- ✅ Technical risks identified and documented
- ✅ Items ready for sprint planning are in "Ready" state
- ✅ Missing information clearly flagged
- ✅ Priorities aligned with business goals

## Post-Workflow

1. Share grooming summary with stakeholders
2. Schedule follow-up meetings for unclear items
3. Update product roadmap based on priorities
4. Prepare refined backlog for sprint planning

## Configuration

**Agents Used:**
{% if config.is_agent_enabled('business-analyst') %}- Business Analyst{% endif %}
{% if config.is_agent_enabled('architect') %}- Project Architect{% endif %}

**Quality Standards:**
- Business value scoring: 1-100 scale
- Technical risk: Low/Medium/High
- Minimum acceptance criteria: Yes/No

**Work Item Types:**
- {{ work_tracking.work_item_types.story or 'User Story' }}
- {{ work_tracking.work_item_types.feature or 'Feature' }}

---

*Generated by Trustable AI Workbench for {{ project.name }}*
