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
- 参考文档evals/evals.json605 B
- 参考文档references/condition-based-waiting.md3.4 KB
- 参考文档references/defense-in-depth.md3.6 KB
- 参考文档references/root-cause-tracing.md5.2 KB
- 脚本scripts/find-polluter.sh1.9 KB
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
- Reproduce the failure with the smallest reliable command, request, or user journey.
- Capture evidence: exact error, inputs, environment, branch/commit, affected boundary, and whether the failure is deterministic.
- Trace backward from the bad value or failed boundary until the first incorrect assumption/state transition is found.
- Form one hypothesis that explains the evidence.
- Run the smallest experiment that can falsify that hypothesis. Change one variable at a time.
- Write or update a regression test when the behavior is testable.
- Apply the smallest root-cause fix. Do not bundle unrelated cleanup.
- Re-run the reproduction + targeted tests + affected journey.
- 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:
references/root-cause-tracing.md— trace bad values backward.references/condition-based-waiting.md— timing/race failures.references/defense-in-depth.md— validation across trust boundaries.scripts/find-polluter.sh— deterministic test-pollution helper.
04 同仓库更多 Skills
mde-pr-review-supabase
Use when reviewing MDE Supabase SQL, Auth and RLS changes in a pull request.
mde-pr-review-stripe
Use when reviewing MDE Stripe payments and webhooks changes in a pull request.
mde-pr-review-nextjs
Use when reviewing MDE Next.js App Router changes in a pull request.
mde-pr-review-mastra
Use when reviewing MDE Mastra agent, tool and workflow changes in a pull request.
mde-pr-review-maps
Use when reviewing MDE Google Maps and Places changes in a pull request.
mde-pr-review-copilotkit
Use when reviewing MDE CopilotKit and AG-UI changes in a pull request.