Story Fix Review Command

Purpose

Use the report generated by /lazy story-review to systematically fix all issues found during the review of a user story using specialized sub-agents.

Introduction

<role>Story Fix Coordinator with expertise in issue remediation, quality assurance, and automated testing</role>

This command transforms story review feedback into actionable fixes by:

1. Resolving story ID to find report file in project-management/US-STORY directory
2. Parsing the US-X.X_REPORT.md generated by story-review
3. Identifying which tasks need fixes with GitHub issue links
4. Invoking appropriate sub-agents for remediation
5. Running quality pipeline for each fix
6. Committing fixes with GitHub issue references
7. Re-running story-review for final approval
8. Creating PR and updating GitHub issues

Prerequisites

<requirements> - Story directory exists in ./project-management/US-STORY/ - US-X.X_REPORT.md exists (generated by `/lazy story-review`) - Git repository with feature branch checked out - All task commits exist on current branch - Clean working tree (no uncommitted changes) - Quality pipeline tools installed (Black, Ruff, Mypy, Pytest) - GitHub CLI authenticated (gh auth status) </requirements>

Main Tasks

1. Resolve Story and Load Report

<story_id_or_path>$1</story_id_or_path> <base_branch>${2:-main}</base_branch>

<thinking> First, I need to determine if the input is a story ID (US-X.Y) or a full path to the report. If it's a story ID, find the story directory and locate the report file. Then load and parse all issues identified. Each issue should have: severity, category, affected files, proposed solution, and GitHub issue reference. </thinking>

Immediate Actions:

<task_list>

• Resolve story ID or path to find story directory
• Locate US-X.X_REPORT.md in story directory
• Verify US-story.md and TASKS/ directory exist
• Load report using Read tool
• Parse report structure to extract all issues
• Categorize issues by type: CRITICAL, WARNING, SUGGESTION
• Identify affected tasks for each issue
• Extract file locations and line numbers
• Load GitHub issue numbers from task files
• Get git log to understand previous commits
• Verify clean working tree: git status --porcelain </task_list>

Story Resolution Logic:

# Determine if input is story ID or full path
story_input="$1"

if [[ "$story_input" =~ ^US-[0-9]+\.[0-9]+$ ]]; then
    # Input is story ID - find story directory
    echo "📁 Resolving story ID: $story_input"

    story_dir=$(find ./project-management/US-STORY -name "US-${story_input}-*" -type d | head -1)

    if [[ -z "$story_dir" ]]; then
        echo "❌ Error: Story US-${story_input} not found"
        echo ""
        echo "Available stories:"
        ls -1 ./project-management/US-STORY/ | grep "^US-"
        exit 1
    fi

    # Look for report file in story directory (try new format first, fall back to old)
    report_file="${story_dir}/${story_input}-review-report.md"

    if [[ ! -f "$report_file" ]]; then
        # Try old format
        report_file="${story_dir}/${story_input}_REPORT.md"

        if [[ ! -f "$report_file" ]]; then
            echo "❌ Error: Report not found at $report_file"
            echo ""
            echo "💡 Run: /lazy review $story_input"
            exit 1
        fi
    fi

    story_file="${story_dir}/US-story.md"
    tasks_dir="${story_dir}/TASKS"
    story_id="$story_input"

else
    # Assume it's a full path to report
    report_file="$story_input"

    if [[ ! -f "$report_file" ]]; then
        echo "❌ Error: Report file not found: $report_file"
        exit 1
    fi

    story_dir=$(dirname "$report_file")
    story_id=$(basename "$report_file" | grep -oE "US-[0-9]+\.[0-9]+")
    story_file="${story_dir}/US-story.md"
    tasks_dir="${story_dir}/TASKS"
fi

# Verify directory structure
if [[ ! -f "$story_file" ]]; then
    echo "❌ Error: US-story.md not found in $story_dir"
    echo "Story directory may be corrupted"
    exit 1
fi

if [[ ! -d "$tasks_dir" ]]; then
    echo "❌ Error: TASKS directory not found in $story_dir"
    echo "Story directory may be corrupted"
    exit 1
