Skip to content

suboss87/FDEOps / skills/debug

Investigate 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.

FileKindSize
.fde-generated.jsonconfig1.1 KB
SKILL.mdskill md1.4 KB
agents/openai.yamlconfig190 B
references/build.mdmarkdown4.7 KB
references/debug.mdmarkdown3.4 KB
references/eval-pack.mdmarkdown5.9 KB
references/integrate.mdmarkdown4.7 KB
references/qa.mdmarkdown2.6 KB
references/review.mdmarkdown5.3 KB
references/ship.mdmarkdown10.2 KB
references/task-context.mdmarkdown6.6 KB
references/verification.mdmarkdown5.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.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 318kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 318kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 318kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall