pos-ai: Skill for Claude Code

Debugging Skill

You are systematically debugging an issue. Follow this structured approach — never brute-force retry the same thing. Every step narrows the search space.

Setup

Before starting: check .handoff/sessions/ for active sessions, read context status.yaml, run git status. Follow .rules/universal.md (Plan -> Approve -> Execute).

Process

Step 1: Reproduce

Before anything else, confirm the bug exists and is reproducible.

1. Get the error — Exact error message, stack trace, or unexpected behavior description
2. Get the context — When did it start? What changed recently? Which environment?
3. Reproduce locally — Run the failing command/test/request and capture the full output
4. If not reproducible — Check environment differences, data differences, timing/race conditions

Output: "I can reproduce this: {exact steps and output}" — OR — "Cannot reproduce. Need: {what additional info is required}"

Step 2: Isolate

Narrow down where the bug lives.

1. Check recent changes — git log --oneline -20, git diff for uncommitted work
2. Trace the execution path — Follow the request/data from entry point to failure
3. Binary search — If the codebase is large, bisect: does the bug exist in module A or B?
4. Check boundaries — Is the bug in our code, a dependency, the database, or the infrastructure?

Key questions:

• Does it fail with the simplest possible input?
• Does it fail in a different environment?
• Does reverting the last change fix it?
• Is it data-dependent?

Output: "The bug is in {file}:{line_range} because {evidence}"

Step 3: Diagnose

Understand the root cause, not just the symptom.

1. Read the code — Read the actual implementation, don't assume
2. Check assumptions — What does the code assume about inputs, state, ordering?
3. Look for common patterns:
   • Null/undefined access — Missing null checks, optional chaining needed
   • Race condition — Async operations completing in unexpected order
   • State mutation — Shared state modified unexpectedly
   • Type mismatch — String vs number, date formats, encoding
   • Off-by-one — Array bounds, pagination, date ranges
   • Missing migration — Database schema doesn't match model
   • Cache stale — OPcache, view cache, query cache serving old data
   • Environment mismatch — .env values, Docker config, service URLs
   • Dependency version — Breaking change in updated package