fi

echo "✅ Story resolved:"
echo "   ID: $story_id"
echo "   Directory: $story_dir"
echo "   Report: $(basename $report_file)"
echo ""

2. Issue Analysis and Automatic Agent Selection

Agent Selection Logic:

Based on issue category extracted from the review report, the appropriate agent is automatically selected:

• Security, Code Issue, Bug Fix → Coder Agent (.claude/agents/coder.md)
• Test Gap, Missing Tests → Tester Agent (.claude/agents/tester.md)
• Architecture, Design Pattern → Refactor Agent (.claude/agents/refactor.md)
• Documentation, Docstrings → Documentation Agent (.claude/agents/documentation.md)
• Performance, Optimization → Coder Agent (.claude/agents/coder.md)

Agent Selection Benefits:

• Simple category-to-agent mapping
• Consistent agent invocation pattern
• Easy to update agent assignments
• Each issue type routed to specialized agent

3. Systematic Issue Resolution

<critical_requirement> Each issue MUST be fixed individually with:

1. Agent invocation for fix
2. Quality pipeline validation
3. Individual commit with descriptive message
4. Git tag for tracking </critical_requirement>

Fix Execution Loop

For each issue in report (ordered by severity: CRITICAL → WARNING → SUGGESTION):

<fix_workflow>

Step 1: Prepare Issue Context

Load from report:
- Issue ID and title
- Severity level
- Category
- Affected files with line numbers
- Problem description
- Proposed solution
- Related task IDs

Step 2: Load Related Context

# Extract task ID from issue
task_id=$(echo "$issue" | grep -oE "TASK-[0-9]+\.[0-9]+")

if [[ -n "$task_id" ]]; then
    # Find task file in TASKS directory
    task_file="${tasks_dir}/${task_id}.md"

    if [[ ! -f "$task_file" ]]; then
        echo "❌ Error: Task file not found: $task_file"
        exit 1
    fi

    # Extract GitHub issue number from task file
    github_issue=$(grep "GitHub Issue: #" "$task_file" | sed 's/.*#//')

    if [[ -z "$github_issue" ]]; then
        echo "⚠️ Warning: No GitHub issue found in $task_file"
    fi

    # Get task details
    task_content=$(cat "$task_file")

    # Get previous commits for task
    git log --grep="TASK-${task_id}" --oneline

    # Get current file content
    cat ${affected_file}
else
    echo "⚠️ Warning: Could not extract task ID from issue"
fi

Step 3: Invoke Appropriate Agent

Based on issue category, invoke agent via Task tool:

# For code issues:
Task: @agent-coder
Input:
  - Issue description: ${issue_description}
  - Affected files: ${file_list}
  - Proposed solution: ${proposed_fix}
  - Task context: ${task_details}
  - Acceptance criteria: ${criteria_from_story}
Output: Fixed code with implementation

# For test gaps:
Task: @agent-tester
Input:
  - Missing coverage: ${uncovered_lines}
  - Edge cases: ${missing_scenarios}
  - Affected modules: ${module_list}
Output: Additional tests with assertions

# For architecture issues:
Task: @agent-refactor
Input:
  - Architecture concern: ${issue_description}
  - Current implementation: ${code_snippet}
  - Recommended pattern: ${proposed_pattern}
Output: Refactored code with improved design

# For documentation issues:
Task: @agent-documentation
Input:
  - Documentation gap: ${missing_docs}
  - Code to document: ${code_files}
  - Format: ${docstring|readme|api}
Output: Complete documentation

# For security issues:
Task: @agent-coder
Input:
  - Security vulnerability: ${vuln_description}
  - Attack vector: ${exploit_scenario}
  - Mitigation strategy: ${recommended_fix}
  - Security context: "CRITICAL - focus on security best practices"
Output: Secure implementation

Step 4: Run Quality Pipeline (MUST ALL PASS)

# Format with Black and Ruff
python scripts/format.py ${affected_files}

# Lint with Ruff
python scripts/lint.py ${affected_files}

# Type check with Mypy
python scripts/type_check.py ${affected_files}

