Agent Skills: Debugging

Debugging

Before choosing project-specific backup locations or environment assumptions, read skill-local guidance only when .kilocode/skills/coding-debug/AGENTS.md is confirmed to exist; otherwise use root AGENTS.md.

Workflow

Constraint: Execute sequentially. Skip nothing.

1: Get ready

Use coding-lifecycle skill, Entrypoint: Start coding work.

2: Systematic debugging process

• Incorporate testing into the debugging work according to the verification strategy established by coding-lifecycle.
• Use app-standards to accomplish the task to the best of your abilities. Steps:
• You must complete each step below in order before continuing to the next, unless explicitly overridden by the user.

1. Read error messages carefully.
   • Do not skip past errors or warnings; they often contain the exact cause.
   • Read stack traces completely.
   • Note line numbers, file paths, error messages, and error codes.
2. Reproduce consistently.
   • Determine precise reproduction steps (URL, inputs, environment, auth state).
   • Confirm whether the issue happens every time:
     • If consistent: document exact steps.
     • If intermittent: gather more observations; do not guess.
3. Gather context to understand related code and recent changes.
   • Ask yourself:
     • What changed that could cause this?
     • Which modules, routes, or DB tables participate in this path?
     • Are there config or environment differences?
4. Form hypotheses.
   • Brainstorm 5–7 plausible causes; narrow to the 1–3 most likely.
   • Add targeted logging or instrumentation to validate assumptions.
   • Prefer minimal, reversible instrumentation changes.
   • Confirm diagnosis:
     • Use logging plus reproduction to prove or disprove each hypothesis.
     • Summarize findings for the user before implementing permanent fixes when appropriate.
   • Create backup:
     • Save the current state of files you will modify under the project-approved backup location with a timestamp.
5. Form a fix plan based on confirmed or most likely hypotheses.
   • Prioritize by risk/impact: address high-impact, low-risk changes first.
   • Break complex fixes into small, independent steps.
   • Identify exact files, functions, and lines you plan to modify.
   • Define verification steps for each change (tests, manual checks, logs).
   • Consider side effects: note other flows that may be impacted.
   • Plan rollback:
     • Know how to revert to previous state quickly if a fix fails.
6. Implement the fix systematically.
   • Create a backup before each file modification under the project-approved backup location.
   • Make ONE logical change at a time; do not bundle unrelated fixes.
   • If the verification strategy calls for tests, test after each change.
   • If a change does not help:
     • Revert immediately.
     • Update your notes and return to the hypothesis step above.
7. If still unclear after several attempts:
   • Reassess hypotheses.
   • Consider higher-level issues (architecture, data model, or configuration).
   • Escalate or involve whichever other mode is best if the required changes are clearly architectural or very large in scope.

If stuck in a loop:

1. Try one completely different approach (algorithm, architecture, or module choice).
2. Check using learning skill for prior solutions or patterns.
3. Try two more novel solutions.
4. If still stuck:
   • Prepare two new, clearly different approach ideas.
   • Present them to the user along with the option: "Abandon this task and return to plan flow."
   • Wait for user direction.

3: Finish

Use coding-lifecycle skill, Entrypoint: Finish coding work.