Skip to content

RandallLiuXin/GodotMaker / skills/core/gm-rescue

gm-rescue

Verified

Self-diagnostic skill for godotmaker itself. Invoked when the main pipeline can't make progress (e.g. several fixgap rounds in a row failed to converge). NOT a "smarter fixgap" — does not modify game code, does not write files, only reports diagnosis to chat. If a godotmaker-side defect is the root cause, drafts an issue the user can post upstream. Explicit invocation only — use /gm-rescue.

FileKindSize
SKILL.mdskill md8.5 KB
references/diagnostic-checklist.mdmarkdown6.0 KB

references/diagnostic-checklist.md

View on GitHub
# Diagnostic checklist — what to inspect, in what order

Use this when walking the godotmaker layers in `gm-rescue` Step 3.
Order is from highest-leverage failure mode to lowest. Stop as soon
as you have a confirmed defect — you don't need to walk the whole
list every time.

## 1. Hooks (highest leverage)

A misconfigured hook can deny *every* tool call of a given shape, so
its blast radius is huge. Bad hook = stuck pipeline that nothing
else can recover from.

Files to inspect (under `hooks/` in the godotmaker repo):

- `check_stage_prerequisites.py` — denies Agent dispatch if prereqs missing.
  Common defect: a new role added to PIPELINE_ROLES without updating
  PREREQ_ROLE here, or a path that the role legitimately produces under a
  different name.
- `check_completion.py` — blocks Stop in worker-dispatching roles.
  Common defect: BLOCK_LIMIT not high enough; stale state.json
  `stop_block_count` carrying over across sessions.
- `check_file_permissions.py` — denies Write/Edit by role.
  Common defect: a path the SKILL.md tells the agent to write is
  not in the role's allow-list here.
- `check_worker_report.py` — blocks SubagentStop if the worker's
  output doesn't match required structure.
  Common defect: required section name was renamed in worker-dispatch.md
  but not here, so workers can't produce a passing report no matter
  what they write.
- `check_asset_access.py` — denies image binary Read for non-analyst agents.
  Common defect: marks a `references/` path as image when it's actually a
  text file, or vice versa.
- `check_stage_prerequisites.py`'s schema validation against
  `config/stage_schemas.json` — see §3 below.
- `append_stage_event.py` — runs the side-effect-free checks in
  `completion_gate.py` before archiving or appending a role completion.
  Common defect: a check function returns a string the user can't act
  on, or fires on a state the role legitimately produces.

What to look for in each:
- Regex over a path/role name that doesn't match a recently added value.
- A required field the upstream skill never produces.
- Cumulative state (state.json, stage.jsonl) consulted in a way that
  treats prior-tag state as current-tag state.

## 2. SKILL.md instructions (next-highest leverage)

A SKILL.md that contradicts itself or contradicts another role's SKILL.md
will produce inconsistent agent behaviour that no amount of fixgap can
converge.

Files to inspect (under `skills/core/gm-*/SKILL.md`):

- The skill that was active when the pipeline got stuck (read
  `.godotmaker/current_role`).
- The skill immediately upstream (its outputs are this skill's inputs).

What to look for:
- Hard Rule that says "you MUST X" while another section says "do NOT X".
- Resume Check that can never become satisfiable from the current state.
- "Permission" line that omits a path the Process section tells the agent
  to write to (this typically surfaces as a hook block — cross-reference §1).
- References to files / paths that no longer exist in the current layout
  (e.g., a SKILL.md still mentions `.godotmaker/milestones/` after the
  layout changed to `docs/tags/`).

## 3. Config schemas

`config/stage_schemas.json` declares each role's required output files
and `checks`. Mismatches here surface as "Cannot mark role X complete"
errors from `append_stage_event.py`.

What to look for:
- A `files` entry that names a path the role doesn't actually produce
  (or produces under a different name).
- A `checks` entry naming a function that doesn't exist in
  `PROGRAMMATIC_CHECKS` — this would leave the append gate without the named check.
- A role missing entirely from the schema, when downstream code expects
  it (e.g., the `rescue` role).

## 4. Templates

Templates rarely cause hard pipeline blocks on their own, but they
shape what gets generated, and a wrong template can produce documents
that downstream stages can't parse.

Files to inspect (under `templates/`):

- `PLAN.md` — if the `**Tag:**` header or `Tag Mechanics` / `Inherited
  Mechanics` sections are missing, every downstream skill that depends
  on them breaks (gm-build, gm-evaluate especially).
- `STRUCTURE.md`, `SCENES.md`, `ASSETS.md`, `ROADMAP.md`,
  `TOC.md` — same idea, smaller blast radius.
- `game-claude.md` — what gets deployed to the game project's CLAUDE.md.
  Wrong content here misroutes the user's expectations of the pipeline.

## 5. Shared references

Files under `skills/core/_shared/` are deployed into multiple skills'
`references/` directories by `publish.py`. A defect here amplifies
across every consumer.

- `worker-dispatch.md` — consumed by gm-build and gm-fixgap. If the
  brief format here drifts from what `check_worker_report.py` requires,
  every worker fails the report check.
- `verifier-dispatch.md`, `reviewer-dispatch.md`, `analyst-dispatch.md`
  — same pattern.

## 6. Tools

Last resort. Tools (`tools/asset_source_generate.py`, `tools/check_project.py`,
`tools/migrate.py`, etc.) are subprocesses; if they fail, they
typically produce a clear stderr message that the calling skill
relays to the user, so "stuck pipeline with no clear error" is
rarely a tools-layer issue.

If a tool *is* the issue:
- Check whether the tool's expected layout matches the post-tag-refactor
  layout (e.g., a tool looking for root `PLAN.md` as a whole-game plan
  when it's now per-tag).
- Check whether tool flags drifted from how the skill invokes them.

## What to skip

- The user's game code under `src/`, `scenes/`, `assets/`, `e2e/`.
  Issues there are NOT godotmaker defects — they're either AI
  implementation issues or GDD-spec issues, both belong in the
  "NOT A GODOTMAKER DEFECT" branch of the diagnosis.
- `addons/` — third-party (gecs, gdUnit4, etc.). Even if these have bugs,
  godotmaker's contract is "pin a working version", so the defect would
  be in `config/addon_versions.json`, not the addon itself.
- Anything that requires running godot or executing the user's game.
  Rescue is read-only diagnostic; runtime behaviour evidence has to come
  in via the artifacts in `gm-rescue` Step 1.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 323kUpdated Claude CodeCodexVerifiedInstall
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall