사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/m-hosseinpour/agent-skills --skill systematic-debugging시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Systematic Debugging
Find the cause before choosing a permanent fix. A fix should explain the evidence, not merely make one symptom disappear. Scale the investigation to the uncertainty: an obvious defect may need only a small reproduction and one check, not a full ceremony.
Scope and Safety
- A request to explain a failure authorizes investigation, not edits, restarts, or deployment. Skip this workflow for failure-free code explanation or an already-verified correction unless new evidence contradicts it.
- Protect user work and diagnostic evidence. Do not reset state, delete artifacts, retry non-idempotent operations, or probe shared/production systems without authorization for that scope. Redact secrets and personal data; log only what distinguishes the hypotheses.
- During an incident, an authorized reversible mitigation can precede diagnosis. Preserve available evidence and check rollback/schema compatibility and persisted writes first. Report service restoration separately from root cause and permanent repair; do not block containment on a local reproduction.
Investigate
- Observe and preserve the failure. Read the relevant error and surrounding context, not just its final line. Record expected versus actual behavior, exact command or steps, inputs, version, and relevant environment. Establish the expectation from requirements, a contract, or a working case—not the suspect implementation. Reproduce safely before repair when possible. For intermittent or production-only failures, retain traces and conditions, bound observation by time or attempts, and say when reproduction is unavailable; absence on one run is not resolution.
- Locate the first divergence. Check relevant recent code, configuration, dependency, schema, and environment changes; timing alone does not prove causation. Follow the failing data/control path and compare a like-for-like working case. Across components, inspect inputs and outputs at the boundaries using a shared request/job identifier. When invalid data appears deep in execution, read root-cause-tracing. For test pollution, preserve order and runner lifecycle rather than assuming an isolated test reproduces it; that guide explains the limits of find-polluter.sh.
- Test a falsifiable hypothesis. State “I think X causes Y because Z; probe P should show Q, and result R would contradict it.” Choose the smallest safe probe that distinguishes plausible causes. Change one relevant variable at a time, keep useful output and exit status, and separate temporary experiments from a proposed repair. If the result contradicts the hypothesis, revise it; do not stack speculative patches.
- Repair the demonstrated cause. Keep the correction scoped and preserve valid behavior. Do not swallow errors, weaken assertions, raise timeouts, or add broad fallbacks just to hide the failure. For timing races, read condition-based-waiting before replacing a delay. For invalid input or a dangerous operation, read defense-in-depth to choose distinct safeguards—not validation at every internal layer. If fixes keep failing or exposing unrelated coupling, pause and reconsider the causal model or design with the user rather than forcing another patch.
- Verify the same behavior. Prefer the project's existing test setup; add a regression check there when practical. With no test framework, use exact manual steps or a disposable check rather than scaffolding one unasked. Show that the check catches the original failure, then repeat it after the fix and exercise relevant adjacent valid/error paths. For intermittent failures, report the observed attempts and conditions without claiming elimination. Use applicable existing checks; do not repair unrelated baseline failures in passing. A green suite alone does not verify the original symptom.
Stop when the evidence supports the cause and the scoped correction has been checked, or when a named evidence/authorization gap prevents progress. Do not reread evidence or repeat checks whose possible outcomes cannot change the decision.
Incorrect Output and Performance
No exception is required. For wrong reports or decisions, inspect recorded inputs, intermediate transformations, and outputs against an independently established expectation. Compare like cases and change one causal rule at a time; aggregate improvement must not hide a broken important case.
For performance, measure a baseline before changing code: same workload, environment, concurrency, and relevant cache state. Locate where time or resources are spent, then repeat that measurement after the change with correctness checks. A metric that does not improve is evidence to revisit the hypothesis or implementation, not by itself a reason to delete the concept. Name confounders and measurement limits.
Handoff
Keep it proportionate: symptom → evidence and cause (or current hypothesis) → correction or mitigation → checks and results → remaining limits. Distinguish observed facts from inference, implemented from verified, and restored service from a permanent fix. If blocked, name the next evidence or permission needed, not a guessed cause.
Maintainers revising this skill can use evaluation scenarios to check metadata selection and application separately. They are not part of ordinary debugging. The optional dependency-free waiting example is linked from the timing guide; prefer existing project waiters over copying it.