resolve-issue
Skill0 starsChanged 6 days agoMITView on GitHub
Takes ONE issue (bug report, feature request, tracker issue #N, a pasted screenshot of a defect) to a VERIFIED BRANCH through a ranked diagnosis, spec, plan, parallel build with an adversarial verifier per task, gates and docs, then stops for a human yes before anything is merged or pushed. Use when the user says "fix issue #N", "resolve #N", "work this issue", "take this bug", "build this feature end to end", "diagnose only #N", or pastes a bug report to be fixed, even when the fix looks like one line, because one-line fixes are the ones that ship the wrong cause.
10 other projects use a version of this.
Adopted by
Most recently taken up by
- Gens-ai/skillstheir own version, first seen Nov 8, 2026
- maiquelleonel/matryoshka-harnesstheir own version, first seen Nov 8, 2026
- neko3cs/skillstheir own version, first seen Nov 6, 2026
- NVIDIA/sphinx-llmtheir own version, first seen Oct 23, 2026
- vivliostyle/vivliostyle.jstheir own version, first seen Oct 8, 2026
- gittower/git-flow-nexttheir own version, first seen Oct 8, 2026
Other versions10 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 10
- vivliostyle/vivliostyle.js★ 800same name
- gittower/git-flow-next★ 458same name
- NVIDIA/sphinx-llm★ 49same name
- pekral/cursor-rules★ 10same name
- getsentry/outpost★ 5same name
- garthcodes/claude-skills★ 2same name
- Gens-ai/skills★ 1same name
- youhei-ushio/dotclaude-public★ 1same name
- maiquelleonel/matryoshka-harness★ 0same name
- neko3cs/skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
Show its rules and text
We split this skill into the rules it gives an agent
15 rules. 0 are common, 12 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 7 edited versions we read keep these.
12
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 32
Rank, never confirm: Before committing to a cause or a plan, list at least two alternatives, your favourite included, and force a relative …
- Distinctive: line 35
Prove the test can fail: Every fix carries a regression test that fails on the old code and passes on the new [VF-3].
- Distinctive: line 37
Never weaken a test or guard to go green: Stop and report instead [TG-7].
- Distinctive: line 41
No sensitive identifiers anywhere: Keep names, record numbers, birth dates and customer PII out of issues, commits, docs and fixtures.
- Distinctive: line 42
Only do the task you were given: Put adjacent cleanup into follow-up issues [BD-2, SP-5].
- Distinctive: line 47
Add the project's own laws from its profile (for example, "migrations are additive only" [DI-25] or "no raw colours outside the design …
- Distinctive: line 53
If the repo is nested inside another repo, run git remote -v first and never apply the parent's settings [PF-2].
- Distinctive: line 57
Do this inline, before launching anything.
- Distinctive: line 65
A destructive or data-loss-sensitive request: never goes straight to a build.
- Very specific: line 88
Agent/Task subagents only: follow templates/subagent-fallback.md.
- Very specific: line 93
Before launch, create the isolated worktree and branch and assign spare ports (references/isolation.md).
- Distinctive: line 115
Use these skills when they are installed.
- Distinctive: line 127
Run git status and git ls-files -d in the worktree.
- Very specific: line 128
Run git log <base>..HEAD and check that every commit carries the required trailers.
- Distinctive: line 150
When the human says "push it" in this turn, push without asking "are you sure?" [HG-3].
“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
resolve-issue
Take one issue from report to a verified branch, then stop.
This skill is the distilled process from months of agent-driven work on one production app: about 70 ad-hoc workflows and around 600 raw lessons, merged into about 400 in references/lessons.md. Every instruction here exists because skipping it once cost a build cycle, a bad release or a user's trust. The ids in square brackets ([DG-1]) point to the lesson and its origin story. Lessons that hold only for one kind of product live in opt-in domain packs (references/packs/).
Scope: issue → verified branch. Merging to the main line, pushing, tagging and releasing are outside this skill. Each needs its own human yes [HG-1, HG-2].
The loop
pre-flight ─▶ size + announce ─▶ DIAGNOSE ─▶ SPEC ─▶ PLAN ─▶ BUILD ║ VERIFY ⟲ REPAIR ─▶ VIEW ─▶ GATES ─▶ DOCS ─▶ HARVEST ─▶ STOP
(questions rank, root real parallel waves, fresh UI: fixed only if side-issue summary
that change probe, cause, code, adversarial verifier shots list; spec drafts for from data
the build) measure scope units per task, repair 1 before, commits says so the main
tier up (max 3) after verified loopEvery stage is a separate agent. Its output passes into the next stage's prompt unparaphrased: compact fields, or a pointer into a committed file (each task reads its plan section at the plan's commit) [OR-1, CO-9]. The run happens in the background so the conversation stays free [OR-2]. Agents inside the run never stop to ask questions. They rank the real alternatives, let evidence decide, and record what they decided. Questions for the human belong in pre-flight and at the final yes [OR-16]. Some questions do need an answer: a data-loss menu [SP-11], a shared component's changed flow nobody can vouch for [SP-17], a change to privacy or security behaviour [SP-18], a behaviour choice a repair cannot settle [VF-5]. Each first goes to a decide step [SP-20]: one agent lists 2 to 4 options with its recommendation, runs the profile ranker and classifies criticality (vault crypto, irreversible deletion no ADR mandates, money, legal or consent, a locked ADR, production access, a security weakening, plus decisions.critical). Code makes it AUTO only when it is not critical, the recommendation is the ranker's top and the margin is at least decisions.margin (0.2). AUTO goes into decisions and the run continues, at most 3 times per run. Anything else stops as decision_required with the options, the recommendation, the ranking and why it was not auto; relaunch with the human's answer in decisions. decisions.auto: false means always ask.
VIEW runs only when the spec sets user_visible. It screenshots before and after on test data, judges them against docs.design and the ux pack, and builds nothing; a defect this branch caused gets one repair, then a human decides [VF-23]. HARVEST turns every stage's side findings into issue drafts for Step 4 [OR-27].
The laws
These are non-negotiable. Inject them into every agent prompt as numbered laws, and give the verifier the same list to check mechanically. Soft guidance gets ignored under pressure, and numbered laws that a verifier enforces get respected [SP-14, OR-7].
- Rank, never confirm. Before committing to a cause or a plan, list at least two alternatives, your favourite included, and force a relative ranking. Never ask "am I right?" [DG-1, DG-2].
- Evidence beats ranking. A ranking informs and never decides. Read the code, probe, and measure. When the two disagree, evidence wins and the overrule gets recorded [DG-3, DG-8].
- Fix the reported symptom, at the shared seam. Fix the root cause at the one place every caller routes through, then look for sibling bugs of the same class [DG-15, DG-25, SP-4].
- Prove the test can fail. Every fix carries a regression test that fails on the old code and passes on the new [VF-3].
- Read the whole log. Grep the full test output for
failed. Compare the failing SET, not the count or the tail [TG-2, TG-8]. - Never weaken a test or guard to go green. Stop and report instead [TG-7].
- Stage explicit paths only. No
git add -A. After any background run, checkgit statusandgit ls-files -d[GR-1, VF-15]. - Stay isolated. Each run gets its own worktree, branch and ports, links the real secrets, and kills every server it started [IS-1, IS-2, IS-3].
- No push, tag, release, settings or secrets changes by agents. Destructive git stays blocked. Doubt means hold [HG-1, HG-5, HG-10].
- No sensitive identifiers anywhere. Keep names, record numbers, birth dates and customer PII out of issues, commits, docs and fixtures. Agents get no production access [PS-1, PS-5].
- Only do the task you were given. Put adjacent cleanup into follow-up issues [BD-2, SP-5].
- Never claim fixed, deployed or green from indirect evidence [CM-3, VF-10].
Law 9 binds agents. Filing side issues to the project's own tracker (Step 4) is a main-loop action, done after the audit and listed in the summary, never by an agent inside a run [OR-27].
Add the project's own laws from its profile (for example, "migrations are additive only" [DI-25] or "no raw colours outside the design tokens" [VF-25]).
Step 0: load or create the project profile
Look for .claude/resolve-issue.yml in the repo. If it is missing, run first-run discovery as described in references/project-profile.md. It finds the real install, typecheck, lint, test, e2e, build and docs commands, the tracker, the label mapping, the docs locations and the commit conventions, and writes the profile for the human to review. Never guess a command. A guessed command looks exactly like a broken build.
If the repo is nested inside another repo, run git remote -v first and never apply the parent's settings [PF-2].
Step 1: pre-flight
Do this inline, before launching anything. It is cheap, and it prevents the most expensive mistakes.
- Make sure a tracker issue exists, even for a hot-fix, and cite only issue numbers that really exist [PF-1].
- Capture the human's report verbatim, plus screenshots, as files that every stage can read. Paraphrase loses the detail that separates the real symptom from a neighbouring one [PF-11]. Scrub identifiers first [PS-1, PS-2]. If the issue has an
## Agent Briefcomment, save it next to the report: its acceptance criteria and out-of-scope list go into the spec. - Read the prior decisions. That means ADRs, decision notes, memory, and earlier attempts on the same surface. Flag any conflict with a locked decision, and treat notes as possibly stale until the code confirms them [PF-4, PF-5, PF-6, DG-11].
- 3b. Check it is not already built or already rejected. Search the code and docs for the issue's glossary concept, not only its words, and read
.out-of-scope/if the repo has one. A hit stops the run: tell the human what exists or was rejected, and recommend closing, re-scoping or reopening the decision [PF-5].
- 3b. Check it is not already built or already rejected. Search the code and docs for the issue's glossary concept, not only its words, and read
- Check feasibility of any new dependency, data source or token before you spec on top of it, on every platform the product targets [PF-7, PF-8, PF-9, PF-10, PF-12].
- Ask only the questions that change what gets built. Ask them one at a time, each with your recommended answer. For everything else, start, and write your assumptions into the spec [PF-3]. The question that matters most is usually the one that separates the reported symptom from a neighbouring one: which screen, which flow, which data [DG-15]. A fact only the reporter has moves the issue to
needs-infowith the question for them. It never becomes an assumption. - A destructive or data-loss-sensitive request never goes straight to a build. It gets a decision menu first [SP-11]. So does a shared component's changed default whose effect on some caller's flow nobody knows [SP-17].
- Check shared state against runs already going. With
env.shared_db: true, warn before a second run that touches DB functions, and run them one after the other. Each run overrides the runner'senv.fixed_pathswith its own log directory [IS-17, IS-18]. Logs and screenshots go under<scratch>/<issue>/logs, outside the worktree; if a log directory sits inside one,git check-ignoremust cover it before launch [IS-19].
Step 2: size it, budget it, announce it
| Size | Typical shape | Agents |
| trivial | decided from the actual diff: no code path changes (copy, typos, comments, config with no behaviour change) | no run. Edit inline, run the gates, write a one-line summary |
| small | one cause, 1 to 2 files, no UI flow change | 1 diagnoser, 1 spec+plan agent, 1 task and its verifier, gates. Symptom check only without a measured repro; docs only if the spec says so |
| medium | one cause, several files or a UI flow | 2 diagnosers on different angles, 3 to 6 tasks, a verifier per task, +1 VIEW when user-visible, +1 harvest when there are findings |
| large | multi-slice feature or several causes | split into sub-issues first and run the smallest first [PL-6]. Cap each run at about 9 tasks [PL-7] |
Trivial is never guessed up front. Make the edit, read git diff, and if it touches any code path, revert it and run it as small. Anything that changes behaviour keeps diagnosis and the negative control.
Announce the size, the agent count, the budget and whether auto-decide is on in one line [SZ-1, SP-20]. A small run then starts. A medium or large announce is a question and waits for a yes, because an accidental run costs hours: "Medium: 2 diagnosers, ~5 build tasks, 5 verifiers, in the background. Go? (Or: stop after the plan for review.)" "Diagnose only" runs with stopAfter: 'diagnose'. A plan review runs with stopAfter: 'plan', then relaunches with resumeFrom: 'build'. Both default off [SP-1].
Respect the human's declared caps (for example "max 3 runs at once"). Count the runs already going before you launch, and queue the rest as issues [SZ-2]. Batch several small, independent issues into one run, with a per-item verify loop and one shared gates pass [SZ-3]. Model and effort per stage come from the profile's tier table. See references/cost.md.
Step 3: run the pipeline
Pick the engine your harness has:
- Workflow tool available (Claude Code): stamp a per-issue copy of
templates/workflow.jswithscripts/stamp-workflow.sh <issue-id>, so that the run's name carries the issue id [OR-3, OR-4]. Then launch it with the args described at the top of the template, includingscratchDirandopenIssues(open issues' number, title and labels, fetched first with the tracker CLI, for examplegh issue list --state open --limit 500 --json number,title,labels; skip it whenissues.auto_fileis false). Workflow scripts cannot read files, so you read the profile, merge it over the defaults inreferences/project-profile.md, and pass it in with the tier table, the domain packs and the skill's path [OR-6]. - Agent/Task subagents only: follow
templates/subagent-fallback.md. It is the same loop, driven by you. - No subagents (another agent harness, or a plain session): run the stages sequentially yourself, as described in
references/process.md. Run the verifier pass in a fresh context if you can get one. If you cannot, switch hats explicitly and assume your own work is wrong.
Lean worker. Stages run as the resolve-worker agent type: core tools only, no MCP, skills, subagents or web, CLAUDE.md kept [CO-9]. Before the first run, check that the type resolves (.claude/agents/resolve-worker.md in the repo, or ~/.claude/agents/; agent files load only at session start, so RESTART Claude Code after installing). If it is missing, offer to copy templates/agents/resolve-worker.md there (a config change, so ask). Until then the run falls back by itself: an unresolved type is retried once as the default agent, logged once, and recorded as metrics.agent_type_fallback. Rules a worker must follow go in profile.laws, never only in memory. Details and the opt-in switches are in references/project-profile.md.
Before launch, create the isolated worktree and branch and assign spare ports (references/isolation.md). Write the spec and plan under the profile's spec_dir. The default is docs/issues/<date>-<slug>/spec.md and plan.md. A value of none means a scratch directory [DC-5].
Stage detail lives in these files, which you should read when that stage runs or when you write its prompt:
| Stage | Read |
| any, entry/exit criteria | references/process.md |
| diagnose | references/diagnosis.md |
| spec, plan | references/spec-and-plan.md, templates/spec.md, templates/plan.md |
| build, verify, repair, view | references/verification.md |
| harvest, filing side issues | references/process.md §9b |
| gates | references/tests-and-gates.md |
| worktrees, ports, env | references/isolation.md |
| docs | references/docs.md |
| anything touching user data | references/privacy.md, references/design-principles.md |
| one product's domain (UX, product scope, imports, runtime cost, tool quirks) | references/packs/, when on via packs: or a diagnosis trigger |
| commits, merge, deploy machinery | references/git-and-handoff.md |
| tiers, budget | references/cost.md |
| talking to the human | references/communication.md |
Composes with
Use these skills when they are installed. The inline rules in this skill are the fallback when they are not.
grill-with-docs: the design grill for feature issues and multi-slice features [SP-1, SP-2].domain-modeling: glossary and ADR writes, in the repo's own ADR format. Rankings stay in the spec.triage: follow-up issues, filed asneeds-triagewith its AI disclaimer, and "which issue next?" questions.codebase-design: the vocabulary behind "shared seam" in law 3.git-guardrails-claude-code: the hook that blocks destructive git, recommended during discovery [HG-5].
Step 4: after the run returns, audit before you believe it
Subagents misreport, and runtimes delete files. The run returns a compact result (status, root cause, gates table, commits, merged findings by severity, follow-ups) and keeps the full stage outputs in its journal and in the spec and plan files [OR-26]. Read the compact result, open the journal only for what it points to, and do all of the following before you say anything is done [VF-10, VF-15, OR-17]:
- Run
git statusandgit ls-files -din the worktree. Restore unexpected deletions without touching new work [VF-15]. - Run
git log <base>..HEADand check that every commit carries the required trailers. An unattributed commit counts as rogue until it is explained [GR-4]. - Cross-check the plan's unit list against the tree. A planned unit with no implementation is a STOP, so dispatch a completion agent for exactly those units [VF-13, OR-10].
- Re-run the gates yourself, independently of the run's gates agent, from the profile's gate list. Save the full output and grep all of it for
failed[VF-10, TG-2]. Checks recorded asci_onlyneed a PR or CI context and are not local gates. If one sits in the gate list and fails for that reason, move it toci_onlyin the profile rather than calling the run red [TG-34].gates_commits_verified: falsemeans the gates agent's own commits failed review: treat the gates as red until you have read them. - Confirm that every server the run started is gone, by process group and
ps, not onlylsof, and that the developer's ports are untouched [IS-8, IS-20]. - Re-triage the merged findings list, defects and test gaps first [VF-31]. "Non-blocking" is the verifier's opinion, not a verdict: re-read each finding against the code and promote any that a user could hit (a page stuck loading, a raw 500, misleading copy). Fix real defects before handoff, and file follow-ups as issues [VF-11].
- File the side issues the run drafted (
side_issues,bundle_issue) unless the profile setsissues.auto_file: false[OR-27]. Re-check each draft against the code first and drop any that is not true or is this branch's own defect (that one goes back to repair). Re-dedupe against a fresh open-issue list fetched now, by concept as well as title: an issue filed after the run's snapshot counts [OR-27]. For aduplicate_ofdraft, comment on that issue with its body. File each serious draft (bundle: false) as its own issue, and the minor ones as the ONE bundle issue, each with itslabels(needs-triage pluslabels.side_issuewhen set) [OR-29]. Abranch_defectsentry is never filed: repair it. Scan every body for identifiers before it leaves [PS-2]. Replace the summary's last line with "New issues filed: #…" (or "none"). - Append one line to
.claude/resolve-issue-runs.jsonl: date, issue, size, status, wall-clock start and end, the run'smetrics(stages, repairs, verifier rejections, gates commits), finding counts by severity, how many findings you promoted at this audit, and the side issues filed. Add theauto_decisionscount andmetrics.cost, the output ofpython3 scripts/run-cost.py <the run's transcript dir>:metrics.stages[].spentcounts output tokens only, about 8% of the cost [CO-9]. Without it, nobody can tell whether a tier or a stage change helped [CO-2]. With 3 or more runs in the log, add one cross-run trend line to the summary (repairs per task, decision stops per run, auto-decisions per run).
Step 5: hand off and stop
The run returns a summary draft rendered from its own data, in the terse format in references/communication.md, with its Insights bullets and any auto-decisions for review. Correct it with what the audit found. It covers the confirmed root cause and how it was confirmed, the rankings used, what changed for the user, the gate results, the commit list, and exactly what the human should check by hand [CM-7]. Then stop.
| Action | Who decides |
| commits on the issue branch inside its worktree | agents, with trailers, explicit paths only |
| merge into the main line | human yes |
| push | a human yes for each push. An earlier "ship it" does not carry forward [HG-2]. Any stricter gate the human declares (a yes per commit, say) applies on top [HG-18] |
| version bump, tag, release, deploy | human yes, done in the main loop, never inside a run [GR-9] |
| repo settings, secrets, CI triggers | human only [HG-1] |
| a decision point inside the run | the decide step, when not critical and the recommendation and ranker agree with margin (max 3, listed in the summary for review); otherwise the human [SP-20] |
| closing the issue | only when the work reaches production and the reporter has confirmed it [GR-10, DG-15] |
When the human says "push it" in this turn, push without asking "are you sure?" [HG-3]. When the permission system blocks an action, do not route around it. Hand the human the exact command [HG-6].
Feed the lessons back
When a run teaches something new, append it to references/lessons.md under the right stage. Use the same format (the rule, why it matters, and a one-line anonymised origin), give it the next free id, and cite it from the stage reference that should apply it. Do this in the same change [DC-21]. A lesson that only holds for one kind of product goes in the matching pack under references/packs/.
Lessons also leave. When one stops earning its place (the tool changed, or it is one product's taste), move it to a pack or mark its line status: archived with a one-line reason, drop its citations, and never reuse its id. Run python3 scripts/check.py. It fails if a core lesson that is not archived is never applied, if an id is defined twice, and if anything private leaks into the skill [TG-23].
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

