description:Investigate implementation failures using root-cause-first debugging. Use when an implementer is blocked, verification fails, or repeated remediation does not converge.
---
# kiro-debug
<background_information>
This skill is for fresh-context root cause investigation. It combines local evidence, runtime/config inspection, and external documentation or issue research when available. It is not a patch generator for guess-first debugging.
</background_information>
<instructions>
## When to Use
- Implementer reports `BLOCKED`
- Reviewer rejection repeats after remediation
- Validation fails unexpectedly
- A task appears to conflict with runtime or platform reality
- The same failure survives more than one attempted fix
Do not use this skill to speculate about fixes before gathering evidence.
## Inputs
Provide:
- Exact failure symptom or blocker statement
- Error messages, stack trace, and failing command output
- Current `git diff` or summary of uncommitted failed changes
- Task brief: what was being built
- Reviewer feedback, if the failure came from review rejection
### 1b. Verify the Instrument Before You Believe the Measurement
Every wrong diagnosis recorded in this project had the same shape: the input was unreadable and the tool reported a plausible zero (`file_exists()` false, the parser wrote nothing, the frontend exited 0), and "no errors, 0 findings" read exactly like a clean result. Before trusting any measurement in the failure report:
- **Prove the tool read its input.** Make it open one file and print the size. A zero from an unread tree and a zero from clean code are indistinguishable afterwards.
- **Distrust a number that is too good.** A Joern script "finishing" in 0.5 s when a JVM takes 15 s to start is a failed launch. A harness must fail loudly with the exit code.
- **Prefer the shipped environment** (the Docker image has a native `php`); local wrappers that proxy stdio are not valid instruments for `php2cpg`.
- **When a result contradicts a working baseline, suspect the instrument first.**
A plausible zero is a failed instrument until proven otherwise; classify it as `CONFIG_GAP` or `RUNTIME_MISMATCH`, not as `LOGIC_ERROR` in the code under test.
- Version-specific issue trackers or migration notes
Prefer:
- Official docs
- Official repos/issues
- Version-specific references
- Runtime-specific documentation
### 4. Classify the Root Cause
Use one category:
-`MISSING_DEPENDENCY`
-`RUNTIME_MISMATCH`
-`MODULE_FORMAT`
-`NATIVE_ABI`
-`CONFIG_GAP`
-`LOGIC_ERROR`
-`TASK_ORDERING_PROBLEM`
-`TASK_DECOMPOSITION_PROBLEM`
-`SPEC_CONFLICT`
-`EXTERNAL_DEPENDENCY`
### 5. Determine the Smallest Safe Next Action
Decide whether the issue can be fixed inside this repo by:
- Editing files
- Adjusting configuration
- Adding or correcting dependencies
- Restructuring code
Use `NEXT_ACTION: RETRY_TASK` when the issue is repo-fixable inside the current approved task plan.
### 6. Determine Whether the Task Plan Is Still Valid
Decide whether the current approved task plan is still safe to execute as written.
Prefer `NEXT_ACTION: STOP_FOR_HUMAN` when:
- A missing prerequisite task should exist before this one
- The current task is ordered incorrectly relative to unfinished work
- The current task boundary is wrong and should be split or merged
- The task is too large or ambiguous to fix safely inside the current implementation loop
Use `NEXT_ACTION: BLOCK_TASK` only when the current task should stop but the rest of the queue can still proceed safely.
Do not propose a brute-force code fix as a substitute for revising `tasks.md` or the approved plan.
## Critical Rule
Do not propose a multi-fix shotgun plan. Identify the root cause first, then produce the smallest plausible fix plan. If the true problem is a spec conflict or architecture problem, say so directly.
## Stop / Escalate
Use `NEXT_ACTION: STOP_FOR_HUMAN` when the blocker genuinely requires:
- Human product/requirements decision
- External credentials or inaccessible services
- Hardware or unavailable external systems
- Re-scoping due to spec/platform conflict
If the issue is fixable by repo changes inside the current task plan, do not escalate prematurely.
## Common Rationalizations
| Rationalization | Reality |
|---|---|
| “This probably just needs a quick patch” | Patch-first debugging creates rework. |
| “Let’s try a few fixes” | Multi-fix guessing hides root cause. |
| “The spec is probably wrong, I’ll adapt it” | Spec conflicts must be surfaced explicitly. |
| “The docs search is optional” | For runtime/dependency issues, docs and version issues often contain the shortest path to root cause. |
| “It ran clean: no errors, zero findings” | A tool that never read its input reports the same. Prove the read (one file, its size) before believing the zero. |
