AGENT SKILL

systematic-debugging

Use when a stubborn, flaky or cross-system MDE failure needs deep multi-step root-cause tracing; consult from errors when a focused reproduction and hypothesis do not isolate the cause.

License 许可
MIT
所属仓库
amoai-tech/mdeai
最近更新
2026-11-13
Stars
★ 2
Forks
1

01 前言 Front Matter

name
systematic-debugging
description
Use when a stubborn, flaky or cross-system MDE failure needs deep multi-step root-cause tracing; consult from errors when a focused reproduction and hypothesis do not isolate the cause.

02 资源文件 5

03 SKILL.md 正文

Systematic Debugging

Purpose

Find the root cause before changing behavior. Treat symptoms, reviewer guesses, and error messages as evidence to test, not fixes to apply blindly.

MDE ownership

Use this skill to diagnose. Once the failure is localized, use testing to lock it into a regression test and apply RED → GREEN → REFACTOR, the affected domain skill for implementation-specific rules, code-review to review the patch, and task-verifier to prove the task or PR is complete.

Workflow

  1. Reproduce the failure with the smallest reliable command, request, or user journey.
  2. Capture evidence: exact error, inputs, environment, branch/commit, affected boundary, and whether the failure is deterministic.
  3. Trace backward from the bad value or failed boundary until the first incorrect assumption/state transition is found.
  4. Form one hypothesis that explains the evidence.
  5. Run the smallest experiment that can falsify that hypothesis. Change one variable at a time.
  6. Write or update a regression test when the behavior is testable.
  7. Apply the smallest root-cause fix. Do not bundle unrelated cleanup.
  8. Re-run the reproduction + targeted tests + affected journey.
  9. Escalate the proof only if the risk warrants it: typecheck/lint/build, integration/E2E, live service, or production smoke.

Boundary debugging

For MDE integrations, record the value at each boundary instead of guessing which layer failed:

UI → Next.js route/server action → CopilotKit/AG-UI → Mastra → domain tool → Supabase/Stripe/Maps/Cloudinary → response/UI

At each boundary verify: input shape, auth/tenant context, IDs, timeout/cancellation, side effects, output shape, and error propagation.

Stop conditions

Stop proposing fixes when you cannot reproduce or localize the failure. Gather more evidence instead. Stop if the proposed patch only suppresses an error, retries indefinitely, weakens authorization, bypasses validation/HITL, or changes unrelated behavior.

Common traps

  • "This looks like X" without proving X.
  • Changing multiple variables before rerunning.
  • Treating a green unit test as proof of routing/integration behavior.
  • Fixing the caller when the source data is already wrong.
  • Adding fallback behavior that hides a broken authoritative path.
  • Rerunning flaky tests until green without explaining the flake.

References

Read only when needed:

04 同仓库更多 Skills