1007 lines
27 KiB
Markdown
1007 lines
27 KiB
Markdown
---
|
|
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>
|