AKDworks/Godot-Clarity

Godot Clarity

Work from the project and engine as evidence. Treat scripts, scenes, Resources, project settings, imports, and runtime behavior as one system. Never present static inspection as engine-verified behavior.

Choose the operating mode

• Create: establish a small project contract, build one playable vertical slice, then extract only proven abstractions.
• Extend: trace the existing feature across every serialized and scripted dependency, then make the smallest cross-file-complete change.
• Debug: preserve a deterministic reproduction, find the first causal failure, change one contract, and rerun the same proof.
• Review: report concrete correctness, lifecycle, compatibility, safety, and verification gaps without rewriting the project unless asked.

For creation work, read project workflow before generating files. When the requested slice includes a common gameplay feature, also read gameplay patterns and adapt the smallest matching contract. For an established project, preserve coherent local conventions unless they cause the bug or conflict with the request.

Establish the project contract

1. Locate the real root from project.godot, or choose it explicitly for a new project.
2. Read repository instructions and preserve unrelated user changes.
3. Determine the exact Godot version, 2D/3D domain, renderer, target platforms, and primary language from project files and the intended executable.
4. Inspect project.godot, the relevant scenes/scripts/Resources, inherited or imported scenes, autoloads, InputMap, named layers, audio buses, and export presets.
5. Resolve only decisions that materially change the result. State conservative assumptions when the user leaves them open.

Target Godot 4.7.x and GDScript directly. Treat Godot 4.0–4.6 as best effort: consult the matching versioned documentation before using version-sensitive APIs or serialized properties. Do not emit Godot 3 patterns. Treat C#, GDExtension, engine modules, and console-platform specifics as outside the core scope unless requested.

Define the smallest complete outcome

Before editing, build a compact change contract:

• the observable behavior requested by the user;
• the scene or system that owns it;
• the existing public API and conventions that must remain stable;
• every script, scene, Resource, project setting, and asset path that participates;
• the smallest repeatable observation that would distinguish success from a partial patch.

Keep this map internal unless sharing it helps the user make a decision. For an existing project, derive it from real files and references rather than presumed node paths. For a new project, choose the repository layout and write a file manifest before generating content. Every proposed file must have one clear owner and one immediate consumer; omit speculative base classes, managers, and empty folders.

Do not begin with an isolated script when the behavior also requires a scene node, InputMap action, signal connection, collision shape, Resource, autoload, audio bus, or main-scene setting. Create or update the full dependency chain in one coherent patch.

Run the Project Doctor when it adds evidence

For Debug or Review work, and for collision or Extend work whose cause may cross scenes and project settings, run the bundled read-only preflight before editing when Python 3.10+ is available:

python <skill-directory>/scripts/project_doctor.py <project-root> --format json
python <skill-directory>/scripts/project_doctor.py <project-root> --format json --focus collisions

Use the collision focus when its static inventory can distinguish competing causes such as missing shapes, filtering, monitoring, or scene ownership. Skip it for a small isolated fixture when a supplied behavioral verifier already reproduces the failure and focused inspection localizes the broken contract. For Create mode, run the full Doctor after the first vertical slice exists. Skip it for explanation-only requests or when no project is available; do not install dependencies merely to run it or rerun it mechanically after a proven repair.

Treat each finding as a diagnostic lead. Check its evidence and confidence, reject false positives using project context, and perform the stated runtime verification before claiming behavior. The Doctor never edits files, runs Godot, expands every inherited/imported graph, or proves physics behavior.

Trace behavior across boundaries

Before editing, map:

• scene ownership, node types, lifecycle, and public root APIs;
• resource paths, subresources, sharing, and per-instance mutation;
• signal declarations, connections, groups, autoloads, and awaited continuations;
• InputMap actions, audio buses, animation paths, and named layer/mask contracts;
• imported/generated ownership and export/platform constraints;
• the smallest observable outcome that proves the requested behavior.

Do not treat a .gd file as the entire feature. A valid script can still fail because a shape is absent, a signal is disconnected, an action is undefined, a Resource is shared, or a serialized NodePath is stale.

Make a coherent patch

