
Gameplay Mechanics Debugger
Diagnose gameplay bugs by analyzing code, feedback, and state interactions
What You Can Do
You can transform vague player bug reports into actionable fixes by establishing clear reproduction steps, identifying state conflicts across mechanics systems, and verifying solutions against edge cases. This skill helps you diagnose complex issues that emerge from interactions between physics, input handling, state management, and animation—reducing feedback iteration cycles with QA and community.
Features
structure vague bug reports into repeatable steps with specific conditions and triggers
identify conflicts and dependencies between gameplay systems (physics, input, state, animation)
systematically eliminate potential causes by testing hypotheses against code behavior
validate fixes work across timing variations, input sequences, and game state combinations
reproduce bugs in controlled contexts to determine if issues stem from single systems or cross-system interactions
convert qualitative descriptions ('feels wrong') into technical requirements and observable behaviors
document findings with code references, reproduction steps, and recommended implementation paths
Example Output
Input: Player reports: 'Jump sometimes doesn't trigger when landing on slopes'
Output:
## Reproduction Steps
1. Land on slope with angle > 35°
2. Press jump within 2 frames of ground contact
3. Jump fails ~40% of the time
## Root Cause Analysis
- Ground detection checks velocity Y, not surface normal
- Slope landing produces partial velocity retention
- Timing window misaligns with state update frequency
## Fix: Normalize ground check to use surface contact point, not velocity threshold
Input: Multiple reports of collision clipping in doorway sequences
Output:
## State Conflict Identified
- Physics collider updates on frame N
- Animation state changes on frame N+1
- Door trigger activates on frame N (before collider reset)
## Recommendation: Sync physics queries to animation state callbacks
What's Included
- SKILL.md: Complete debugging workflow with phases and structured analysis templates
- Reproduction Template: Standardized format for documenting bug conditions, triggers, and frequency
- State Interaction Checklist: Systems to verify when diagnosing cross-system bugs (physics, input, state, animation, networking)
- Root Cause Analysis Framework: Hypothesis-driven testing methodology with elimination matrix
- Bug Report Format: Professional documentation template with code references and implementation recommendations
Who It's For
- Gameplay Programmers — diagnosing complex mechanic interactions and state-dependent bugs
- QA Lead/Test Automation Engineers — translating player reports into reproducible test cases
- Technical Game Designers — understanding why mechanics behave unexpectedly in integrated gameplay
- Multiplayer/Networking Programmers — isolating bugs in state synchronization and latency-sensitive interactions
- Game Engine Developers — preparing detailed bug reports for physics, input, or core systems
Best For
- Bugs that only occur under specific condition combinations (timing, state, input sequences)
- Cross-system issues where multiple mechanics could be responsible
- Reproducing and documenting inconsistent or intermittent failures
- Analyzing edge cases in movement, collision, state transitions, or timing windows
- Reducing iteration cycles between development and QA by providing comprehensive reproduction documentation







