summerengine/summer/debug

/debug — Triage and Fix a Bug End-to-End

The disciplined debugging loop for Summer projects. Read the error before guessing. Form a hypothesis before editing. Verify the fix before declaring victory. Never grep the codebase before reading the actual error.

Core principle: The debugger already knows what's wrong. Your job is to listen to it before doing anything else.

When to use this skill

• The user says "it crashes", "it broke", "throws an error", "doesn't work", "freezes", "wrong behavior".
• The user invokes /summer debug, asks for a support report, or wants something they can send to Summer.
• The user pastes a stack trace.
• A previous build or test step failed and the user wants to fix it.

When NOT to use this skill

• The user is asking how to prevent a class of bug — that's a design question. Use the relevant discipline skill (gdscript-patterns, scene-composition).
• The user is asking for a feature with a known unfinished spec — that's make-game territory.
• The bug is in a file outside the game project that the host agent can debug natively (CI config, npm scripts) — use the host's debugger.

The Loop

  Listen → Diagnose → Hypothesize → Propose → Fix → Verify

Do not skip steps. Do not loop back to "Hypothesize" without re-running the cheap diagnostic.

0. Support report mode

If the user asks for /summer debug, "send this to Summer", "make a report", or they are stuck in Codex, a cloud sandbox, or another agent environment, create a portable report first:

summer_create_debug_report({
  issue: "<one-sentence user symptom>",
  include_play_session: <true only when the issue appears during runtime>
})

Tell the user where the Markdown file was written and remind them to review local paths and stack traces before sending. Then continue the normal debug loop only if they also asked you to fix the bug.

Fallback when the MCP tool is not available but shell is available:

summer debug "<one-sentence user symptom>"

Add --play only when the issue appears after pressing Play.

1. Listen

Ask the user one focused question and wait for the answer:

What's happening, and when does it happen?

If they already gave a clear symptom in the request, skip the question. If they say "something's broken", that one question is your only call until they reply. Don't run tools yet.

2. Diagnose — cheapest tool first

In strict order. Stop at the first one that returns useful signal.

If `summer_get_script_errors` is clean and the user says it crashes only when running: it's a runtime bug. Go to step 2b.

2b. Runtime-only bugs

Reproduce it yourself first. Write a RunVerification probe that performs the repro steps (press / key), reports the state you expect to be wrong, and saves a frame. See "Drive the game yourself" below for the exact call. The returned results.errors_seen and reports are the diagnostic. This costs one call, touches nothing the user owns, and gives you a repro you can re-run after the fix.

Fall back to the editor session only when the repro genuinely needs a human (feel, hardware, "is this what you meant?"):

  summer_clear_console
  summer_play
  ─▶ ASK USER: "Reproduce the bug now."
  (wait for confirmation)
  summer_get_debugger_errors
  summer_get_debugger_warnings   (if diagnostics showed warnings)
  summer_stop

If you go this route, do not skip the "reproduce now" prompt. Auto-running and grabbing whatever's in the buffer leads you to chase ghosts from previous sessions.

2c. Missing MCP tools versus an unavailable engine

If summer_get_script_errors is not listed in this session, use summer engine get-script-errors from the shell (see summer-cli for flags and the package-version fallback). Missing MCP tools alone do not mean Summer Engine is stopped. Continue the same diagnostic order through the shell equivalents below.

If the operation returns engine_not_running (or "Summer Engine is not running"), follow summer-cli's "Start or reconnect to Summer Engine" sequence: open the existing project yourself, wait for readiness, verify project context, then retry the diagnostic. Use the project's exact path; bare summer run fails. Starting the engine does not reload the host's MCP tool list.

Only when neither MCP nor shell access can read the engine, ask the user for the Output and Debugger panel text. Reason over it and continue the diagnostic loop, explicitly noting anything you could not verify. Do not loop on unavailable MCP tools, recreate the project, or substitute stock Godot.

3. Hypothesize — one specific theory

State exactly one hypothesis, in one sentence, naming the file and line.

Good: "Typo at scripts/player.gd:14 — GRAVTY should be GRAVITY."

Bad: "Could be a typo, missing import, or wrong scope."

If you have multiple plausible theories, pick the highest-prior-probability one. The user can correct you if you're wrong; chasing all three at once wastes their time.

Verify the hypothesis without editing. If the error mentions a missing node, call summer_inspect_node to confirm. If it's a missing resource, summer_inspect_resource. If it's a scene-graph issue, summer_get_scene_tree. Confirm the world state matches the error before proposing a fix.

4. Propose — ask before writing

Surface the proposed fix in plain language and ask permission. Two patterns:

Code fix:

May I edit scripts/player.gd to rename GRAVTY → GRAVITY on line 14?

Scene fix vs code fix:

The script calls audio.play() but the AudioStreamPlayer child is gone. Two options:

1. Re-add the AudioStreamPlayer to ./Coin (preserves the original behavior).

2. Null-check in coin.gd (defensive, but the audio is silent).

Which one do you want?

Never unilaterally pick when there are two equally valid fixes (scene vs code, defensive vs strict, fast vs correct). Ask.

5. Fix — minimal, focused

• For GDScript edits: Read the 20–40 lines around the error, Edit the exact change. Don't read the whole file. Don't reformat. Don't rename other things.
• For scene edits: use the appropriate summer_* tool (summer_add_node, summer_set_prop, summer_replace_node). Group multi-step changes in summer_batch for one undo step.
• Nested resource properties: summer_set_resource_property works against inline sub_resource targets too — pass nodePath, resourceProperty, and subProperty (there is no dotted "mesh.size" form). Structural failures (node not found, property is not a resource, resource is null) are explicit errors; a bad value shape is not — a JSON object instead of an engine literal string, a misspelled key/subProperty, or a wrong-typed value returns ok:true yet silently no-ops or coerces destructively on current engines (dict → material cleared; dict → Color(0,0,0,1); newer engines reject these with unknown_property / bad_value_shape / type_mismatch). Pass class names and Color(...)/Vector3(...) strings, and confirm the fix in the saved .tscn or a snapshot diff, never from ok alone. See summer_docs_read id reference/mcp-tools-reference.

6. Verify — re-run the diagnostic that found it

The fix is not done until the same diagnostic that found the bug returns clean.

• Script error → re-run summer_get_script_errors.
• Runtime error → re-run the play/reproduce/check-debugger loop.
• Console warning → summer_clear_console, then summer_play and confirm clean output.

If the diagnostic is still red after the fix, you formed the wrong hypothesis. Go back to step 3 — do not make a second edit on top of the first. Revert if the first edit didn't help, then re-hypothesize.

Anti-Patterns

Quick reference — common Summer Engine bug families

Closing

A debug session is done when:

1. The user-reported symptom no longer reproduces.
2. The diagnostic that originally flagged the bug returns clean.
3. No new errors or warnings have been introduced.

Tell the user one short sentence: "Fixed <file>:<line> — <change>. Diagnostic clean." Then stop.

What the MCP debug tools CAN and CAN'T see (read this before claiming "clean")

The static and boot-time tools (summer_get_script_errors, summer_get_console, summer_get_diagnostics) can't substitute for play-testing — but you have a play-testing route, so a false-clean report is a choice, not a limitation. Know which tool answers which question.

What the MCP CAN see