GitHub Issue Solver

Solve GitHub issues end-to-end: triage → explore → design → implement → test → PR → merge → close.

Never guess architecture. Never close an issue before the PR is merged.

Activation Criteria

Invoke this skill when:

• User says /github-issue-solver or /solve-issue
• User says "solve issue #N", "fix GitHub issue #N", "work on issue #N"
• User pastes a GitHub issue URL
• User asks to process open issues from the repository

Workflow

Step 1 — Fetch Issue Metadata

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

Capture and record:

• Title and full body
• Labels (bug, feature, security, docs, performance, DX, auth, database, workflow, battle, CLI, mobile, web)
• Milestone and due date
• All comments (may contain constraints or partial solutions)
• Linked PRs or branches

If no issue number is provided, ask the user which issue(s) to target.

Step 2 — Check for Duplicates and Related Work

gh issue list --state all --search "<key terms from title>"
gh pr list --state all --search "<key terms>"

If a duplicate exists: comment on the issue linking the canonical one, then stop.

Step 3 — Repository Exploration

Do not assume architecture. Explore:

apps/*                  — entry points and composition roots
libs/domain/*           — business concepts, invariants, core types
libs/api/*              — contracts and DTOs
libs/data/*             — repositories, Supabase integration
libs/features/*         — feature slices and orchestration
libs/infra/*            — analytics, moderation, storage adapters
libs/ui/*               — UI components, forms, layout, tokens
libs/utils/*            — low-level shared utilities
supabase/               — schema, migrations, RLS policies, SQL functions
.github/workflows/      — CI/CD pipelines and test commands
apps/cli/               — CLI if issue is CLI-related
apps/mobile/            — mobile app if issue is mobile-related
package.json / pnpm-workspace.yaml — test and build commands
CLAUDE.md / CONTRIBUTING.md        — coding standards and rules
.claude/skills/         — available AI agent skills

Load relevant skills before implementing:

• Feature placement → feature-slice-designer
• Architecture concern → repo-architecture-auditor
• Schema change → supabase-schema-reviewer
• RLS/security → supabase-rls-security-reviewer
• Migration → migration-risk-reviewer
• Contract/DTO → contract-dto-consistency-reviewer
• Code quality → deep-code-reviewer or grasp-ooad-review
• Performance → vite-performance-engineer
• UI/UX → tailwind-ui-ux-reviewer
• Tests → unit-test-planner

Step 4 — Classify the Issue

Determine issue type:

A single issue may span multiple types; note all that apply.

Step 5 — Identify Root Cause

Before writing any code:

1. Trace data flow from the issue symptom back to its origin.
2. Identify which module owns the broken invariant.
3. Check whether the bug is in domain, data, feature, UI, or infra layer.
4. Confirm whether backend validation is missing (do not enforce only in frontend).
5. Identify affected tests and whether they currently catch the bug.

State the root cause explicitly before designing a solution.

Step 6 — Design Solution (GRASP + OOAD)

Apply references/grasp-ooad-checklist.md.

Rules:

• Single source of truth: one place owns each business rule
• Low coupling: changes should not ripple unexpectedly
• High cohesion: related behavior stays together
• Information Expert: assign responsibility to the class/module with the required data
• Creator: the object that aggregates or uses another creates it
• Controller: one entry point handles a use case
• Backend validation: business rules enforced server-side, never frontend-only
• No duplicated domain logic across layers
• No unrelated refactors bundled with the fix
• No hardcoded temporary fixes
• No security bypasses

Design the solution in 1–3 sentences before touching any file.

Step 7 — Create a Branch

git checkout development
git pull origin development
git checkout -b fix/issue-<number>-<short-slug>
# or feat/issue-<number>-<short-slug> for features

Never work on main or development directly. See docs/en/how-to/contributors/branching.md for naming rules and conventional commit format.

Step 8 — Implement Minimal Correct Fix

• Edit only files required to resolve the root cause.
• No opportunistic refactors.
• No doc additions unless the behavior change requires them.
• If schema changes are needed, create a new migration file in supabase/migrations/.
• If RLS changes are needed, invoke supabase-rls-security-reviewer first.
• Keep changes auditable: one logical concern per commit.

Step 9 — Add or Update Tests

Load references/test-discovery-checklist.md.

1. Find existing test commands:

# From workspace config
cat package.json | grep -E '"test|"spec'
pnpm nx show project <affected-project> --json | jq '.targets | keys'
# From CI
cat .github/workflows/*.yml | grep -E 'run:|nx run'

2. Run the smallest relevant test set first:

pnpm nx test <affected-project> --testPathPattern=<related-spec>
pnpm nx typecheck <affected-project>
pnpm nx lint <affected-project>

3. If no adequate tests exist for the fixed behavior, add them. Do not ship without test coverage for the root cause.
4. If the fix touches database logic, run migration/RLS tests:

pnpm nx test supabase --testPathPattern=<related>
# or pgTAP via supabase test db

5. If the fix crosses feature boundaries, run integration tests.
6. Run broader checks if the affected area is critical (auth, billing, RLS, battle engine):

pnpm nx affected --target=test --base=origin/development
pnpm nx affected --target=typecheck --base=origin/development

If tests cannot be run, explain why and what manual verification was done.

Step 10 — Commit

Use the smart-commit skill for staged changes, or:

git add <specific-files>
git commit -m "$(cat <<'EOF'
fix(scope): concise imperative description

Root cause: <one sentence>

Closes #<issue-number>

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

Rules:

• Conventional Commits format
• Include Closes #N only when the PR fully resolves the issue
• Never use --no-verify
• Never commit .env, secrets, or credentials

Step 11 — Push and Open PR

git push -u origin <branch-name>
gh pr create \
  --base development \
  --title "<type>(scope): short description (fixes #N)" \
  --body "$(cat <<'EOF'
## Issue

Closes #<number>

## Root Cause

<one paragraph>

## Solution

<one paragraph>

## Files Changed

- `path/to/file.ts` — what changed and why

## Tests

- [ ] Existing tests pass
- [ ] New tests added for: <what>
- [ ] Typecheck passes
- [ ] Lint passes

## Commands Run

\`\`\`bash
pnpm nx test <project> --testPathPattern=<spec>
pnpm nx typecheck <project>
\`\`\`

## Migration Notes

<!-- If schema changed -->

## Security Notes

<!-- If auth/RLS/data/provider logic changed -->

## Screenshots

<!-- If UI changed -->

## Remaining Risks

<!-- Anything not fully addressed -->
EOF
)"

Load references/pr-template.md for a full PR body template.

Step 12 — Monitor CI

gh pr checks <pr-number> --watch

If CI fails:

1. Read the failure output.
2. Fix the root cause locally.
3. Push the fix.
4. Re-run failing checks.

Do NOT merge while CI is failing.

Step 13 — Merge into Development

Only after:

• All CI checks pass
• No unresolved conflicts
• No unsafe migrations
• No security regressions
• Implementation is complete

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

Use --squash only if the team's merge strategy is squash. Use --rebase only if the team uses rebase. Default to --merge unless CLAUDE.md or CONTRIBUTING.md specifies otherwise.

Step 14 — Post-Merge Synchronization

git checkout development
git pull origin development

Verify:

pnpm install --frozen-lockfile
pnpm nx typecheck <affected-project>
pnpm nx test <affected-project>

If post-merge validation fails, open a follow-up issue immediately and do not close the original.

Step 15 — Close the Issue

Only after merge is confirmed and post-merge validation passes:

gh issue close <number> --comment "Fixed in PR #<pr-number> (merged into development)."

If the PR used Closes #N syntax and GitHub auto-closed the issue on merge, verify the issue is closed and add a comment with the merge commit hash for traceability.

Issue Closing Rules

Never close an issue speculatively or before the PR merges.

Engineering Constraints

• Single source of truth — one module owns each business rule
• GRASP principles enforced — see references/grasp-ooad-checklist.md
• Backend validation for all business rules — never frontend-only
• No duplicated domain logic across layers
• No unrelated refactors bundled in the fix
• No hardcoded temporary fixes
• No security bypasses
• No force-push to protected branches
• No --no-verify on commits
• No detached HEAD states
• No stale branch work

Failure Handling

Final Report Format

After completing the workflow, output:

## GitHub Issue Solver — Final Report

### Issue
#<number>: <title>
URL: <url>

### Root Cause
<one paragraph>

### Solution
<one paragraph>

### PR
URL: <pr-url>
Branch: <branch-name>

### Merge
Commit: <hash>
Branch: development
Status: merged / failed

### Post-Merge Validation
- Install: pass / fail
- Typecheck: pass / fail
- Tests: pass / fail
- Migrations: valid / invalid

### Issue Status
Closed / Open (reason)

### Remaining Risks
<bullet list or "none">

Example Triggers

• /github-issue-solver 42
• /solve-issue 118
• "Fix GitHub issue #86"
• "Work on issue #139"
• "Solve the bug reported in issue #84"