gh-andre-mygentic-andre-engineering-system/commands/implement-issue.md

---
description: Complete 3-phase automation: implement → review → merge for GitHub issues
argument-hint: [issue number]
---

# Implement GitHub Issue - Automated Workflow

You are orchestrating the complete implementation → review → merge pipeline for issue **$ARGUMENTS**.

## Your Mission

Execute this workflow **autonomously** without stopping between phases unless errors occur:

1. **Phase 1: Implementation** - Launch issue-implementer agent
2. **Phase 2: Review** - Launch review-orchestrator agent (3 parallel checks)
3. **Phase 3: Merge** - Launch issue-merger agent

Do **NOT** stop between phases to ask the user. Only stop if:
- An agent returns an error
- Review decision is "REQUEST_CHANGES" (report feedback to user)
- Merge fails due to conflicts (report to user)

---

## Execution Instructions

### Phase 1: Implementation

Launch the issue-implementer agent with issue number **$ARGUMENTS**:

```
Use the Task tool with:
- subagent_type: issue-implementer
- description: "Implement issue $ARGUMENTS"
- prompt: "Implement issue $ARGUMENTS following the 8-step workflow."
```

**If API returns 500 "Overloaded" error**:
- Automatically retry up to 2 more times (3 attempts total)
- Wait 5 seconds between retries
- Log: "API overloaded, retrying in 5 seconds... (attempt X/3)"
- Only fail if all 3 attempts return 500 errors

**After agent completes, verify actual implementation**:
```bash
# Check manifest exists
if [ -f ".agent-state/issue-$ARGUMENTS-implementation.yaml" ]; then
  STATUS=$(grep "status:" .agent-state/issue-$ARGUMENTS-implementation.yaml | cut -d: -f2 | tr -d ' ')

  # Verify implementation artifacts
  BRANCH=$(grep "branch:" .agent-state/issue-$ARGUMENTS-implementation.yaml | cut -d: -f2 | tr -d ' "')

  # Check branch exists
  if ! git rev-parse --verify "$BRANCH" >/dev/null 2>&1; then
    echo "⚠️ Warning: Branch $BRANCH not found, but status is $STATUS"
    echo "This may indicate implementation succeeded despite error messages"
  fi

  # For AWS operations, verify resources exist (if applicable)
  # This will be handled in implementation verification section below
else
  echo "❌ ERROR: Implementation manifest not found"
  echo "Agent may have failed before completion"
  exit 1
fi
```

**Verify Implementation Success**:
Check actual state, not just manifest:
- Branch exists: `git rev-parse --verify feature/issue-$ARGUMENTS`
- Commits pushed: `git log origin/feature/issue-$ARGUMENTS`
- Issue labeled: `gh issue view $ARGUMENTS --json labels | grep ready_for_review`

**Using the verification helper script**:
```bash
# Verify branch exists
~/.claude/scripts/verify-github-operation.sh branch-exists $ARGUMENTS feature/issue-$ARGUMENTS

# Verify label updated
~/.claude/scripts/verify-github-operation.sh label-updated $ARGUMENTS ready_for_review
```

The verification script provides color-coded output and clear success/failure indicators.

If status is "ready_for_review" and verification passes, print:
```
✅ Phase 1 Complete: Implementation
📋 Files changed: [list from manifest]
📊 Status: ready_for_review
⏭️  Continuing to review phase...
```

Then proceed to Phase 2 immediately.

---

### Phase 2: Review

Launch the review-orchestrator agent:

```
Use the Task tool with:
- subagent_type: review-orchestrator
- description: "Review issue $ARGUMENTS"
- prompt: "Orchestrate code review for issue $ARGUMENTS. Coordinate security, quality, and documentation checks in parallel. Create PR if approved."
```

**Wait for completion**, then check:
```bash
cat .agent-state/issue-$ARGUMENTS-review.yaml | grep "decision:"
```

**If decision is "APPROVE"**, verify and report:

