gh-issue

GitHub Issue Workflow

Fetch a GitHub issue, create branch, implement following TDD, and open a PR.

Arguments

• $ARGUMENTS - Issue number (e.g., 42 or #42)

Instructions

Phase 1: Setup

1. Parse the issue number from $ARGUMENTS (strip # if present)

2. Fetch issue details:

   gh issue view <number> --json title,body,labels,assignees,milestone,state
   

3. Assign yourself if unassigned:

   gh issue edit <number> --add-assignee @me
   

4. Add appropriate labels if the issue doesn't have them:

   • bug - Something isn't working
   • enhancement - New feature or request
   • documentation - Improvements or additions to documentation

5. Create a branch from main:

   Determine prefix from labels:

   • bug → fix/
   • enhancement → feat/
   • documentation → docs/
   • Default → feat/

   Branch name: <prefix><issue-number>-<slug> (slug: lowercase title, spaces → -, max 50 chars)

   git checkout main && git pull
   git checkout -b <branch-name>
   

Phase 2: Plan

1. Analyze the issue: requirements, labels, referenced issues, affected areas

2. Explore the codebase for context:

   • Find related code in src/
   • Find related tests in tests/
   • Study existing patterns

3. Create implementation plan:

   • Acceptance Criteria
   • Test Strategy (which tests to write first)
   • Files to Change
   • Implementation Order (smallest first step)

4. Use EnterPlanMode if implementation is non-trivial

Phase 3: Implement

1. Follow strict TDD workflow (see @.claude/rules/tdd-workflow.md):

   For each test:

   • RED - Write failing test, verify it fails for the RIGHT reason
   • GREEN - Minimal code to pass
   • REFACTOR - Improve while keeping tests green

2. Run full test suite frequently:

   ./bashunit tests/
   ./bashunit --parallel tests/
   

3. Quality checks after each refactor:

   make sa && make lint