• Match naming, typing, formatting, composition, and connection style already used by the project.
• Prefer a scene root's narrow typed API over reaching into its internal children.
• Let parents issue commands downward and children announce events upward; coordinate siblings at their common owner.
• Use Nodes for SceneTree lifecycle, Resources for serializable data, and RefCounted objects for tree-independent runtime logic.
• Add an autoload only for a narrow system whose lifetime and responsibility genuinely span scene changes.
• Preserve .tscn/.tres IDs, owners, instance edges, NodePaths, tracks, and connections. Never edit .godot/ generated data.
• Do not invent engine APIs, property names, UIDs, or project settings. Verify uncertain details against the installed engine or the exact versioned class reference.
• Avoid speculative managers, event buses, frameworks, object pools, and broad refactors before real consumers justify them.

Route to the relevant reference

Treat this table as a routing index, not a preload list. Start with the narrowest primary reference for the demonstrated concern. Follow another matching row only when project evidence or the first reference exposes that second concern. When the task is primarily a choice between several valid mechanisms, start with the decision guide, select one contract, then load only its domain reference.

Concern	Primary reference
Choosing Node/Resource/RefCounted, call/signal, dependency path, body/Area/query, autoload/local owner, composition/inheritance, or repository layout	Decision guide
Engine version, migration, serialized compatibility, backend differences	Version compatibility
New project, renderer/targets, repository layout, vertical slice	Project workflow
Scene boundaries, ownership, Resources, autoloads, .tscn/.tres	Scene and Resource architecture
Typed GDScript, lifecycle, signals, await, Godot 3 migration	GDScript
Player/enemy actors, health, damage, weapons, projectiles, interactions, spawners, states, HUD, pause, transitions, camera ownership	Gameplay patterns
Any collision, movement, hitbox, trigger, projectile, ray/shape query, physics layer or mask	Collision reasoning core
Implementing or changing a mover, platform, hitbox/hurtbox, trigger, rigid contact, projectile, or physics query	Collision implementation patterns
Diagnosing or reviewing missed/duplicate contacts, tunneling, floor/platform faults, query timing, or shared shapes	Collision diagnosis
InputMap, rebinding, controller/touch, HUD, menus, focus, resolution, pause	Input and UI
TileMapLayer/GridMap, world transforms, Camera2D/3D, level streaming	Worlds, cameras, and tile/grid content
AnimationPlayer/Tree, imported animation, root motion, sound, buses	Animation and audio
NavigationRegion/Mesh/Agent, avoidance, dynamic pathing	Navigation
Settings, save/load, schemas, runtime files, migrations	Persistence
HTTP, WebSocket, RPC, ENet, replication, authority	Networking
Renderer, imports, materials, shaders, cameras, visual layers	Rendering and shaders
Export presets, desktop/mobile/web/server constraints, release artifacts	Export and platforms
Reproduction, engine errors, profiling, stutter, threading	Debugging and performance
Commands, headless checks, behavioral verifiers, export proof	Verification

Enforce collision correctness

For every collision-related task, read Collision reasoning core and build the interaction contract below. Then choose one primary path: use Collision implementation patterns when selecting or changing the mechanism; use Collision diagnosis for an unexplained failure. Load both only when diagnosis exposes a remaining design choice. Do not load the general architecture or GDScript references unless project evidence requires them.

• exact 2D/3D participants and body/Area types;
• active shape ownership and transforms;
• both layer/mask directions;
• movement owner, callback, units, and movement API;
• monitoring/contact/CCD or sweep settings;
• expected event and physical response;
• a bounded runtime proof.

Verify the whole chain. A changed signal handler or mask alone is not a collision fix.

Verify before declaring success

Run an existing focused verifier first. Read Verification when no suitable proof exists, when designing or strengthening a verifier, or when its result needs interpretation. Use the strongest available rung:

1. inspect the focused diff and search every renamed path/action/layer/bus/signal consumer;
2. run repository validators and focused tests;
3. run the version-matched Godot import and parser checks;
4. instantiate the affected scenes and Resources;
5. execute a bounded behavioral check for the fragile outcome;
6. run integration and affected export presets when available.

Treat parser errors, missing resources, invalid NodePaths, relevant warnings, timeouts, and unexpected engine output as failures. Do not conceal them with sleeps, broad null checks, or swallowed errors.

Report completion

Lead with the behavior delivered. State the exact Godot executable/version and checks that actually ran. Separate passed, failed, and not-run checks, then call out remaining visual, editor-only, hardware, network, or platform risk. If no matching executable or reproducible path is available, describe the limitation and do not call the result verified or release-ready.