**Verify Review Completion**:
```bash
# Verify PR was created
~/.claude/scripts/verify-github-operation.sh pr-created $ARGUMENTS

# Verify label updated to ready_for_merge
~/.claude/scripts/verify-github-operation.sh label-updated $ARGUMENTS ready_for_merge
```

If verification passes, print:
```
✅ Phase 2 Complete: Review
🔒 Security: PASS (0 issues)
⚡ Quality: PASS
📚 Documentation: PASS
🎯 Decision: APPROVE
📝 PR created and label updated
⏭️  Continuing to merge phase...
```

Then proceed to Phase 3 immediately.

**If decision is "REQUEST_CHANGES"**, print:
```
❌ Phase 2: Changes Requested
📝 Feedback: [show blocking issues from manifest]
🔄 Issue returned to "To Do" status

Workflow stopped. Address the feedback and re-run /implement-issue $ARGUMENTS
```

Stop here and report to user.

---

### Phase 3: Merge

Launch the issue-merger agent:

```
Use the Task tool with:
- subagent_type: issue-merger
- description: "Merge PR for issue $ARGUMENTS"
- prompt: "Merge the approved pull request for issue $ARGUMENTS. Handle conflict resolution if needed, update all tracking systems, and cleanup worktrees."
```

**Wait for completion**, then verify and report:

**Verify Merge Completion**:
```bash
# Verify PR was merged
~/.claude/scripts/verify-github-operation.sh pr-merged $ARGUMENTS

# Verify issue was closed
~/.claude/scripts/verify-github-operation.sh issue-closed $ARGUMENTS
```

If verification passes, print:
```
✅ Phase 3 Complete: Merge
🔗 PR merged and verified
📦 Commit: [SHA from merger output]
🏁 Issue #$ARGUMENTS closed and verified
✨ Workflow complete
```

---

## Error Handling

**Error Recovery Protocol**:

1. **Check actual state before failing**:
   - Implementation phase: Verify branch exists, files changed, commits pushed
   - Review phase: Verify PR created (if approved), issue labeled correctly
   - Merge phase: Verify PR merged, issue closed, branch deleted

2. **For API 500 "Overloaded" errors specifically**:
   - These are temporary overload, not failures
   - Automatically retry up to 2 more times (3 attempts total)
   - Wait 5 seconds between retries
   - Only fail if all 3 attempts return errors

3. **For "operation failed" but state shows success**:
   - Log warning but continue workflow
   - Example: "Connection closed" error but AWS resource actually exists
   - Report to user: "Operation completed successfully despite error message"

4. **For actual failures**:
   - Stop workflow immediately
   - Show clear error with phase name and details
   - Provide specific recovery steps
   - Preserve work (don't delete worktree/branch)

**Common errors:**
- "Issue not found" → Check issue number format (should be just number, not URL)
- "No implementation manifest" → Run implementer first
- "Review not approved" → Address review feedback and re-run workflow
- "Merge conflicts" → Resolve manually, then re-run merge phase
- "API Overloaded" → Automatic retry (up to 3 attempts)
- "Label not updated" → Manually update via: `gh issue edit NUMBER --add-label LABEL`

---

## Status Reporting

After each phase completion, use this format:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase [N]: [Phase Name]
✅ Status: [Complete/Failed]
📊 Details: [Key information]
⏭️  Next: [What happens next]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

---

## Final Report

After Phase 3 completes successfully, provide:

```
🎉 Issue #$ARGUMENTS Implementation Complete

📊 Summary:
   • Implementation: [files changed]
   • Review: [decision + check results]
   • Merge: [PR number + commit SHA]

🔗 Links:
   • Issue: https://github.com/Mygentic-AI/mygentic-personal-assistant/issues/$ARGUMENTS
   • PR: [PR URL from merger output]
   • Commit: [commit URL]

✅ All tracking systems updated
✅ Worktree cleaned up
✅ Branches deleted
```

---

**Start now with issue $ARGUMENTS. Do not ask for confirmation between phases.**