github-issue

name	github-issue
description	Work on a GitHub issue end-to-end: checkout main, create branch, research best practices, plan implementation, write tests first (TDD), implement, run code review, QA validation, then create PR. Use when given a GitHub issue URL or number to implement.
disable-model-invocation	true
argument-hint	<issue-url-or-number>
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","Task","WebFetch","WebSearch"]

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

1. Validate working directory is clean:

   git status --porcelain
   

   If there are uncommitted changes, warn the user and ask how to proceed.

2. Checkout and update main branch:

   git checkout main && git pull origin main
   

3. Parse issue identifier from $ARGUMENTS:

   • If URL: Extract owner, repo, and issue number
   • If number only: Use current repo context

4. Fetch issue details:

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

5. 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

1. Parse issue requirements:

   • Extract acceptance criteria from issue body
   • Identify affected components/files
   • Note any linked issues or PRs

2. 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

3. 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"
   )
   

4. Document findings:

   • Create a mental model of what needs to change
   • Identify potential risks or edge cases

Phase 3: Implementation Plan

1. 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}
   

2. 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

1. Create/update test file:

   • Write test that captures the expected behavior
   • Include edge cases identified in planning

2. Run test to confirm it fails:

   go test ./... -run TestNamePattern -v
   

3. 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

1. Write implementation:

   • Only enough code to make the test pass
   • Follow existing code patterns in the project
   • Refer to CLAUDE.md for project conventions

2. Run tests:

   go test ./... -v
   

3. Iterate until all tests pass

4.3 REFACTOR: Improve Code Quality

1. Clean up implementation:

   • Remove duplication
   • Improve naming
   • Simplify logic where possible

2. Ensure tests still pass:

   go test ./... -v
   

Phase 5: Code Review

1. 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"
   )
   

2. Address feedback:

   • For each issue identified:
     • If Critical/Important: Fix immediately
     • If Suggestion: Evaluate and fix if reasonable
   • Run tests after each fix

3. Re-run reviewer if significant changes made:

   • Ensure new issues weren't introduced

Phase 6: QA Validation

1. 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"
   )
   

2. 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

3. Continue until all requirements are FULFILLED

Phase 7: Commit & Create PR

1. Final test run:

   go test ./... -v
   

2. Stage changes:

   git add {specific files}
   

3. 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 <[e-mail]>
   EOF
   )"
   

4. Push branch:

   git push -u origin {branch-name}
   

5. 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
   )"
   

6. Report PR URL to user

Error Handling

Git Conflicts

If merge conflicts occur:

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

Test Failures

If tests fail unexpectedly:

1. Analyze failure reason
2. If test bug: Fix test
3. If implementation bug: Fix implementation
4. If unclear: Ask user for guidance

API/CLI Errors

If gh commands fail:

1. Check if user is authenticated: gh auth status
2. Report specific error to user
3. 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

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