Github Issue Solver

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:

• Title and full body
• Labels (bug, feature, security, docs, performance, DX, auth, database, workflow, battle, CLI, mobile, web)
• 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

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
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
.lenserfight/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
• Performance → vite-performance-engineer
• UI/UX → tailwind-ui-ux-reviewer
• Tests → unit-test-planner

Step 4 — Classify the Issue

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 (do not enforce only in frontend).
5. Identify affected tests and whether they catch the bug.

State root cause explicitly before designing a solution.

Step 6 — Design Solution (GRASP + OOAD)

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 with the required data
• Creator: the object that aggregates 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.

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/.
• 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

# Discover commands
pnpm nx show project <project> --json | jq '.targets | keys'
grep -rE 'nx (test|run|affected)' .github/workflows/

# 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 for the fixed behavior, add them. Do not ship without test coverage.

Step 10 — Commit

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

Root cause: <one sentence>

Closes #<issue-number>
EOF
)"

• Conventional Commits format
• 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>
pnpm nx typecheck <project>
\`\`\`

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

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

## Screenshots
<!-- If UI changed -->

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

Step 12 — Monitor CI

gh pr checks <pr-number> --watch

Fix CI failures before merging. Never 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

Step 14 — Post-Merge Synchronization

git checkout development
git pull origin development
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)."

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
• 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

Failure Handling

Final Report Format

## 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"