---
name: github-issue-solver
description: Read GitHub issues, triage them, solve them using GRASP/OOAD principles, run or add tests, commit, push, open a PR linked to the issue, merge into development, and close the issue only after merge. Use when the user says /github-issue-solver, "solve issue #N", "fix GitHub issue", or "work on issue".
---

# 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

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

Capture:
- Title and full body
- Labels (bug, feature, security, docs, performance, DX, auth, database, workflow, battle, CLI, mobile, web)
- All comments
- Linked PRs or branches

### Step 2 — Check for Duplicates

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

If a duplicate exists: comment linking the canonical issue, 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
package.json / pnpm-workspace.yaml — test and build commands
CLAUDE.md / CONTRIBUTING.md        — coding standards and rules
.cursor/skills/         — available 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`
- Tests → `unit-test-planner`

### Step 4 — Classify the Issue

| Type | Detection criteria |
|------|-------------------|
| `bug` | Unexpected behavior, crash, incorrect output |
| `feature` | New capability or enhancement request |
| `security` | Auth bypass, data leak, RLS gap, injection |
| `performance` | Slow query, bundle size, N+1, memory leak |
| `docs` | Missing or incorrect documentation |
| `DX` | Dev tooling, CI, build, test setup |
| `database` | Schema change, migration, RLS, index |
| `workflow` | Battle workflow, automation, trigger |
| `CLI` | CLI command, output, TUI |
| `mobile` | Mobile app screen, navigation, native |
| `web` | Web app route, UI, API integration |

### Step 5 — Identify Root Cause

Before writing any code:

1. Trace data flow from symptom back to origin.
2. Identify which module owns the broken invariant.
3. Check domain, data, feature, UI, or infra layer.
4. Confirm whether backend validation is missing.
5. Identify affected tests.

State root cause explicitly before designing.

### Step 6 — Design Solution (GRASP + OOAD)

Apply [references/grasp-ooad-checklist.md](./references/grasp-ooad-checklist.md).

Rules:
- Single source of truth: one place owns each business rule
- Low coupling, high cohesion
- Information Expert: assign responsibility to the module with the required data
- Backend validation: business rules enforced server-side, never frontend-only
- No duplicated domain logic
- No unrelated refactors bundled with the fix
- No hardcoded temporary fixes
- No security bypasses

### Step 7 — Create a Branch

```bash
git checkout development
git pull origin development
git checkout -b fix/issue-<number>-<short-slug>
```

### Step 8 — Implement Minimal Correct Fix

- Edit only files required to resolve the root cause.
- No opportunistic refactors.
- If schema changes are needed, create a new migration in `supabase/migrations/`.

### Step 9 — Add or Update Tests

Load [references/test-discovery-checklist.md](./references/test-discovery-checklist.md).

```bash
# Smallest scope first
pnpm nx test <project> --testPathPattern=<spec>
pnpm nx typecheck <project>
pnpm nx lint <project>

# If schema/RLS changed
pnpm supabase test db

# Broader check for critical areas
pnpm nx affected --target=test --base=origin/development
```

If no adequate tests exist, add them.

### Step 10 — Commit

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

Root cause: <one sentence>

Closes #<issue-number>
EOF
)"
```

### Step 11 — Push and Open PR

```bash
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

## Tests
- [ ] Existing tests pass
- [ ] New tests added
- [ ] Typecheck passes

## Commands Run
\`\`\`bash
pnpm nx test <project>
pnpm nx typecheck <project>
\`\`\`

## Migration Notes
<!-- If schema changed -->

## Security Notes
<!-- If auth/RLS changed -->

## Remaining Risks
<!-- Anything not fully addressed -->
EOF
)"
```

Load [references/pr-template.md](./references/pr-template.md) for full template.

### Step 12 — Monitor CI

```bash
gh pr checks <pr-number> --watch
```

Fix CI failures before merging.

### Step 13 — Merge into Development

Only after all CI checks pass:

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

### Step 14 — Post-Merge Synchronization

```bash
git checkout development
git pull origin development
pnpm install --frozen-lockfile
pnpm nx typecheck <project>
pnpm nx test <project>
```

### Step 15 — Close the Issue

Only after merge confirmed and post-merge validation passes:

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

---

## Issue Closing Rules

| Condition | Action |
|-----------|--------|
| PR merged, fully resolves issue | Close with merge commit reference |
| PR merged, partial fix | Leave open, comment what remains |
| Duplicate | Link canonical issue, close as duplicate |
| Not reproducible | Comment evidence, close as invalid |
| CI fails | Do not merge, do not close |
| Post-merge test fails | Open follow-up, leave original open |

---

## Engineering Constraints

- Single source of truth — one module owns each business rule
- GRASP principles enforced
- Backend validation for all business rules — never frontend-only
- No duplicated domain logic
- 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

---

## Failure Handling

| Failure | Response |
|---------|----------|
| Issue not found | Ask user to confirm issue number |
| Cannot reproduce | State what was tried, ask for steps |
| Root cause unclear | Document exploration, ask for clarification |
| Tests fail after fix | Diagnose, do not suppress |
| Migration unsafe | Invoke `migration-risk-reviewer`, halt |
| RLS regression | Invoke `supabase-rls-security-reviewer`, halt |
| CI fails | Fix before merging |

---

## Final Report Format

```
## GitHub Issue Solver — Final Report

### Issue
#<number>: <title>

### Root Cause
<one paragraph>

### Solution
<one paragraph>

### PR
URL: <pr-url>

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

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

### Issue Status
Closed / Open (reason)

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

---

## Example Triggers

- `/github-issue-solver 42`
- "Fix GitHub issue #86"
- "Work on issue #139"
- "Solve the bug in issue #84"
