---
description: Fix issues from story review report
argument-hint: "[STORY-ID or REPORT-FILE] [base-branch]"
allowed-tools: Read, Write, Edit, Bash, Task, Glob, Grep
model: claude-haiku-4-5-20251001
---

# 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:

```bash
# 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**
```markdown
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**
```bash
# 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:

```markdown
# 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)

```bash
# 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**

```markdown
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)

```bash
# 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**

```bash
# 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:**
```markdown
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:**
```markdown
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**
```bash
# 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**
```bash
# 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**

```markdown
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:**

```bash
# 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>

```markdown
## 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>

```bash
# 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`:

```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:

```markdown
# 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:

```markdown
# 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>