| name | resolve-issue |
| description | Resolve a GitHub issue end-to-end — analyze the issue, create a feature branch, implement the fix (TDD when the issue is marked), run verification gates, open a PR, and drive the cr-fix review loop to convergence. Use ONLY when the user explicitly types /github-dev:resolve-issue <number> or asks to resolve or implement a specific issue. Do NOT auto-fire from incidental issue mentions — this creates a branch, commits, and opens a GitHub PR. Flags pass through to cr-fix — --skip-review, --strict, --skip-cr-fix, --cr-fix-max, --auto-merge, --codex-grace, --no-codex, --skip-minor, --no-minor-stop, --no-generalize, --cr-source. |
| allowed-tools | Read Write Edit Bash Glob Grep AskUserQuestion Task |
Resolve GitHub Issue
Hermes Agent Compatibility
When this skill is loaded through Hermes as github-dev:<skill>, map Claude/Codex tool names to Hermes tools:
| Claude/Codex term | Hermes tool |
|---|
| Bash | terminal |
| Read | read_file |
| Write | write_file |
| Edit | patch |
| Glob/Grep | search_files |
| AskUserQuestion | clarify |
| Task | delegate_task |
| Monitor | process |
Treat $ARGUMENTS as the natural-language arguments supplied when the user asks Hermes to load the skill. Plugin-provided skills are explicit opt-in loads in Hermes; use skill_view("github-dev:<skill>") (or ask Hermes to load that qualified skill) rather than relying on bare text like github-dev:<skill> ....
Act as an expert developer who systematically analyzes and resolves GitHub issues. Receive a GitHub issue number as argument and resolve the issue. Follow project guidelines in @CLAUDE.md.
Prerequisites
Before starting the workflow:
- Serena MCP: If not already active, run
activate_project to enable semantic code analysis tools
- Clean state: Ensure no uncommitted changes that could conflict with the new branch
Flags
| Flag | Description |
|---|
--skip-review | Skip 2-stage review (for trusted changes) |
--strict | Treat lint failures as blocking errors |
--skip-cr-fix | Skip the auto cr-fix loop after PR creation (default: cr-fix runs) |
--cr-fix-max <n> | Cap iterations on the auto cr-fix loop (default: 5) |
--auto-merge | Pass through to cr-fix; auto-merge the PR after convergence (default: OFF) |
--codex-grace <sec> | Pass through to cr-fix; extra wait window after CodeRabbit completes for ChatGPT-Codex review comments (default: 90) |
--no-codex | Pass through to cr-fix; force-disable Codex auto-detect for the run (default: auto-detect ON) |
--skip-minor | Pass through to cr-fix; silently skip CR Minor/Trivial/Info severity (excluding Bug/Security) + Codex P2 to shrink the gated queue on lint-heavy PRs |
--no-minor-stop | Pass through to cr-fix; disable the minor soft-stop (default ON — cr-fix stops from iter 2 when a cycle applied only low-severity fixes with nothing deferred, final_state=minor_floor) |
--no-generalize | Pass through to cr-fix; disable bounded same-file generalization (default ON — a real + high-confidence + grep-able finding also patches sibling occurrences of the same pattern in the same file) |
--cr-source <mode> | Pass through to cr-fix; review source selector. auto (default) falls back to local coderabbit CLI or Codex-only on PR-bot rate-limit. pr-bot / cli / codex-only lock the source. |
Note: For parallel development, create worktrees manually before starting Claude sessions. See CLAUDE.md for the recommended worktree workflow.
Workflow
-
Analyze Issue:
- Run
gh issue view $ISSUE_NUMBER --json title,body,comments,milestone to get issue title, body, labels, and milestone
- Check TDD marker: Look for
<!-- TDD: enabled --> in issue body -> Set TDD workflow flag
- If milestone exists, run
gh issue list --milestone "<milestone-name>" --json number,title,state to view related issues and understand overall context
- Identify requirements precisely
- [NEW] Save checkpoint: phase="analyze"
-
Verify Plan File Alignment (If Exists):
- Check if issue body or milestone description contains a plan file path
- Common patterns:
Plan: /path/to/plan.md, See: .claude/plans/xxx.md
- If plan file exists:
- Read the plan file content
- Compare plan objectives with issue requirements
- Verify scope alignment (plan covers issue, no scope creep)
- If misaligned, ask user for clarification before proceeding
- If no plan file, continue to next step
- [NEW] Save checkpoint: phase="plan"
2.5. Worktree context check:
bash if [ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ]; then echo "[info] In linked worktree — Step 3 will replace this worktree's branch with feat/<n>-<slug>. This is expected for the PR flow." fi
No abort. The PR flow inside a worktree is supported.
-
Create Branch: Create and checkout a new branch from the default branch.
- Detect default branch:
git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'
- Branch naming convention:
{type}/{issue-number}-{short-description}
type: Infer from issue labels (bug -> fix, enhancement/feature -> feat) or title prefix. Default to feat if unclear.short-description: Slugify issue title (lowercase, spaces to hyphens, max 50 chars, remove special chars)- Examples:
fix/42-login-validation-error, feat/15-add-dark-mode, refactor/8-cleanup-auth
- [NEW] Save checkpoint: phase="branch"
-
Update GitHub Project Status (Optional)
- Run
gh project list --owner <owner> --format json to check for projects
- If no projects exist, skip silently
- If projects exist:
-
Analyze Codebase (MANDATORY): Before writing any code, understand the affected areas:
Tool Selection by Scope:
| Scope | Approach |
|---|
| Narrow (1-2 files, specific function) | Serena: get_symbols_overview -> find_symbol -> find_referencing_symbols |
| Broad (multiple modules, architecture) | Explorer agents in parallel (preserves main context) |
For broad changes, spawn 2-3 Explorer agents simultaneously using Task Tool:
# Structure analysis
Task(
subagent_type="Explore",
prompt="Analyze architecture related to [feature]. Map file relationships and module boundaries."
)
# Pattern analysis
Task(
subagent_type="Explore",
prompt="Find similar implementations of [feature type] in the codebase."
)
# Dependency analysis
Task(
subagent_type="Explore",
prompt="Identify all modules that depend on [target]. List potential breaking changes."
)
-
Plan Resolution: Based on analysis results, develop a concrete resolution plan and define work steps.
-
Resolve Issue: Implement the solution using appropriate tools:
- Symbolic edits (Serena):
replace_symbol_body, insert_after_symbol for precise modifications
- File edits: For non-code files or complex multi-line changes
- Sub-agents: For large-scale parallel modifications
- If TDD enabled (marker detected in Step 1):
- Prefer the shared TDD skill: If
superpowers:test-driven-development is installed, invoke it and follow its discipline. It is the source of truth for TDD rigor (RED -> GREEN -> REFACTOR with tracer-bullet vertical slices, never refactor while RED, test behavior over implementation, mock only at boundaries).
- Fallback (skill not installed):
superpowers is an external plugin and MUST NOT be a hard dependency — Codex and minimal installs may lack it, and this skill must not break there. When it is absent, degrade gracefully to these four built-in rules:
- Tracer-bullet vertical slice — one failing test -> one minimal implementation -> repeat. Do not write a batch of tests up front (no horizontal slicing).
- Strict RED -> GREEN — watch the test fail first, then write the minimum to pass. Never refactor while a test is RED.
- Behavior over implementation — assert through the public interface only; do not couple tests to internal structure.
- Mock at the boundary — stub only external collaborators (network / DB / clock / filesystem); never mock internal collaborators.
- If TDD not enabled: Implement features directly according to the plan
- Execution verification required: For Python scripts, executables, or any runnable code, always execute to verify correct behavior. Do not rely solely on file existence or previous results.
# For complex implementation
Task(
subagent_type="claude",
model="opus",
prompt="Implement [complex feature]. Ensure type safety and error handling."
)
# For standard implementation
Task(
subagent_type="claude",
model="sonnet",
prompt="Implement [feature] in [file]. Follow existing patterns."
)
- [NEW] Save checkpoint: phase="implement"
-
Write Tests:
- If TDD enabled: Verify test coverage meets target (tests already written in Step 7), add missing edge cases if needed
- If TDD not enabled: Spawn independent sub-agents per file to write unit tests in parallel, achieving at least 80% coverage
# Parallel test writing
Task(
subagent_type="claude",
model="sonnet",
prompt="Write unit tests for [file]. Target 80% coverage. Test happy path, edge cases, error conditions."
)
- [NEW] Save checkpoint: phase="test"
-
Validate: Run tests, lint checks, and build verification in parallel using independent sub-agents to validate code quality.
# Parallel validation
Task(
subagent_type="claude",
model="haiku",
prompt="Run test suite and report pass/fail count."
)
Task(
subagent_type="claude",
model="haiku",
prompt="Run linter and report issues."
)
9.4. [NEW] E2E suite (opt-in, auto-detected):
- Detect E2E presence: look for playwright.config.* (.ts/.js/.mjs/.cts) or an e2e/ test directory.
- If detected: run the E2E suite (e.g. npx playwright test) and report pass/fail counts.
- Failures are warn-only — they do NOT block PR creation. E2E is slow and environment-dependent; surface the failures (and the trace/report path if produced) for the user to triage, then continue the workflow.
- If not detected: silent skip. resolve-issue does not require the e2e-harness plugin, a playwright.config, or any E2E setup to exist — it works whether or not E2E is configured (loose coupling).
9.5. [NEW] Verification Gates:
- Run BUILD, TEST, LINT checks (see "Verification Gates" section)
- Block on BUILD or TEST failure
- Warn on LINT failure (block if --strict)
9.6. [NEW] 2-Stage Review (unless --skip-review):
- Stage 1: Spec compliance review
- Stage 2: Code quality review
- Maximum 3 retries, then escalate to user
- Save checkpoint: phase="review"
- Create PR: Create a pull request for the resolved issue.
- Commit only issue-relevant files: Never use
git add -A. Stage only files directly related to the issue.
- [NEW] Save checkpoint: phase="pr"
10.5. [NEW] Auto cr-fix loop (default ON):
- Unless --skip-cr-fix is passed, invoke the /github-dev:cr-fix skill (plugins/github-dev/skills/cr-fix/SKILL.md) and let it run its 16-step lifecycle in this same Claude turn. Pass through the resolve-issue flags: --cr-fix-max <n> becomes cr-fix's --max-iterations; --auto-merge, --codex-grace <sec>, --no-codex, --skip-minor, --no-minor-stop, --no-generalize, --cr-source <auto|pr-bot|cli|codex-only> are forwarded as-is. CodeRabbit auto-review takes ~7-30 min per cycle; ChatGPT-Codex (when present) typically posts within 5 min after CR; cr-fix's wait phase uses Bash(run_in_background) + Monitor so token cost during waits is ~0. Codex auto-detect is enabled by default — repos without Codex installed see no behavior change. PR-bot rate-limit detection (~30s) auto-flips to local coderabbit CLI or Codex-only when --cr-source=auto.
> **Ambiguous user phrase handling**:
>
> User phrases like "auto merge로", "auto merge 전까지", "끝까지", "머지까지 가줘" are ambiguous — they can mean "enroll in auto-merge queue" or "drive until merge actually completes" or "drive the loop but stop before any merge". Default interpretation: drive cr-fix to natural convergence (`final_state="clean"` AND CR engagement gate satisfied). Do NOT enroll auto-merge unless the user passes the explicit `--auto-merge` flag. If the user used such a phrase but did not pass `--auto-merge`, surface a single `AskUserQuestion` ("did you mean enroll auto-merge?" — Yes / No) before any merge action. The sankun PR #68 incident (immediate merge with CR review left dangling) was caused by interpreting an ambiguous phrase as implicit `--auto-merge`.
- Print one banner line at start: `CR auto-fix loop starting; pass --skip-cr-fix to disable.`
- On non-success exit:
- `final_state` ∈ {failure, iteration_cap, user_declined, minor_floor, cr_inactive}: cr-fix emits a final JSON line via its EXIT trap (Step 16). Surface that JSON's diagnostic to the user.
- `final_state="timeout"`: cr-fix's trap still emits the JSON line (with `final_state="timeout"` and `merged=false`), but the user-facing message should additionally mention exit code 124 if the underlying poller hit the wall-clock cap. Surface "cr-fix timed out — re-run with a larger `--cr-fix-max` or `--timeout`, or check the CodeRabbit dashboard."
- `final_state="cr_inactive"`: CodeRabbit never engaged with the PR within the iteration budget. Surface "CodeRabbit did not review the PR; merge not attempted. Check the CodeRabbit dashboard or re-run with a larger `--cr-fix-max`."
- `final_state="minor_floor"`: cr-fix stopped at the low-severity floor (default on; `--no-minor-stop` disables) — the last cycle applied only minor fixes with nothing deferred. Those fixes were pushed but the latest push has not been CR-re-reviewed. Surface "cr-fix stopped at minor_floor — low-severity fixes pushed, latest push not yet re-reviewed; re-run cr-fix to confirm clean or merge via GitHub UI." Pass `--no-minor-stop` to keep looping.
- In all non-success cases, resolve-issue still considers itself complete (PR is open and reviewable). Do NOT auto-merge in any non-clean exit.
- On `final_state="clean"` and `--auto-merge` flag set: cr-fix's Step 15 branches on branch-protection presence. With protection, `gh pr merge --auto --squash --delete-branch` queues the merge until protection requirements are met. Without protection, cr-fix prompts the user (Merge now / Skip merge / Cancel) — `--auto` would otherwise collapse to immediate merge and bypass any external review.
- Save checkpoint: phase="cr-fix"
11. Update Issue Checkboxes: Mark completed checkbox items in the issue as done.
11.5. Update Project Tracking State (if milestone exists):
- Check if issue has a milestone:
bash MILESTONE=$(gh issue view $ISSUE_NUMBER --json milestone --jq '.milestone.title // empty')
- If milestone exists:
1. Generate slug from milestone name (lowercase, spaces to hyphens, remove special chars)
2. Check for state file: .claude/state/project-tracking-{slug}.json
3. If state file exists:
- Load the state file
- Update issue state to "in_progress" (PR created during resolve)
- Record PR number in the issue entry (preserve existing dependsOn and architectureNode):
json { "state": "open", "pr": <PR_NUMBER>, "moduleId": "<existing>", "dependsOn": [<existing>], "architectureNode": "<existing>" }
- Recalculate module progress:
module.progress = (closed_issues / total_issues) * 100 module.status: "complete" -> all issues closed "in_progress" -> at least 1 closed or has PR, at least 1 still open "pending" -> all open, no PR
- Save updated state file
4. If no state file: skip silently (tracking not set up for this milestone)
- Note: GitHub diagram sync is NOT performed here. Diagrams are updated in post-merge after the PR is merged.
- [NEW] Cleanup:
- Archive state file to
.claude/state/archive/
Follow ~/.claude/CLAUDE.md and project CLAUDE.md.
Verification and Completion Criteria
Important: Always verify actual behavior before marking checkboxes as complete.
Verification Principles
- Execution required: Directly run code/configuration to confirm it actually works
- Provide evidence: Show actual output or results that prove completion
- No guessing: Explicitly mark unverified items as "unverified" or "assumed"
- Distinguish partial completion: Clearly separate code written but not tested
Prohibited Actions
- Reporting "expected to work" without execution
- Stating "will appear in logs" without checking logs
- Presenting assumptions as facts
State Management
Session state enables workflow recovery after interruption.
State File Location
Sessions are saved to: .claude/state/github-dev-{issue-number}.json
State Schema
{
"sessionId": "github-dev-{issue-number}-{timestamp}",
"command": "resolve-issue",
"issueNumber": 123,
"phase": "analyze|branch|implement|test|review|commit|pr",
"branchName": "feat/123-add-dark-mode",
"branchType": "feat|fix|refactor|docs|chore",
"startedAt": "ISO timestamp",
"lastCheckpoint": "ISO timestamp",
"checkpoints": [
{ "phase": "analyze", "status": "complete", "timestamp": "ISO" },
{ "phase": "implement", "status": "in_progress", "timestamp": "ISO" }
]
}
Checkpoint Save (after each phase)
mkdir -p .claude/state
cat > .claude/state/github-dev-${ISSUE_NUMBER}.json << 'EOF'
{... state JSON ...}
EOF
Cleanup (on successful completion)
mkdir -p .claude/state/archive
mv .claude/state/github-dev-${ISSUE_NUMBER}.json \
.claude/state/archive/github-dev-${ISSUE_NUMBER}-$(date +%Y%m%d).json
Verification Gates
Quality gates that must pass before commit.
Check Types
| Check | Purpose | Required |
|---|
| BUILD | Compilation success | Yes |
| TEST | All tests pass | Yes |
| LINT | No linting errors | No (warning only) |
| TYPE_CHECK | Type errors resolved | No (warning only) |
Project Type Detection
| Detection File | Project Type | Commands |
|---|
package.json | Node.js | npm run build, npm test, npm run lint |
pyproject.toml or setup.py | Python | pytest, ruff check . |
Cargo.toml | Rust | cargo build, cargo test, cargo clippy |
go.mod | Go | go build ./..., go test ./... |
Running Verification
Task(
subagent_type="claude",
model="haiku",
prompt="Run verification checks for this project:
1. Detect project type from config files
2. Run BUILD command - must pass
3. Run TEST command - must pass
4. Run LINT command - report warnings
5. Return JSON: {build: pass/fail, test: pass/fail, lint: pass/fail/skipped, errors: []}"
)
Gate Enforcement
- BUILD failure: Block commit, report errors
- TEST failure: Block commit, report failures
- LINT failure: Warn but allow commit (unless
--strict)
2-Stage Review Protocol
Overview
Before PR creation, implementation passes two review stages:
- Spec Compliance - Does it meet requirements?
- Code Quality - Is it well implemented?
Stage 1: Spec Compliance Review
Task(
subagent_type="claude",
model="sonnet",
prompt="Spec compliance review for issue #${ISSUE_NUMBER}
## Issue Requirements
${ISSUE_BODY}
## Changed Files
${GIT_DIFF_STAT}
## Review Checklist
1. Does implementation meet all issue requirements?
2. Are all checkbox items in the issue addressed?
3. Any missing functionality?
## Output: {verdict: PASS|FAIL, gaps: [], recommendation: string}"
)
Stage 2: Code Quality Review
Task(
subagent_type="claude",
model="opus",
prompt="Code quality review for issue #${ISSUE_NUMBER}
## Changed Files
${GIT_DIFF}
## Review Checklist
1. Does code follow project conventions?
2. Is error handling comprehensive?
3. Are tests sufficient?
4. Any security concerns?
## Output: {verdict: PASS|FAIL, issues: [], recommendation: string}"
)
Review Loop
- Maximum 3 retries per stage
- On failure, fix based on specific feedback
- After 3 failures, escalate to user
Skip Review Flag
--skip-review: Use for trusted changes (e.g., docs only)
