gaia-research/gaia-skill-tree / .agents/skills/gaia-issue-resolver
gaia-issue-resolver
VerifiedEnd-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.
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" --comments
Read 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.md
Branch 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.md
Branch 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |