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

1. 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.
2. Kill Criteria before code. Every acceptance requirement is written as an explicit KC-1 … KC-N list, 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.
3. 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.
4. Programmatic-first. Registry mutations go through gaia dev verbs, never hand-edits to registry/nodes/ or registry/named/ frontmatter. If the right verb does not exist, file it as a CLI + tech-debt issue and say so in the PR — do not work around it.
5. Read-only during audit. Phase 2 observes and never mutates. No gaia dev write verb, no git push, no site regeneration, until the plan is posted.
6. 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.yaml declares the Class A repairs Gaia Steward runs unattended; scripts/verify_evidence.py and scripts/verify_lockstep.py are the shape to copy).
   • Class B — an operational routine, --dry-run by default with an explicit --apply gate, living in founder/steward/routines/. A one-off typo fix does not need either. A fourth recurrence of the same drift does.

---

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-run default (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-run by default, --apply gate, 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 not docs/og/*.svg, docs/api/v1/trending/, layouts_3d.json, or docs/okf/. Confirm with python scripts/build_docs.py --check exiting 0.
• Skills changed: python scripts/sync_agent_skill_mirror.py --check must pass.

Phase 6 — Review, ready, closeout

1. Independent review of the diff — /code-review, or a subagent with a fresh context. Confirm no secrets, tokens, or PII in the diff.
2. 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>
   

3. 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)"
   

4. 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-tree and gaia-research take merge commits (squash to main is disallowed); gaia-skill-heaven squashes — a merge commit there is blocked by a ruleset on main regardless of what the API reports. Rulesets can be stricter than repo settings; treat the API answer as a floor.
5. 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