GitHub Issue Workflow

Implement a GitHub issue following TDD principles with integrated code review and QA validation.

Arguments

$ARGUMENTS - GitHub issue URL (e.g., https://github.com/owner/repo/issues/123) or issue number (e.g., 123)

Workflow Overview

┌─────────────────────────────────────────────────────────────────┐
│  1. Setup       → Checkout main, create feature branch          │
│  2. Research    → Fetch issue details, research best practices  │
│  3. Plan        → Create implementation plan, get user approval │
│  4. TDD Cycle   → Write failing test → Implement → Pass         │
│  5. Code Review → Run go-code-reviewer, incorporate feedback    │
│  6. QA Validate → Run qa-requirements-validator, fix gaps       │
│  7. PR Creation → Commit, push, create pull request             │
└─────────────────────────────────────────────────────────────────┘

Process

Phase 1: Environment Setup

Validate working directory is clean:
```
git status --porcelain
```
If there are uncommitted changes, warn the user and ask how to proceed.

Checkout and update main branch:

git checkout main && git pull origin main

Parse issue identifier from $ARGUMENTS:
- If URL: Extract owner, repo, and issue number
- If number only: Use current repo context

Fetch issue details:

gh issue view $ISSUE_NUMBER --json title,body,labels,assignees

Create feature branch:

# Branch naming: fix/issue-{number}-{short-description} or feat/issue-{number}-{short-description}
git checkout -b {branch-name}

Phase 2: Research & Understanding

Parse issue requirements:
- Extract acceptance criteria from issue body
- Identify affected components/files
- Note any linked issues or PRs
Research best practices:
- Use WebSearch to find relevant patterns for the problem domain
- Check existing codebase patterns using Glob and Grep
- Review similar implementations in the project

Explore affected code:

Use the Explore agent to understand the codebase area:

Task(
  prompt="Explore how {affected_area} works in this codebase. Find relevant files, understand the architecture, and identify where changes need to be made for: {issue_summary}",
  subagent_type="Explore"
)

Document findings:
- Create a mental model of what needs to change
- Identify potential risks or edge cases

Phase 3: Implementation Plan

Create structured plan:

Present to user for approval:

## Implementation Plan for Issue #{number}: {title}

### Requirements (from issue)
- [ ] Requirement 1
- [ ] Requirement 2
...

### Approach
{High-level description of the solution}

### Files to Modify/Create
| File | Action | Purpose |
|------|--------|---------|
| path/to/file.go | Modify | Add X functionality |
| path/to/file_test.go | Create | Test cases for X |

### Test Strategy (TDD)
1. Test case 1: {description}
2. Test case 2: {description}
...

### Risks & Mitigations
- Risk: {potential issue}
  Mitigation: {how to handle}

Get user approval:
- Present the plan
- Ask: "Does this plan look good? Should I proceed with implementation?"
- Wait for explicit approval before continuing

Phase 4: TDD Implementation Cycle

For each feature/requirement, follow RED-GREEN-REFACTOR:

4.1 RED: Write Failing Test First

Create/update test file:
- Write test that captures the expected behavior
- Include edge cases identified in planning
Run test to confirm it fails:
```
go test ./... -run TestNamePattern -v
```
Verify failure is for the right reason:
- Test should fail because functionality doesn't exist yet
- NOT because of syntax errors or wrong test setup

4.2 GREEN: Implement Minimum Code to Pass

Write implementation:
- Only enough code to make the test pass
- Follow existing code patterns in the project
- Refer to CLAUDE.md for project conventions
Run tests:
```
go test ./... -v
```
Iterate until all tests pass

4.3 REFACTOR: Improve Code Quality

Clean up implementation:
- Remove duplication
- Improve naming
- Simplify logic where possible
Ensure tests still pass:
```
go test ./... -v
```

Phase 5: Code Review

Run go-code-reviewer agent:

Task(
  prompt="Review the code changes I made for GitHub issue #{number}. Focus on:
  - KISS (Keep It Simple, Stupid) violations
  - DRY (Don't Repeat Yourself) violations
  - Go best practices and idioms
  - Error handling
  - Test coverage quality

  The changes are in these files: {list of modified files}

  Provide specific, actionable feedback.",
  subagent_type="go-code-reviewer"
)

Address feedback:
- For each issue identified:
  - If Critical/Important: Fix immediately
  - If Suggestion: Evaluate and fix if reasonable
- Run tests after each fix
Re-run reviewer if significant changes made:
- Ensure new issues weren't introduced

Phase 6: QA Validation

Run qa-requirements-validator agent:

Task(
  prompt="Validate my implementation against the requirements from GitHub issue #{number}.

  Requirements from issue:
  {parsed requirements from Phase 2}

  Implementation files:
  {list of modified files}

  Verify each requirement is:
  - Fully implemented
  - Properly tested
  - Handles edge cases

  Provide a detailed validation report.",
  subagent_type="qa-requirements-validator"
)

Address gaps:
- For any requirement NOT FULFILLED or PARTIALLY FULFILLED:
  - Go back to Phase 4 (TDD cycle) for that requirement
  - Write test for missing case
  - Implement fix
  - Re-run QA validation
Continue until all requirements are FULFILLED

Phase 7: Commit & Create PR

Final test run:
```
go test ./... -v
```
Stage changes:
```
git add {specific files}
```

Create commit:

git commit -m "$(cat <<'EOF'
fix: {short description} (#{issue_number})

{Longer description of what was done}

- {Change 1}
- {Change 2}

Closes #{issue_number}

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"

Push branch:
```
git push -u origin {branch-name}
```

Create pull request:

gh pr create --title "{title}" --body "$(cat <<'EOF'
## Summary

Fixes #{issue_number}

{Brief description of changes}

## Changes Made

- {Change 1}
- {Change 2}

## Test Plan

- [ ] All existing tests pass
- [ ] New tests added for {feature}
- [ ] Manually verified {scenario}

## Checklist

- [x] Code follows project style guidelines
- [x] Tests written and passing
- [x] Code reviewed by go-code-reviewer
- [x] Requirements validated by qa-requirements-validator

---
Generated with Claude Code
EOF
)"

Report PR URL to user

Error Handling

Git Conflicts

If merge conflicts occur:

Report to user with affected files
Ask for guidance on resolution
Do NOT auto-resolve conflicts

Test Failures

If tests fail unexpectedly:

Analyze failure reason
If test bug: Fix test
If implementation bug: Fix implementation
If unclear: Ask user for guidance

API/CLI Errors

If gh commands fail:

Check if user is authenticated: gh auth status
Report specific error to user
Provide remediation steps

Quality Gates

Before proceeding to each phase, verify:

[ ] Phase 1 → 2: Branch created, issue details fetched
[ ] Phase 2 → 3: Requirements understood, codebase explored
[ ] Phase 3 → 4: User approved the plan
[ ] Phase 4 → 5: All tests pass, implementation complete
[ ] Phase 5 → 6: Code review feedback addressed
[ ] Phase 6 → 7: All requirements validated as FULFILLED
[ ] Phase 7 complete: PR created and URL provided

Output

After completion, provide summary:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GITHUB ISSUE COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Issue: #{number} - {title}
Branch: {branch-name}
PR: {pr-url}

Changes:
- {file1}: {description}
- {file2}: {description}

Tests Added: {count}
Code Review: Passed
QA Validation: All requirements fulfilled

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━