# Run tests with Pytest
python scripts/test_runner.py tests/

# If ANY step fails: STOP, report error, retry fix

Step 5: Review Fix

Task: @agent-reviewer
Input:
  - Original issue: ${issue_description}
  - Implemented fix: ${fixed_code}
  - Quality results: ${pipeline_output}
  - Acceptance criteria: ${criteria}
Output: APPROVED or CHANGES_NEEDED

Step 6: Commit Fix (only if review approved)

# Determine commit type from issue category
case ${issue_category} in
  "Security") commit_type="fix" ;;
  "Bug"|"Code Issue") commit_type="fix" ;;
  "Test Gap") commit_type="test" ;;
  "Documentation") commit_type="docs" ;;
  "Architecture") commit_type="refactor" ;;
  "Performance") commit_type="perf" ;;
  *) commit_type="fix" ;;
esac

# Build commit message with GitHub issue reference
if [[ -n "$github_issue" ]]; then
    commit_msg="${commit_type}(${task_id}): ${issue_title}

Fixes issue from story review report

Related to #${github_issue}

Changes:
- ${issue_description}
- ${solution_summary}

Issue Severity: ${severity}
Location: ${file_locations}

Quality: format ✓ lint ✓ type ✓ test ✓
Review: APPROVED ✓

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>"
else
    commit_msg="${commit_type}(${task_id}): ${issue_title}

Fixes issue from story review report:
- ${issue_description}
- ${solution_summary}

Issue: #${issue_number} (${severity})
Location: ${file_locations}

Quality: format ✓ lint ✓ type ✓ test ✓
Review: APPROVED ✓

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>"
fi

# Create commit
git add ${affected_files}
git commit -m "$commit_msg"

# Save commit SHA for GitHub comment later
commit_sha=$(git rev-parse HEAD)

# Tag the fix
git tag "fix/${issue_id}-resolved" -f

# Comment on GitHub issue if present
if [[ -n "$github_issue" ]]; then
    gh issue comment "$github_issue" --body "**Fix Applied**: ${issue_title}

Fixed in commit ${commit_sha:0:7}

**Changes:**
- ${issue_description}
- ${solution_summary}

**Quality Checks:** ✅ All Passed
- Format: ✓
- Lint: ✓
- Type: ✓
- Test: ✓

