Defect Diagnosis

Defect Diagnosis

Use this skill for the full defect discipline: diagnose the immediate failure, fix it with evidence, then decide whether root-cause prevention should update a product, architecture, development, testing, release, or tooling skill.

Non-Negotiable Rules

• Do not skip the problem because another path appears to work.
• Do not delete, comment out, or weaken a failing test just to make the suite pass.
• Do not call a workaround the fix unless the owner explicitly accepts the tradeoff and residual risk is recorded.
• Do not start broad refactoring while the cause is unknown. Isolate and fix first; refactor after the behavior is understood.
• Do not stop at "this line was wrong" when the defect reveals a missing contract, guardrail, test, review check, or skill rule.
• Do not state or act on a root-cause verdict — even as a confident aside — before you have read the failing owner's own evidence with your own eyes (assertion diff for a test, stack/exception for a crash, trace/log slice for a production symptom, source only when it is itself the failing artifact). Until then, label every cause as a hypothesis and name the evidence that would confirm or reject it. This applies to your OWN analysis, not only to LLM-proposed causes. Mitigation is exempt: you may roll back, flag-off, or shed traffic from symptoms while cause stays marked unknown — what is forbidden is choosing or applying a fix as though a cause is proven.

Phase A: Diagnose

1. Reproduce.

• Record exact steps, inputs, environment, command, config, and observed failure.
• Prefer a failing test, trace, payload, or smallest runnable reproduction.
• If intermittent, record frequency, timing, data shape, and resource conditions.
• Before declaring a bug non-reproducible — or an environment / service / tool / dataset needed to reproduce it "unavailable" or "blocked" — run the normal remediation for that layer first. Start the service / emulator / container / dependency and wait for readiness, run the repo setup or fixture/seed script, restart the client daemon, provision or refresh the test data, or try a different reproduction strategy (smaller or adversarial input, a different transport/endpoint, added tracing, or an engineered-interleaving / race-detector harness for a concurrency bug). Only record can't-reproduce / unavailable / blocked after the bounded remediation for that layer fails, with the command evidence, the residual risk, and the next concrete unblock action. A confident "I can't reproduce it" or "the env is down" with no remediation attempt is not a closed defect — it is pending.
• This is not an escape hatch to never close or escalate. Remediation attempts are bounded and subject to the same frame-change / escalation discipline as hypotheses below (Frame-change-or-escalate, Escalation does not close the defect): after repeated failed bounded attempts, stop inventing new "different" strategies, escalate with a handoff packet, and keep the defect open under an owner — do not sit on an endless pending.
• Safety preflight for any mutating remediation (setup / fixture / seed / data-refresh / daemon-restart, or docker compose up-style stack start): first prove the target endpoint, credential, and namespace are synthetic and disposable — never a live/prod/shared DB, API, token, or environment — and disable or isolate any side-effecting consumers, webhooks, or scheduled jobs the start would wake (they can process real queued events or reconnect to shared staging). If you cannot confirm the target is safe/scratch, the remediation is itself blocked — do not run destructive setup/refresh to chase a repro.

1. Isolate.

• Narrow by layer, recent change, dependency, data shape, permission, timing, or environment.
• Use minimal reproduction, binary search, feature flags, dependency substitution, or generated-file drift checks when useful.
• When the failure has no useful binary-search axis (no orderable/partitionable commit, input, dependency version, config/env, or dataset with a reliable good/bad predicate), compare against a known-working analog — a confirmed-passing sibling test, the same operation on another service/endpoint, or a last-good build/env/config — and enumerate every difference between the working and broken cases, however small; do not pre-dismiss one as "that can't matter". Verify the analog is genuinely passing and contract-comparable first (a superficially similar but different-contract analog misleads). Do this only after reading the failing owner's own evidence (per the evidence-first Non-Negotiable above; for a failing test, the assertion-first rule below), and treat each enumerated difference as a hypothesis to verify (Phase A.3), not a proven cause.
• git bisect is the default binary-search tool when the failure is a regression with a known-good and known-bad commit.
• Per git-scm.com/docs/git-bisect: git bisect start && git bisect bad && git bisect good && git bisect run automates the search.
• Script-exit-code contract per git-scm.com/docs/git-bisect: 0 = commit is good; any non-zero exit in 1..127 except 125 = commit is bad; 125 = commit is untestable (skip).
• The make || exit 125 idiom belongs to the build / setup phase of the script — emit 125 ONLY when the commit cannot even be built/prepared, not when the actual test fails (test failure should propagate as exit 1 so bisect counts it as bad).
• For a regression caused inside a merge, git bisect --first-parent follows mainline only so the search doesn't dive into intermediate feature-branch commits that don't matter.
• The script must be deterministic — flaky-reproduction-rate product-rd-workflow.
• Go backend architecture issue -> go-microservice-architecture.
• Go backend implementation, testing, codegen, DB, Redis, MQ, or protobuf issue -> go-microservice-dev references.
• Python backend, AI-service host, worker, SDK/package, or batch-job architecture issue -> python-service-architecture.
• Python implementation, pytest, packaging, schema, ORM/migration, Redis, queue, async, or service-wiring issue -> python-service-dev references.
• LLM, inference, RAG, prompt, model-routing, streaming, fallback, evaluation, replay, shadow, token-cost, or agent-runtime/tool-call issue -> llm-inference-integration.
• Mobile app issue involving Flutter, Android, iOS, navigation, state, platform bridge, device capability, build/release, crash, accessibility, or performance -> app-cross-platform-dev.
• Mini-program issue involving WeChat/Alipay/Douyin/Baidu page routing, host-platform APIs, developer tools, review submission, release, real-device preview, or platform capability -> miniapp-product-dev.
• React web issue involving components, routing, browser state, frontend API integration, forms, build/deploy, accessibility, or browser performance -> web-react-dev.
• Terminal, CLI, or TUI issue involving ANSI rendering, text layout, PTY behavior, keyboard/mouse/paste/focus input, selection/copy, scrollback, resize, color fallback, or terminal cleanup -> terminal-cli-dev.
• Tests, CI, fixture, mock, E2E, device/browser, or verification-layer miss -> testing-strategy.
• Regression test case needs to be written and tracked in Feishu Bitable after a bug is fixed -> test-artifact-management.
• Hands-on diagnosis method issue -> defect-diagnosis.
• UI/product interaction issue -> product-ui-ux-design first when UX is unclear, then app-cross-platform-dev, miniapp-product-dev, web-react-dev, or terminal-cli-dev for implementation.
• One-off business/domain issue -> do not convert to a generic skill rule.

Reference Loading

• For diagnosis lenses and evidence templates, read references/diagnosis-playbook.md.
• For prevention types and skill update rules, read references/prevention-routing.md.

Source & license

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

• Author: ccoalm
• Source: ccoalm/ccl-skills
• License: Apache-2.0

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