gh-issue

name	gh-issue
description	Fetch a GitHub issue, create a branch, implement with TDD, and open a PR

GitHub Issue Workflow

Context

Read both the issue body and every comment as requirements input. Maintainer follow-ups frequently add scope, edge cases, or override the original description; when a later comment conflicts with the body, prefer the comment.

!gh issue view ${ARGUMENTS#\#} --json number,url,title,body,labels,assignees,state,comments 2>/dev/null || echo "Provide an issue number"

Instructions

Phase 1: Setup

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

2. Assign yourself if unassigned:

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

3. Create a branch from fresh origin/main based on the issue type:

   Determine the branch prefix from labels:

   • bug → fix/
   • enhancement → feat/
   • documentation → docs/
   • No label → feat/ (default)

   Branch name format: <prefix><issue-number>-<slug>

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

Phase 2: Plan

4. Enter Plan Mode to design the implementation:

   • Explore the codebase to understand affected areas.
   • Identify files that need changes.
   • Respect adapter independence: .claude/rules/no-cross-adapter-imports.md.
   • Honor the adapter skeleton: .claude/rules/adapter-pattern.md.
   • Plan the TDD approach (what tests to write first).

5. Create implementation plan with:

   • Summary of what the issue requires.
   • List of files to create/modify.
   • Test strategy (unit per package, integration under tests/integration).
   • Step-by-step implementation order.

Phase 3: Implement

6. After plan approval, implement following TDD:

   • Write failing tests first (*_test.go next to the code under test).
   • Implement minimum code to pass.
   • Refactor while keeping tests green.
   • Wrap returned errors per .claude/rules/error-wrapping.md.
   • Follow .claude/rules/test-conventions.md (use t.TempDir(), testutil.Chdir, behavior-named tests).

7. Run full test suite:

   go test ./...
   

   Fix ALL failures before proceeding.

8. Regenerate derived artifacts when touched:

   • Edited internal/config/config.go struct tags → go run ./cmd/schemagen (see .claude/skills/regen-schema/).
   • Edited specs under .agnostic-ai/ or any adapter → agnostic-ai sync then ./agnostic-ai sync --check (see .claude/skills/run-sync-check/).
   • Touched code reachable from cmd/agnostic-ai-wasm → rebuild the playground (see .claude/skills/playground-rebuild/).

Phase 4: Ship

9. Update CHANGELOG.md — add an entry under ## [Unreleased], grouped as Added, Changed, Fixed, or Removed per .claude/rules/docs-sync.md. Skip only for pure refactors or test-only changes.

10. Update user docs when behavior is visible:

    • New or changed flag, target, or output field → docs/user/targets.md and docs/user/configuration.md.
    • New or changed spec field → docs/user/spec-format.md.
    • New command or capability → README.md.

11. Commit changes using Conventional Commits (.claude/rules/conventional-commits.md):

    git add <specific-files>
    git commit -m "<type>(<scope>): <description>
    
    Related to #<issue-number>"
    

    Use ref: (not refactor:) for refactor commits. Subject under 72 chars. Body explains why, not what. Never mention AI assistance.

12. Final refactor commit (mandatory, last commit before PR): Re-review every file touched by this change. Look for:

    • duplication introduced by the new code (extract or reuse).
    • dead branches, unused params, leftover debug.
    • naming drift vs. surrounding package conventions.
    • violations of .claude/rules/adapter-pattern.md, no-cross-adapter-imports.md, error-wrapping.md, go-style.md, plain-english.md.
    • over-engineering: speculative abstractions, premature interfaces, helpers used once.

    Apply fixes. Re-run go test ./.... Commit as a separate ref(...) commit — must be the final commit on the branch before PR:

    git commit -m "ref(<scope>): polish <area> after #<issue-number>
    
    Related to #<issue-number>"
    

    If review surfaces zero changes, record that fact in the PR body instead of skipping silently.

13. Push and create PR:

    git push -u origin <branch-name>
    gh pr create \
      --assignee Chemaclass \
      --label "<bug|enhancement|documentation>" \
      --title "<type>(<scope>): <description>" \
      --body "$(cat <<'EOF'
    ## Summary
    <1-3 bullets>
    
    ## Test plan
    - [ ] go test ./...
    - [ ] agnostic-ai sync --check (if specs/adapters touched)
    
    Closes #<issue-number>
    EOF
    )"
    

    Match the label to the issue type. Use Closes #<num> so merge auto-closes the issue.

Phase 5: Verify & Merge

14. Wait for CI green on the PR:

    gh pr checks <pr-number-or-branch> --watch
    

    Fix red checks on the branch (push fixes; re-watch). Do not proceed while any required check is failing. Never --no-verify past a failing required check.

15. Merge with admin bypass when possible: Once every required check is green:

    gh pr merge <pr-number> --squash --admin --delete-branch
    

    If --admin is rejected (token lacks admin, branch protection blocks bypass), fall back to --auto --squash --delete-branch and surface that the PR is awaiting human approval.

16. Sync local main after merge:

    git checkout main && git fetch origin main && git reset --hard origin/main
    

Checklist

• Issue fetched and understood (body + comments)
• Self-assigned
• Branch created from fresh origin/main
• Plan created and approved
• Tests written first (TDD)
• Implementation complete
• go test ./... passes
• Derived artifacts regenerated (schema / sync / playground) when applicable
• Changelog updated under ## [Unreleased]
• User docs updated when behavior is visible
• Feature commit with Related to #<num>
• Final ref(...) commit (last commit on branch)
• PR created with Chemaclass assignee, matching label, Closes #<num>
• CI green (gh pr checks --watch)
• PR merged via --admin --squash (or --auto fallback if admin blocked)
• Local main synced to origin/main