Commit: \`${commit_sha:0:7}\`"

    echo "✅ Commented on GitHub issue #${github_issue}"
fi

Step 7: Verify Git State

# Confirm commit created
git log --oneline -1

# Verify clean working tree
git status --porcelain

# Show fix tag
git tag -l "fix/${issue_id}-*"

</fix_workflow>

Parallel Fix Strategy (for independent issues)

<parallel_execution>

If multiple issues are INDEPENDENT (affect different files with no overlap):

Analyze Dependencies:

Group issues by:
- File overlap (issues touching same files → sequential)
- Task overlap (issues in same task → sequential)
- No overlap (different files, different tasks → parallel)

Example:
- Issue #1: Security fix in auth.py (TASK-1.1)
- Issue #2: Test gap in payment.py (TASK-1.2)
- Issue #3: Docs missing in utils.py (TASK-1.3)
→ All independent → Run in parallel

Parallel Execution:

Launch multiple agents in parallel using single message with multiple Task calls:

Message with parallel Task invocations:
  Task 1: @agent-coder (issue=#1, files=[auth.py])
  Task 2: @agent-tester (issue=#2, files=[payment.py])
  Task 3: @agent-documentation (issue=#3, files=[utils.py])

# Each agent runs independently
# After all complete, run quality pipeline for each
# Commit each fix separately with proper messages

Benefits:

• 3+ independent issues fixed in ~time of 1 issue
• Each agent has minimal context (only its issue)
• Lower total token usage vs sequential

</parallel_execution>

4. Re-Run Story Review

<critical_requirement> After ALL fixes committed, re-run story-review to verify all issues resolved. </critical_requirement>

<re_review_workflow>

Step 1: Verify All Fixes Applied

# Check all fix tags exist
git tag -l 'fix/*-resolved' | wc -l

# Verify number matches issue count from report
# If mismatch: identify missing fixes, complete them

Step 2: Invoke Story Review

# Re-run story review using story ID
echo "🔄 Re-running story review..."
/lazy story-review ${story_id}

# story-review will:
# - Re-analyze all tasks in TASKS directory
# - Check acceptance criteria again
# - Verify quality metrics
# - Update GitHub issues if needed
# - Return APPROVED (creates PR) or new report

Step 3: Handle Re-Review Results

If APPROVED:
  → Proceed to PR creation (Step 5)

If CHANGES_NEEDED:
  → New report generated: USER-STORY-X.X_REPORT-ITERATION-2.md
  → Recursively invoke: /lazy story-fix-review ${new_report}
  → Continue until APPROVED

</re_review_workflow>

5. Create Pull Request (if approved)

<pr_creation>

Prerequisites:

• Story review: APPROVED ✓
• All fixes committed ✓
• Quality pipeline: PASS ✓
• Clean working tree ✓

PR Creation via gh CLI:

# Get story details
story_id=$(grep -E "^# (US-[0-9.]+|Issue #[0-9]+)" ${story_file} | ...)
story_title=$(grep "^## " ${story_file} | head -1 | sed 's/^## //')

# Get current branch
current_branch=$(git branch --show-current)

# Count commits (original tasks + fixes)
commit_count=$(git log ${base_branch}..HEAD --oneline | wc -l)
fix_count=$(git tag -l 'fix/*-resolved' | wc -l)

# Create PR body
cat > pr_body.md <<EOF
# ${story_title}

## Story: ${story_id}

### Overview
${story_description_from_file}

### Implementation Summary
- **Total Commits:** ${commit_count}
- **Task Commits:** $((commit_count - fix_count))
- **Fix Commits:** ${fix_count} (from story review)

### Tasks Completed
$(grep -E "^TASK-" TASKS.md | sed 's/^/- ✅ /')

### Issues Fixed
$(cat ${report_file} | grep -E "^### Issue #" | sed 's/^### /- ✅ /')

### Quality Metrics
- **Test Coverage:** $(pytest --cov --cov-report=term-missing | grep "^TOTAL" | awk '{print $4}')
- **Type Checking:** Passed ✅ (Mypy strict mode)
- **Linting:** Passed ✅ (Ruff)
- **Formatting:** Passed ✅ (Black)

### Story Review
- **Status:** APPROVED ✅
- **Review Iterations:** ${iteration_count}
- **All Acceptance Criteria:** Met ✅

### Commits
$(git log ${base_branch}..HEAD --oneline --reverse | sed 's/^/- /')

---

🤖 Generated with [Claude Code](https://claude.com/claude-code)

**Review Process:**
1. Initial implementation: ${commit_count - fix_count} task commits
2. Story review: ${fix_count} issues identified
3. Systematic fixes: ${fix_count} fix commits
4. Re-review: APPROVED ✅
EOF

# Create PR
gh pr create \
  --title "[${story_type}] ${story_title}" \
  --body "$(cat pr_body.md)" \
  --base ${base_branch} \
  --label "automated-pr,reviewed,story-fix-review"

# Capture PR URL
pr_url=$(gh pr view --json url -q .url)

# Clean up
rm pr_body.md

</pr_creation>

6. Final Summary Report

<summary_output>

## Story Fix Review Complete

**Story:** ${story_id} - ${story_title}
**Branch:** ${current_branch}
**Base:** ${base_branch}

### Story Directory Structure
📁 Story: ${story_id}-${story_slug}
   Directory: ${story_dir}
   Report: US-${story_id}_REPORT.md
   Tasks: ${task_count} tasks in TASKS/

### Issues Resolved
Total Issues: ${total_issues}
- 🔴 CRITICAL: ${critical_count} fixed
- 🟡 WARNING: ${warning_count} fixed
- 🔵 SUGGESTION: ${suggestion_count} fixed

### Fixes Applied

🔧 Fixes with GitHub Issue Links:
$(for fix in "${fixes_with_issues[@]}"; do
    echo "   - ${fix.severity}: ${fix.title} (${fix.task_id}) - Issue #${fix.github_issue}"
done)

$(if [[ ${#fixes_without_issues[@]} -gt 0 ]]; then
    echo "🔧 Fixes without GitHub Issues:"
    for fix in "${fixes_without_issues[@]}"; do
        echo "   - ${fix.severity}: ${fix.title} (${fix.task_id})"
    done
fi)

### Fix Commits
$(git log --grep="Fixes issue from story review" --oneline | sed 's/^/- /')

### Quality Pipeline Results
✅ Format: PASS (Black + Ruff)
✅ Lint: PASS (Ruff)
✅ Type: PASS (Mypy strict)
✅ Test: PASS (Coverage: ${coverage}%)

### Story Re-Review
📊 Status: APPROVED ✅
🔄 Iterations: ${iteration_count}
✅ All Acceptance Criteria: Met

### Pull Request
📦 PR Created: ${pr_url}

**PR Summary:**
- Title: [${story_type}] ${story_title}
- Commits: ${commit_count} (${task_commit_count} tasks + ${fix_count} fixes)
- Files Changed: ${files_changed}
- Lines Added: +${lines_added}
- Lines Removed: -${lines_removed}

### GitHub Issues Updated
$(for issue in "${github_issues[@]}"; do
    echo "🔗 #${issue.number}: ${issue.title}"
    echo "   Fixes applied: ${issue.fix_count}"
    echo "   Comments added: ${issue.comment_count}"
done)

### Git State
Branch: ${current_branch}
Commits ahead of ${base_branch}: ${commit_count}
Tags: ${tag_count} (tasks + fixes)
Status: Clean working tree ✅

### Next Steps
1. Review PR: ${pr_url}
2. Check GitHub issue comments
3. Address any PR comments
4. Merge after approval
5. Delete feature branch after merge

</summary_output>

Error Handling & Recovery

<error_recovery>

Error	Cause	Recovery
Story ID not found	Invalid story ID or not created yet	List available stories with ls -1 ./project-management/US-STORY/, retry with correct ID
Report file not found	story-review not run yet	Run /lazy story-review ${story_id} first, then retry
Story directory corrupted	Missing US-story.md or TASKS/	Check directory structure, may need to recreate story
Task file not found	Task file missing from TASKS/	Verify task exists in story, check TASKS/ directory
GitHub issue not found	Task file missing GitHub issue link	Task may have been created without GitHub issue, continue without issue reference
No issues in report	Report shows APPROVED	No fixes needed, skip to PR creation
Agent fix failed	Implementation error	Review agent output, provide more context, retry
Quality pipeline failed	Code issues remain	Review failure logs, fix manually or re-invoke agent with error context
Review not approved	Fix incomplete or incorrect	Check new report, identify remaining issues, retry fix workflow
Commit failed	Pre-commit hook failure	Fix hook issues, stage changes, retry commit
GitHub comment failed	gh CLI not authenticated or network issue	Run gh auth status, verify connection, retry
PR creation failed	gh CLI not authenticated	Run gh auth login, verify with gh auth status, retry
Dirty working tree	Uncommitted changes	Run git status, commit or stash changes, retry
Base branch missing	Branch doesn't exist	Create branch or use correct base, retry
Parallel fix conflict	File overlap detected	Switch to sequential execution for conflicting issues

</error_recovery>

Success Criteria

<success_indicators>

• ✅ All issues from report addressed (fix tags exist)
• ✅ Quality pipeline passes for all fixes
• ✅ Story re-review: APPROVED
• ✅ All commits follow conventional format
• ✅ Clean working tree (no uncommitted changes)
• ✅ PR created with comprehensive summary
• ✅ PR includes original tasks + fix commits
• ✅ All acceptance criteria met
• ✅ Test coverage maintained or improved
• ✅ Git tags track all fixes: git tag -l 'fix/*' </success_indicators>

Example Usage

<usage_examples>

# Fix issues using story ID (recommended - finds report automatically)
/lazy story-fix-review US-3.4

# With custom base branch
/lazy story-fix-review US-3.4 develop

# With full path to report (backward compatible)
/lazy fix ./project-management/US-STORY/US-3.4-oauth2-authentication/US-3.4-review-report.md

# Verify issues before running
cat ./project-management/US-STORY/US-3.4-oauth2-authentication/US-3.4-review-report.md

# List available stories
ls -1 ./project-management/US-STORY/

# Check current branch and status
git branch --show-current
git status

# After completion, verify fixes
git log --grep="Fixes issue" --oneline
git tag -l 'fix/*'

# View created PR
gh pr view

# Check GitHub issue comments
gh issue view 44
gh issue view 45

Example Output

📁 Resolving story ID: US-3.4

✅ Story resolved:
   ID: US-3.4
   Directory: ./project-management/US-STORY/US-3.4-oauth2-authentication
   Report: US-3.4-review-report.md

✅ Fixed 5 issues from report

📁 Story: US-3.4-oauth2-authentication
   Directory: ./project-management/US-STORY/US-3.4-oauth2-authentication/
   Report: US-3.4-review-report.md
   Tasks: 3 tasks in TASKS/

🔧 Fixes Applied:
   - CRITICAL: SQL injection vulnerability (TASK-1.2) - Issue #44
   - WARNING: Missing rate limiting (TASK-1.3) - Issue #45
   - WARNING: Incomplete edge case testing (TASK-1.3) - Issue #45

💾 Commits Created:
   - fix(TASK-1.2): use parameterized queries (a1b2c3d)
   - fix(TASK-1.3): add rate limiting middleware (e4f5g6h)
   - test(TASK-1.3): add edge case tests (i7j8k9l)

🔗 GitHub Issues Updated:
   - #44 commented: "Fixed SQL injection vulnerability"
   - #45 commented: "Added rate limiting and comprehensive tests"

🔄 Re-running story review...

✅ Story review: APPROVED

📦 PR Created: https://github.com/org/repo/pull/50
   Title: [Feature] OAuth2 Authentication System
   Commits: 8 (3 tasks + 5 fixes)
   Files Changed: 6

🔗 GitHub Issues Updated:
   - #44: 1 fix applied, 1 comment added
   - #45: 2 fixes applied, 2 comments added

</usage_examples>

Session Logging

<session_logging>

All activities logged to logs/<session-id>/story-fix-review.json:

{
  "story_id": "US-3.4",
  "story_directory": "./project-management/US-STORY/US-3.4-oauth2-authentication",
  "report_file": "US-3.4_REPORT.md",
  "base_branch": "main",
  "feature_branch": "feat/US-3.4-oauth2-authentication",
  "timestamp": "2025-10-26T10:00:00Z",
  "issues": {
    "total": 5,
    "critical": 2,
    "warning": 2,
    "suggestion": 1
  },
  "fixes": [
    {
      "issue_id": "1",
      "severity": "CRITICAL",
      "category": "Security",
      "title": "SQL injection risk in auth query",
      "task_id": "TASK-1.2",
      "github_issue": "44",
      "agent": "coder",
      "files_affected": ["src/auth/oauth2.py"],
      "stages": [
        {"stage": "agent_fix", "status": "completed", "duration": 45},
        {"stage": "quality_pipeline", "status": "passed", "duration": 28},
        {"stage": "review", "status": "approved", "duration": 12}
      ],
      "commit_sha": "abc123",
      "tag": "fix/issue-1-resolved",
      "github_comment_posted": true
    },
    {
      "issue_id": "2",
      "severity": "CRITICAL",
      "category": "Test Gap",
      "title": "Missing edge case for expired tokens",
      "task_id": "TASK-1.3",
      "github_issue": "45",
      "agent": "tester",
      "files_affected": ["tests/auth/test_oauth2.py"],
      "stages": [
        {"stage": "agent_fix", "status": "completed", "duration": 38},
        {"stage": "quality_pipeline", "status": "passed", "duration": 25},
        {"stage": "review", "status": "approved", "duration": 10}
      ],
      "commit_sha": "def456",
      "tag": "fix/issue-2-resolved",
      "github_comment_posted": true
    }
  ],
  "github_issues_updated": [
    {
      "issue_number": "44",
      "title": "Implement OAuth2 Token Validation",
      "fixes_applied": 1,
      "comments_added": 1
    },
    {
      "issue_number": "45",
      "title": "Add OAuth2 Security Tests",
      "fixes_applied": 2,
      "comments_added": 2
    }
  ],
  "re_review": {
    "iteration": 1,
    "status": "APPROVED",
    "timestamp": "2025-10-26T10:45:00Z"
  },
  "pr_creation": {
    "status": "completed",
    "url": "https://github.com/org/repo/pull/42",
    "commits": 9,
    "files_changed": 8,
    "lines_added": 247,
    "lines_removed": 38
  },
  "summary": {
    "total_duration": 2700,
    "fixes_applied": 5,
    "commits_created": 5,
    "quality_score": "100%",
    "coverage_change": "+3%",
    "github_issues_updated": 2
  }
}

</session_logging>

Notes

<implementation_notes>

Story Directory Structure Expected:

./project-management/US-STORY/
└── US-3.4-oauth2-authentication/
    ├── US-story.md                    # User story specification
    ├── US-3.4-review-report.md        # Review report (if issues found)
    └── TASKS/
        ├── TASK-1.1.md                # Task with GitHub issue link
        ├── TASK-1.2.md
        └── TASK-1.3.md

Report Structure Expected:

The US-X.Y-review-report.md in story directory should contain:

# Story Review Report: US-3.4

**Status**: ❌ FAILED
**Reviewed**: 2025-10-30 10:45
**Tasks**: 3/5 passed

## Summary
3 issues found preventing PR creation.

## Issues Found

### 1. Lint Error (src/auth.py:45)
- **Type**: lint_error
- **File**: src/auth.py:45
- **Issue**: unused import 'os'
- **Fix**: Remove import or use it

### 2. Test Failure (tests/test_auth.py)
- **Type**: test_failure
- **File**: tests/test_auth.py
- **Issue**: test_login_success failed
- **Fix**: Check mock credentials

## Tasks Status
- TASK-001: ✅ Passed
- TASK-002: ❌ Failed (2 lint errors)
- TASK-003: ⚠️ No tests
- TASK-004: ✅ Passed
- TASK-005: ❌ Failed (test failure)

## Next Steps
Run: `/lazy fix US-3.4-review-report.md`

Or manually fix and re-run: `/lazy review @US-3.4.md`

Task File Structure Expected:

Each TASK-X.Y.md in TASKS/ directory should contain:

# TASK-1.2: Implement OAuth2 Token Validation

**Status**: Completed
**GitHub Issue**: #44

## Description
[Task description]

## Acceptance Criteria
- [Criteria 1]
- [Criteria 2]

## Implementation Notes
[Notes]

Agent Selection Logic:

The command automatically selects the right agent based on issue category:

• Security → @agent-coder (security-focused)
• Code Issue/Bug → @agent-coder
• Test Gap → @agent-tester
• Architecture → @agent-refactor
• Documentation → @agent-documentation
• Performance → @agent-coder (performance-focused)

Quality Pipeline Integration:

Every fix MUST pass the complete quality pipeline before commit:

1. Format (Black + Ruff)
2. Lint (Ruff)
3. Type (Mypy)
4. Test (Pytest with coverage)

If any stage fails, the fix is rejected and agent is re-invoked with error context.

Commit Message Format:

All fix commits follow conventional commits format:

{type}({scope}): {issue_title}

Fixes issue from story review report:
- {issue_description}
- {solution_summary}

Issue: #{issue_number} ({severity})
Location: {file_locations}

Quality: format ✓ lint ✓ type ✓ test ✓
Review: APPROVED ✓

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>

Iterative Review Process:

The command supports multiple review iterations:

1. Fix all issues from initial report
2. Re-run story-review
3. If new issues found → new report generated
4. Recursively invoke story-fix-review with new report
5. Continue until APPROVED

</implementation_notes>