gaia-issue-resolver
Skill4 starsChanged 12 days agoMITView on GitHub
End-to-end plan → implement → review pipeline that takes one triaged Gaia issue to a merged-ready PR, with Kill Criteria on the issue and zero follow-up debt. Use when someone says: "resolve this issue", "take #N end-to-end", "work the P0 queue", "fix and ship this issue", "run the resolver", "close out this issue properly", or /gaia-issue-resolver. Works any gaia-research org repo — gaia-skill-tree, gaia-research, gaia-skill-heaven — while the issue itself lives on the headquarters tracker, gaia-research/gaia-skill-tree. Assumes the issue is already triaged and carries a P0–P4 label; if it does not, run /gaia-triage first.
- Commits and pushes
1 other project uses a version of this.
Adopted by
Most recently taken up by
- gaia-research/gaia-skill-treeword for word, first seen Nov 14, 2026
Other versions1 project uses a version of this.
Word for word · 1
- gaia-research/gaia-skill-tree★ 22100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
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.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- gaia-issue-resolverSkill
- gaia-triageSkill
- impeccableSkill
- lucy-image-productionSkill
- lucy-riveSkill
- lucy-tunerSkill
- wayfinderSkill
- gaia-triageSkill
- impeccableSkill
- lucy-riveSkill
- wayfinderSkill
- impeccableSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
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 29
Zero follow-up debt: Do not close an issue by filing a trailing "clean up" issue that carries its own unfinished work.
- Very specific: line 34
Kill Criteria before code: Every acceptance requirement is written as an explicit KC-1 … KC-N list, posted as a comment on the issue …
- Distinctive: line 46
Class A / Class B dual delivery, where it applies: If the issue describes a recurring drift rather than a one-off defect, ship a detector …
- Very specific: line 68
Read the whole thread, not the title.
- Distinctive: line 93
Write the plan, then formalize it as Kill Criteria covering, as applicable:
- Distinctive: line 127
When the issue warrants dual delivery:
- Very specific: line 139
Run the Class B routine --dry-run, inspect the plan, --apply, then dry-run again and show 0 planned actions.
- Distinctive: line 199
before/after readings of the Phase 2 probe
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
gaia-issue-resolver
Execute the complete resolution pipeline on one already-triaged Gaia issue, selected
by priority (P0–P4) or assignee. Adapted from favorchurch/rock-steward's
rock-issue-resolver; the six-phase shape and the Kill Criteria discipline are its
contribution, the Gaia mechanics below are this repo's.
Prerequisite: the issue is triaged — it has a priority label, a size, and a stated
problem. If it doesn't, stop and run /gaia-triage on it first. This skill resolves; it
does not decide what is worth resolving.
1. Non-negotiables
- Zero follow-up debt. Do not close an issue by filing a trailing "clean up" issue
that carries its own unfinished work. Everything a reasonable reviewer would call a
direct consequence of this change belongs in this change. This is
gaia-skill-tree's sprint-completeness rule applied at issue granularity: genuinely new, out-of-scope work discovered along the way may still be filed; the issue's own remainder may not. - Kill Criteria before code. Every acceptance requirement is written as an explicit
KC-1 … KC-Nlist, posted as a comment on the issue before implementation starts, and checked off from evidence before closing. An issue with no Kill Criteria has no definition of done. - Draft PR first, push often. Branch, then open a draft PR as the first git operation after the first commit — before the work is finished. Push after each phase. Draft PRs stay draft until a human marks them ready.
- Programmatic-first. Registry mutations go through
gaia devverbs, never hand-edits toregistry/nodes/orregistry/named/frontmatter. If the right verb does not exist, file it as aCLI+tech-debtissue and say so in the PR — do not work around it. - Read-only during audit. Phase 2 observes and never mutates. No
gaia devwrite verb, nogit push, no site regeneration, until the plan is posted. - Class A / Class B dual delivery, where it applies. If the issue describes a
recurring drift rather than a one-off defect, ship a detector alongside the fix:
- Class A — a read-only, deterministic check that observes the condition
(
founder/steward/POLICY.yamldeclares the Class A repairs Gaia Steward runs unattended;scripts/verify_evidence.pyandscripts/verify_lockstep.pyare the shape to copy). - Class B — an operational routine,
--dry-runby default with an explicit--applygate, living infounder/steward/routines/. A one-off typo fix does not need either. A fourth recurrence of the same drift does.
- Class A — a read-only, deterministic check that observes the condition
(
2. The six phases
Phase 1 — Intake & scope
export GAIA_HQ=gaia-research/gaia-skill-tree
gh issue list --repo "$GAIA_HQ" --label P0 --state open # or --assignee @me
gh issue view <n> --repo "$GAIA_HQ" --commentsRead the whole thread, not the title. Note which repo the fix lands in — the issue is
in HQ, the code may not be (see /wayfinder §1 for the target-repo convention). Confirm
the issue is still real before spending a session on it; a stale issue is a /gaia-triage
close, not a resolution.
Phase 2 — Baseline audit (read-only)
Establish what is actually true now, from the artifact, not from the issue text. Pick the probes that match the domain:
| Domain | Baseline probe |
| Registry data / evidence | gaia dev list --generic --named, gaia dev audit, python3 scripts/verify_evidence.py |
| Trust Magnitude | gaia dev calibrate-trust-magnitude --skill <id> --dry-run, /trust-appraise |
| Docs / Class S drift | python scripts/build_docs.py --check (must exit 0) |
| CLI behaviour | run the actual command; read src/gaia_cli/commands/ |
| Versioning | python scripts/verify_lockstep.py |
| Site rendering | /design-gate, or node scripts/visual-audit.mjs in gaia-research |
| Nomenclature | npx tsx scripts/lexicon/check-lexicon.ts (in gaia-research) |
Capture the baseline output. It is what proves the fix later, and a number you did not capture before the change cannot be claimed after it.
Phase 3 — Plan, Kill Criteria, draft PR
Write the plan, then formalize it as Kill Criteria covering, as applicable:
- the defect actually fixed, with the failing probe from Phase 2 named
- Class A detection (if the issue is recurring drift)
- Class B remediation routine,
--dry-rundefault (same condition) - generated-artifact cohesion — Class S committed alongside the source change
- automated tests passing
- idempotency: a second run plans zero actions
- CI green
Post them:
gh issue comment <n> --repo "$GAIA_HQ" --body-file kill-criteria.mdBranch and open the draft PR against the correct base — an integration branch if the
effort spans multiple PRs, main otherwise:
git checkout -b fix/<topic>-<issue-number> # or feat/<workstream>-<slug>
gh pr create --draft --body-file pr-body.mdBranch prefix must satisfy the target repo's scope rules — in gaia-skill-tree,
.github/workflows/branch-scope.yml enforces which directories each prefix may touch
(schema/, cli/, docs/, design/, review/meta/, infra/, dev/, claude/).
Phase 4 — Implement & test
One logical change per commit; push after each. Registry mutations through gaia dev.
Tests are surgical during the loop and full once before review — CI runs on every push,
so read results rather than re-running locally.
When the issue warrants dual delivery:
- Class A check — deterministic, read-only, structured output, non-zero exit on detection.
- Class B routine in
founder/steward/routines/—--dry-runby default,--applygate, a receipt of what it changed.
Cover in tests: the computation and its edge cases, the CLI flags and exit codes, and an idempotency proof (second run ⇒ zero planned actions).
Phase 5 — Verify against the baseline
- Re-run the Phase 2 probe. It must now pass, and you must show both readings.
- Run the Class B routine
--dry-run, inspect the plan,--apply, then dry-run again and show 0 planned actions. - Re-run the Class A check → clean.
- Registry changes:
gaia dev docs, then commit the deterministic Class S set only —docs/graph/*,docs/api/v1/**,docs/u/<handle>/index.html,docs/tree.md,registry/registry.md,docs/graph/ledger/data.json— and notdocs/og/*.svg,docs/api/v1/trending/,layouts_3d.json, ordocs/okf/. Confirm withpython scripts/build_docs.py --checkexiting 0. - Skills changed:
python scripts/sync_agent_skill_mirror.py --checkmust pass.
Phase 6 — Review, ready, closeout
- Independent review of the diff —
/code-review, or a subagent with a fresh context. Confirm no secrets, tokens, or PII in the diff. - Mark ready only if the change is not human-gated. Frontend changes are founder-gated
in
gaia-skill-tree: agents may open, iterate, and mark ready, but may not merge. Attach the evidence page from/design-gate.gh pr ready <pr> - Post the closeout comment: every Kill Criterion checked off with the evidence that
satisfied it (a command output, a file path, a commit sha), then close.
gh issue close <n> --repo "$GAIA_HQ" --reason completed --comment "$(cat closeout.md)" - Merge verb is per repo, not per project — check before merging:
gh api repos/<owner>/<repo> --jq '{squash:.allow_squash_merge,merge:.allow_merge_commit,rebase:.allow_rebase_merge}'gaia-skill-treeandgaia-researchtake merge commits (squash tomainis disallowed);gaia-skill-heavensquashes — a merge commit there is blocked by a ruleset onmainregardless of what the API reports. Rulesets can be stricter than repo settings; treat the API answer as a floor. - Report token spend for the session (
/pi-cost) as a comment on the PR, or on the issue when there is no PR.
3. Priority behaviour
The P0–P4 ladder is the one /gaia-triage, /gaia-meta-audit, and /gaia-meta-sweep
already use — do not import a second one. What changes per priority is how much pipeline
the issue earns:
| Priority | Pipeline |
P0 | Full six phases. Interrupt other work. Dual delivery expected — a P0 that recurred once will recur again. |
P1 | Full six phases. Class A detection expected; Class B if the remediation is repeatable. |
P2 | Full six phases, dual delivery optional. |
P3 | Phases 1, 3, 4, 6. Baseline probe only where a number is claimed. |
P4 | Phases 1, 4, 6. Kill Criteria may be a single line. Do not over-ceremony a typo. |
4. Output
Close every run with:
- the issue and PR, by title and number
- each Kill Criterion, checked off with its evidence
- before/after readings of the Phase 2 probe
- what shipped as Class A vs Class B, or an explicit "one-off — neither warranted"
- anything genuinely out of scope that was filed separately, and why it was not this issue's remainder
- session token spend and estimated cost
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.

