version: "1.0.0" name: gdextension-hygiene description: > Run a Godot/GDExtension finish pass over the current diff: enforce headless GDScript validation, public API doc_classes coverage, docs/spec/sample/test synchronization, and registration or CMake follow-through. Triggers: hygiene pass, finish pass, validate diff completeness, godot addon hygiene, gdextension hygiene, preflight diff, final pass

GDExtension Hygiene Skill

You are the repo-local gdextension-hygiene skill. Your job is to inspect the current diff and make sure the change is finished cleanly across the Godot-facing surfaces that usually drift apart.

Core rules

• Start from the current diff or the user-specified files, not from a whole-repo audit.
• Build the checklist from the touched surfaces instead of applying every rule blindly.
• Use the existing repo and path-scoped instructions before inventing new validation steps.
• If the user explicitly wants PR-feedback triage, use pr-feedback-loop first.
• If the user explicitly wants risky-diff pressure testing, use adversarial-review first.

Finish-pass checklist

• For .gd changes anywhere in the repo, run:

pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\tools\check_gd_scripts_headless.ps1

• For godot_gdk public contract changes:
• ensure public classes, methods, properties, signals, and enums stay reflected in

addons\godot_gdk\doc_classes\*.xml

• ensure the related docs\<addon>\*.md, spec\gdext-<addon>.md, sample content, and tests stay

aligned when behavior or script-visible API changes

• For new native classes or source files:
• ensure registration and ownership are wired correctly
• ensure the relevant addon CMakeLists.txt includes the new files
• For synced godot_gdk addon content under addons\godot_gdk\:
• run the existing debug build step that refreshes the sample copy when required by the

path-scoped instructions

• For other addons:
• follow their current build and documentation patterns
• do not invent doc_classes requirements for addons that do not currently ship them
• For tutorial / sample snippet drift (the hand-discipline backstop — there is

no machine validator that holds tutorial prose and sample scripts in lockstep):

• If any docs\tutorials\**\*.md was edited in this diff, verify the matching

scene or script under the relevant sample\tutorial_gdk\, sample\tutorial_playfab\, sample\tutorial_integrated\ (or sample\tutorial_gameinput\ for the standalone GameInput track) was also touched in the same diff. The sample is the "this is what you should have" anchor for the tutorial reader, so a tutorial-only change is a drift smell unless the snippet genuinely matches what already ships.

• If any script under sample\tutorial_gdk\, sample\tutorial_playfab\,

sample\tutorial_integrated\, or sample\tutorial_gameinput\ was edited in this diff, verify the matching docs\tutorials\**\*.md was also touched. A sample-only change without the matching tutorial update silently walks the reader off the rails.

• If the change is intentionally docs-only or sample-only (typo fix, comment

polish, scene-tree node order that does not appear in any snippet, autoload refactor that does not change the snippet shape), call it out explicitly in the report so the reviewer can confirm the asymmetry is on purpose.

Workflow

1. Identify the changed surfaces in the diff.
2. Build the minimum finish-pass checklist that applies to those surfaces.
3. Fix the missing follow-through directly when it is concrete and local.
4. Run the narrowest existing validation that proves the change is complete.
5. Report any remaining gaps that need a product or scope decision.

Output format

Use this structure:

1. Scope
2. Required follow-through
3. Gaps fixed
4. Remaining gaps
5. Validation