Debug

Debug: Prove The Cause

Use this skill when the task starts from a symptom.

Prefix your first response line with ⚗️ inline, not as its own paragraph.

Before the workflow, apply ../../shared-rules/personalization.md for explicit TasteD/TasteDistill invocations. Apply ../../shared-rules/runtime-hygiene.md when debugging uses helper scripts, browser checks, local servers, screenshots, traces, or other generated artifacts.

Outcome Contract

• Outcome: proven root cause, minimal fix or handoff, and verification evidence.
• Done when: every observed symptom fits the explanation and the fix is checked by a reproducible test or runtime observation.
• Evidence: repro steps, logs, traces, state, source paths, generated artifacts, tests, screenshots, and command output.

Workflow

1. List the observed symptoms.
2. Reproduce the issue or define the missing evidence.
3. Trace from symptom to source.
4. State a one-sentence root-cause hypothesis with evidence.
5. Make the smallest fix that addresses the cause.
6. Run the narrow regression check.
7. Search for the same bug shape if the root cause is reusable.

Coding Guardrails

For fixes, apply ../../shared-rules/coding-guardrails.md:

• Think before coding: do not edit until the root-cause hypothesis is specific and evidence-backed.
• Simplicity first: fix the cause directly; avoid broad rewrites, new abstractions, or speculative compatibility.
• Surgical changes: keep the patch to the failure path; search siblings only for the same bug shape.
• Goal-driven execution: prove the original symptom changed with a reproducible check.

CodeGraph

For root-cause analysis in a Git repository, ../../shared-rules/personalization.md should already have ensured the local CodeGraph index. When codegraph_* tools are available, prefer codegraph_trace for "how does X reach Y", codegraph_callers / codegraph_callees for one-hop flow, and codegraph_context for nearby implementation context. Read target files directly before editing.

Stop Rules

• Same symptom after a fix means the hypothesis failed.
• Do not stack patches without new evidence.
• Do not claim UI, native, or generated-artifact bugs are fixed from compile output alone.
• If the fix expands into a refactor, pause and name the scope change.

Output Shape

Root cause:
Fix:
Confirmed:
Tests:
Regression guard:
Remaining risk:

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sssstwee
• Source: sssstwee/tastedistill
• License: MIT
• Homepage: https://tastedistill.com/

Install and usage instructions live in the source repository linked above.