suboss87/FDEOps / skills/debug
debug
VerifiedInvestigate a failure, regression or incorrect result in an integration or application, even before it can be reproduced. Use for diagnosis and repair; follow incident authority for live mitigation.
| File | Kind | Size |
|---|---|---|
| .fde-generated.json | config | 1.1 KB |
| SKILL.md | skill md | 1.4 KB |
| agents/openai.yaml | config | 190 B |
| references/build.md | markdown | 4.7 KB |
| references/debug.md | markdown | 3.4 KB |
| references/eval-pack.md | markdown | 5.9 KB |
| references/integrate.md | markdown | 4.7 KB |
| references/qa.md | markdown | 2.6 KB |
| references/review.md | markdown | 5.3 KB |
| references/ship.md | markdown | 10.2 KB |
| references/task-context.md | markdown | 6.6 KB |
| references/verification.md | markdown | 5.5 KB |
references/debug.md
View on GitHub# debug - Find and repair the cause
A useful repair explains the customer's failure and shows why the changed path now behaves correctly.
**Use when:** a failure, regression, incident symptom, or misleading output needs investigation, whether or not it can yet be reproduced.
Follow [task context](task-context.md); permitted supplied evidence is enough without `.fde/`. During an incident, follow authorized containment procedures before diagnosis. Investigation authority does not authorize production writes.
## Establish what failed
Capture expected and observed behavior, the trigger or input, revision, environment, and last known working state. Keep useful errors and timestamps, without secrets or raw private data. Label unverified reports as reports.
Inspect the affected path, callers, relevant changes, and existing tests. Reproduce with the smallest representative case in a permitted environment when practical. If reproduction is unavailable, state the gap and use traces or other safe observations to distinguish causes. Keep investigating without promoting a hypothesis to a finding. Ask for the smallest permitted observation that distinguishes the remaining causes; an operator-run check or approved excerpt may be enough without granting the agent additional access.
## Test the explanation
Keep a short hypothesis list with a predicted observation and a discriminating check for each. Trace values and control flow across the actual boundary. Change one relevant variable at a time so the result tells you something.
After two unsuccessful repair cycles, reassess the evidence and approach. That is a signal to reconsider, not proof that a hypothesis is false. Continue useful investigation and identify any missing decision or access.
## Repair and verify the affected path
Fix the cause at the appropriate layer, preserving evidence of the original failure. Consider other callers, stale data, retries, concurrency, and permissions; leave unrelated cleanup out.
Name the hazard behind the mistake, not just the bad line, and search for other places where the same hazard exists. Report how many you found and which you fixed or left with an owner. Prefer a fix that makes the mistake impossible over one that warns about it, and a warning over a check that only detects it afterwards; say which you chose.
Add a regression check when it can meaningfully reproduce the bug. Show failure before and success after when practical, and disclose when the before-state could not be checked. Exercise the original journey and run affected adjacent and required checks using [verification](verification.md). Review the diff; use [review](review.md) for substantial or risky fixes.
*Fictional example:* Northstar's imports sometimes duplicate orders. A lost-response trace suggests a retry after a committed write. If staging cannot reproduce it, report the supported hypothesis and missing evidence rather than calling a longer timeout a root-cause fix.
## Completion
Return the cause and evidence, repair, original journey or reproducer result, adjacent checks, and unresolved uncertainty. A disappearing symptom without discriminating evidence establishes a mitigation, not a demonstrated root cause.
In an engagement, put the incident/fix receipt in the appropriate existing record under its write rules; standalone work can return it directly. Release or rollback needs the existing operational authority and [ship](ship.md) or recovery procedure.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |