Defect Diagnosis

Defect Diagnosis

Diagnose and fix from evidence; route prevention to product, architecture, development, testing, release or tooling.

• Code/test changes require self-checks; invoke code-review automatically before completion.

Non-Negotiable Rules

• Required failures, including inherited debt: diagnose, safely repair and rerun that check before handoff. Read repair-before-handoff. Working alternatives never close defects.
• 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.
   • A production symptom that cannot be re-triggered in place is not blocked on reproduction: diagnose from the failing run's own telemetry (step 4). Race or deadlock evidence may stay suggestive, but the cause still owes a falsifying probe before any fix.
   • 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.

2. 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 <bad-sha> && git bisect good <good-sha> && git bisect run <script> 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 — emit 125 ONLY when the commit cannot be built/prepared, not when the test fails (test failure propagates as exit 1 so bisect counts it as bad).
     • For a regression caused inside a merge, git bisect --first-parent follows mainline only, skipping intermediate feature-branch commits.
     • The script must be deterministic — a flaky reproduction makes bisect converge on the wrong commit; fix the reproduction script first (loop N times, assert ≥M failures, then exit 1) OR switch from bisect to logging/tracing diagnosis.
     • Routing: stack-specific bisect-script idioms (pytest -x / go test -run / npm test --bail) belong in stack dev skills; this skill owns the workflow + exit-code contract.
     • Do not bisect the whole history when evidence confines the cause to known paths: git bisect start <bad> <good>... -- <paths> narrows the search by path and by every known-good commit (per git-scm.com/docs/git-bisect); if the restricted search finds no reproducing commit, rerun over the full range — dependency, generator, build-config, or schema changes can sit outside those paths. git bisect log / replay hand off a half-finished search instead of restarting it.
   • For build or release-tool failures, shrink the failing command to the smallest owning tool before editing application code. Examples include moving from app build to native build settings, compiler, asset/storyboard compiler, package resolver, code generator, or emulator/simulator runtime discovery.
   • A multi-component failure (client → service → store) must be localized to one boundary in a single instrumented run when the chain can be re-run safely and every boundary is reachable, before hypotheses fan out: log allowlisted, redacted metadata at each boundary (ids, sizes, status codes, field presence, config keys received), never raw bodies, headers, secrets, PII, or env/config values (inspect those only ephemerally); run once, find the first wrong boundary, then hypothesize inside that component only. When the chain is historical, partially observable, or unsafe to instrument, use the telemetry path (step 4), partial boundary evidence, or layer narrowing and record the visibility gap.
   • A wrong value must be traced upstream to the first point where it became wrong (the correct→faulty transition); the fix lands there when that point is owned and changeable (validation at the observation point is then defence in depth, never the fix); when it sits in an external or unchangeable producer, record the upstream cause and enforce the contract at the nearest owned boundary.
   • A test that passes alone and fails in the suite must be bisected over the tests that run before it — only for a failure that reproduces on every run under a fixed serial order (parallel or intermittent failures keep the failing schedule and validate each kept or dropped subset over repeated runs per the flaky rule, or route to concurrency diagnosis): halve the preceding set in order and keep a failing half; when neither half fails alone, remove one chunk at a time and keep the reduced set whenever the failure persists without that chunk, then halve the chunk size and repeat until every remaining chunk is needed (a minimal ordered polluting subsequence) or the shared fixture/state is found; the same reduction isolates a failing input, config, or dataset when no commit range exists (moves in references/diagnosis-playbook.md).
   • Identify whether the failure is in product logic, contract mapping, persistence, cache, async processing, dependency behavior, runtime config, release state, or test setup.
   • If the failure appears only in tests or CI, classify the test evidence before changing code: deterministic assertion, fixed external data, live infrastructure, random/log-only behavior, long sleep, allow-failure gate, generated/vendor test, or deploy/build-only pipeline.
   • A red CI pipeline/job is not by itself a code/dependency defect — read the failing job's own trace (not the red/green summary) and classify the cause before touching code. Refining the classes above into why-CI-is-red-but-code-may-be-fine: (a) trigger-variant artifact — when the same job runs under more than one trigger-scoped config (branch/push vs merge-request vs manual/scheduled), the trigger can resolve different default variables or a different checked-out ref, so a red on a non-gating trigger may be benign — but conclude that ONLY after confirming the same failing check ran and is green on the gating path (a gating pipeline that is overall green yet never runs the failing check does not clear it; if that check's coverage is unique to the non-gating trigger — e.g. a scheduled/manual-only suite — treat it as genuine (d), not a variant artifact); (b) retriable infra flake — e.g. a shared-runner lock collision: confirm per the flaky rule below (rerun N times + record the ratio; a 100%-reproducible red is deterministic, not a flake), and still read the red run's trace for the collision signature, since one green rerun cannot separate an infra flake from a genuine intermittent code bug; (c) deterministic non-code infra fault — toolchain/runner-image drift, stale cache/vendored artifact, credential/quota expiry: reproduces identically (NOT a flake) AND must be shown code-independent before disowning — confirm the same failure reproduces on a known-good baseline (parent/last-good commit, or a build without the change) under the same runner/toolchain; if the red appears only with the change it is (d) however much it resembles drift → route to platform/infra only after that baseline check, then do not attribute to code; (d) genuine code/dependency failure. (Single-variant repos skip the (a) check; the trace-first and cause-classification still apply.)
   • For a failing test, read the actual assertion error (Expected/Actual) and the failing test body FIRST — before diagnosing flakiness, concurrency, shared state, mock setup, or external-dependency causes. A passing/failing count, a REQUEST POST-style debug log line, or "passes in isolation, fails in suite" is a symptom, not the assertion evidence; naming a cause from those alone is the exact failure this skill exists to prevent. If the test is suspected flaky, rerun N times and record the pass/fail ratio before calling it flaky (100% reproducible failure is deterministic, not flaky), and confirm the test's network/dependency boundary by reading its setup (e.g. whether it is already mocked) rather than inferring from logs.

3. Hypothesize.

   • Write concrete causes that can be proven or rejected.
   • For each hypothesis, define the expected observation if it is true and the observation that would falsify it — then go get the falsifying one first. A search hit, a log line, or a plausible implementation detail proves the text EXISTS, not that it RAN on the path that failed: run it on the failing path for an observation only THAT cause predicts — reachability rules out non-execution and nothing else, so watching the suspected code execute clears no cause — or build a paired control differing in exactly ONE variable (every precondition of the predicate under test enumerated, both arms equal on all the others). Until an operation that could have falsified the cause has been run and did not, it stays a hypothesis — it must not become the basis of a fix, and it must not enter a commit/MR body, a durable note, or a report as the cause. Withdrawing a landed wrong cause costs far more than testing it. The probe itself stays inside the same boundaries the extraction workflow's falsification rule names — existing sandbox and permission limits, non-destructive, synthetic targets, no production or live credentials, no permission-boundary bypass; where no safe probe exists the cause simply stays a hypothesis and must never be upgraded by running an unsafe one.
   • Probe order must be decided by discriminating power, then cost, then risk — never by which hypothesis came to mind first: safety is a filter, not a rank — reject probes outside the safety boundary first, rank the rest by alternatives ruled out per unit of cost, and break ties by likelihood, then residual risk. An active probe that changes the system (more resources, verbose logging, shifted traffic) can change the next observation: record each such change and revert it before the next probe.
   • The hypothesis log must be kept inside the loop, not written at closeout: each hypothesis with its prediction, falsifier, probe (cost, side effects), and result. Check a new hypothesis against the recorded observations before it costs a probe; a rejected class is never re-tested under a new name; the three-strike count below reads from this log.

4. Instrument.

   • Add targeted logs, assertions, traces, metrics, local probes, or debugger breakpoints.
   • Keep instrumentation narrow. Remove or downgrade temporary noise before finishing.
   • A hypothesis about a runtime value or state must be settled by observing it — breakpoint, print, assertion, or a trace attribute at the exact point — not by inferring it from the code.
   • Observability-driven RCA: when the failure is observable in production telemetry, start from the bad metric/alert and walk back through traces, not from the application code reading bottom-up.
     • Per opentelemetry.io/docs/specs/otel/metrics/data-model/ and the OTel exemplars spec, modern observability platforms (OpenTelemetry SDK + Prometheus + Tempo / Jaeger / Grafana / similar) link metrics to a sample of traces via exemplars — a metric data point can carry the trace-id of a request that produced it, so a latency spike leads to a representative slow trace.
     • The cardinality discipline rule (never put trace-id / request-id as a metric label) makes exemplars necessary — they preserve high-cardinality drill-down without exploding the metric.
     • Workflow: alert fires → open dashboard → pick an exemplar trace from the spike → read the span tree (downstream service called, timing, attributes) → jump from span to logs via shared trace-id → form hypothesis.
     • Reading application code without first checking the trace is the most common time-sink in production-symptom diagnosis.
     • The trace-shipping pipeline / dashboard / alert routing belong to platform-observability; this skill owns the diagnoser-facing workflow.
   • AI-assisted diagnosis (Claude Code / Cursor / Copilot / similar) is a default-on hypothesis generator, NOT a default-on root-cause verdict.
     • The pattern that works: paste the sanitized error evidence to the assistant, ask for a ranked hypothesis list with evidence-collection commands, then YOU verify each candidate by running them and reading the actual output.
     • The pattern that breaks production: accept a confident LLM-named root cause as the answer and ship a fix without running the verification commands — LLMs routinely hallucinate plausible root causes from partial evidence, especially when the stack trace matches a familiar bug class but the code path differs.
     • Required discipline when AI-assisting diagnosis: (a) record the prompt + assistant output as part of the diagnosis evidence (so reviewers can spot a hallucinated cause), (b) whoever ran the verification commands and read their output owns the final cause verdict and the regression test — a cause proposed by any model, including your own analysis, stays a hypothesis until then, (c) never let the assistant apply a fix without first writing or strengthening a regression test that fails before the fix and passes after — the AI's "I fixed it" claim is not verification, the failing-then-passing test is, (d) sanitize before the error leaves the trust boundary — before pasting a stack trace / log / failing-test output / query / trace JSON to an external assistant or searching it on the public web, strip internal hostnames, IPs, internal URLs/paths, raw SQL and query bodies, customer data / PII, secrets / tokens, env values, and proprietary identifiers; send only the generic error class + framework/version (search the error category, not the raw message). A self-hosted / in-VPC assistant under a no-retention, no-training contract may receive more diagnostic context, but secrets / tokens, customer data / PII, request/response bodies, headers, env values, and credential-bearing variable values are minimized regardless of channel; if an error cannot be safely sanitized, do not send it externally — diagnose from local evidence. The prompt/assistant-output you record under (a) is then subject to the same evidence-sanitization rule as any other persisted evidence (Phase B "Record evidence"), so the recording step does not re-leak what this strip removed.
     • Safe-to-delegate work: log/trace summarization, repro-script drafting, hypothesis fan-out, refactoring-after-fix.
     • Not-safe-to-delegate: the root-cause verdict, the fix application without test, the prevention routing decision.

5. Verify cause.

   • Prove the cause with evidence.
   • A diagnosis licenses a fix only when it explains both causality and incorrectness: how the defect produced this failure on the failing path, and why that code, data, or config is wrong against its contract — so the fix covers related failures. A change that makes the failure disappear without the second half is a symptom patch; a genuine defect that cannot be linked to this failure is a different bug — record it, never ship it as this cause.
   • Report query/lookup evidence by cardinality: a data query, log search, or identity resolution that returns 0, 1, or N matches reports each of those outcomes distinctly — never silently take the first row of N, and never treat 0 rows as "no evidence collected" (an empty result over a named scope IS evidence: record which scopes matched and which were empty).
   • When the cause is environment/toolchain state, prove it from the tool that owns that state, not only from the high-level wrapper. A wrapper failure is a symptom until the underlying compiler, generator, runtime registry, dependency resolver, or platform destination evidence explains it.
   • If disproven, return to hypotheses instead of guessing.
   • Separate symptom, immediate cause, contributing factors, and prevention.

Convergence Control And Escalation

The hypothesize → instrument → verify loop must not run forever, and escalation must not drop the discipline. Apply these signals:

• Frame-change-or-escalate (three-strike). Count evidence-backed rejected hypotheses within the same frame (same layer, evidence source, and reproduction). After about three, pause for reassessment before adding another from that frame. Continue in the same frame only when the next hypothesis is materially new, has a distinct falsifier, and is backed by new or deeper evidence that can distinguish it from the rejected class; otherwise record a material frame change (new reproduction, layer, independent evidence source, owning invariant, or a tool that exposes new evidence rather than re-reading the same signal) or escalate. Rephrasing the same hypothesis class, swapping tools that observe the same evidence, or renaming owners does not reset the count. This is a reassessment signal, not a numeric cap on valid evidence-driven hypotheses.
• Escalation does not close the defect. Handoff, "instrument and wait", or re-scope leaves the defect OPEN; it never waives the verified cause, fresh verification, or regression evidence before any fix is accepted. A handoff packet carries: symptom, reproduction, rejected hypotheses with evidence, current mitigation, next owner, and the open verification/regression obligations.
• "Instrument and wait" needs a severity gate. It is acceptable only with an explicit classification: no plausible user, data-integrity, security, compliance, or SLA impact; mitigation is not applicable or would be riskier; an owner accepts observe-only; and an alert + timeout + owner are recorded. Unknown or latent-uncertain severity defaults to mitigate/escalate, not wait. Emergency mitigation (roll back, flag off, shed traffic) stays available immediately while the cause is unknown, per the Non-Negotiable mitigation rule.
• Wrong-layer smell. If each fix makes a new problem appear elsewhere, you are patching symptoms at the wrong layer or abstraction — stop patching and re-trace to the layer that owns the broken invariant. A fix proposed before its cause is verified by evidence (per Phase A) is a guess, not a fix.
• Recurring-area smell. A defect recurring in the same module or files across separate fixes is a trigger to investigate whether the cause is structural — not a verdict that it is. Mitigate or land the minimal verified fix first, then route prevention to the owning skill via Prevention Routing (architecture only when the cause is genuinely structural — service boundary, source-of-truth, contract, auth, runtime/release, or data ownership; otherwise dev/testing/product/tooling per the table).

Phase B: Fix And Verify

1. Fix minimally.

   • Address the proven cause with the smallest correct change.
   • Preserve contracts unless the task explicitly requires a contract change.
   • If the minimal fix would change a shared deterministic gate/verifier (workspace verifier, conformance/contract-coverage script, status-source validator, CI harness, continuation-state checker) or shared/cross-repo contract/status/version/release/compatibility semantics — whether in a named surface or in code, generated artifacts, config, or scripts — stop before editing and route the fix through product-rd-workflow's shared-gate classification (its Enforce quality gates shared deterministic gate/verifier rule: artifact classification + persistent repo-local plan + feature-risk-router shared-gate route). Diagnosis still owns the verified cause and regression test; that handoff governs only how the fix lands.
   • Keep unrelated cleanup separate.

2. Add regression evidence.

   • Add or update a test that would have caught the defect when feasible.
   • Prefer a test that fails before the fix and passes after the fix.
   • Do not treat a random, log-only, sleep-heavy, or live-data script as sufficient regression evidence unless it is explicitly marked as a manual/integration probe and paired with a deterministic check.
   • Run narrow verification first, then broader affected tests based on risk.

3. Record evidence.

   • Do not claim the defect is fixed until fresh verification has been run and read.
   • Symptom and reproduction.
   • Proven cause and rejected hypotheses.
   • Fix summary.
   • Verification command/result.
   • Regression test or why it was not feasible.
   • Sanitize evidence that is persisted or shared. Any diagnosis evidence copied to a ticket, MR, repo-local file, or shared doc — repro inputs, env/config, commands, request/response headers and bodies, logs, verification output, and AI-assist transcripts (per Phase A item (d)) — is minimized and redacted first of the same categories Phase A item (d) strips before an external send, plus config values and any credential-bearing value. Raw unredacted repro artifacts live only in an access-controlled incident store with a retention rule, referenced by link, never pasted into shared diagnosis evidence; recording the failure must not become the leak the live system avoided.

Phase C: Root Cause And Prevention

Run 5 Whys after the immediate defect is understood:

• Why did the observable failure happen?
• Why did that code/data/config condition exist?
• Why did tests, review, monitoring, or runtime checks miss it?
• Why was the contract, workflow, or assumption unclear?
• What durable prevention changes future behavior?

Stop when the answer points to a reusable prevention mechanism, not when it only names the broken code. Reject disguised non-causes — "developer was careless / didn't follow the rule / will be more careful next time" name the human's diligence, not the mechanism. When a control that was expected to catch this (a test/check/review/CI/lint/type/contract/runbook) existed but did not fire, and the failure would recur for others, that is not the root cause — the next why is "why did no trigger/gate make that control fire", and the prevention is the mechanism that fires next time (a failing-first regression test, CI check, lint, type, contract, or review-checklist item). A genuine one-off low-risk human slip that an existing check already caught may stop at "no shared change needed" — but never at "try harder next time".

The 5 Whys lineage is generic industrial-quality practice (popularized by Toyota Production System manufacturing-quality work). For incident-class defects (production outage, data corruption, security event), pair 5 Whys with two additional named lenses commonly applied in modern SRE practice (repeated/recurring defects are routed by the complexity rule below, which fires the widen lens regardless of user-visibility):

• Blameless postmortem (per Google SRE Book chapter on Postmortem Culture, sre.google/sre-book/postmortem-culture/): write the incident review assuming everyone involved acted with the right intent given the information they had at the time. The point is to extract systemic prevention (gates, alerts, contracts, runbooks) rather than to assign individual fault. Templates capture timeline, impact, contributing causes, action items with owners + due dates, and what worked/didn't in response. Where blame prevails, people stop bringing issues to light (per the same SRE chapter), so repeating failure classes stay hidden.
• Swiss Cheese model (James Reason, safety/accident-causation literature): every defense layer (test, code review, monitoring, alerting, runbook, on-call response) has holes; an incident reaches production when holes line up. The action items from a postmortem should close the relevant hole at MULTIPLE layers, not just the one closest to the bug — adding a unit test alone leaves the alert + the runbook + the on-call playbook still empty. List which layers had a hole this time and which closures the team commits to.

Scale Phase C depth to defect complexity, not only to user-visible incident status:

• Simple deterministic non-incident — one local cause plus one regression/control fully explains the defect (test caught it, dev fixed it, no user impact): the linear 5 Whys above is sufficient.
• Complex defect — intermittent/flaky/racy, multi-component, repeated/recurring, required a Phase-A frame change (the three-strike signal), spans more than one Diagnosis Playbook lens category (e.g. a contract + timing + cache interaction) or the test layer is itself causal, or more than one expected control failed: widen before deepening, even with no user-visible impact. Enumerate the contributing factors across the Diagnosis Playbook lenses (contract / state / time / dependency / runtime / test / human-agent workflow), separate the immediate cause from the enabling/latent conditions (applying the blameless / local-rationality framing — assume right intent given the information available at the time; that framing is the lens and applies here, separate from the formal ceremony below), counterfactually rank the primary cause against the failed secondary controls (close each failed layer per Swiss Cheese, not only the one nearest the bug), then route prevention for each. A single straight 5-Why chain that stops at one cause is the documented failure mode here — a complex defect with no branches means you stopped early. Record the complexity verdict (simple / complex + which trigger fired) in the diagnosis evidence, so the widen path cannot be silently skipped on a bug that warranted it.

The widen + multi-layer (Swiss Cheese) lens fires on complexity above, not only on visible impact — so a repeated regression (a named complexity trigger above) is widened even when caught in CI with no user impact. Reserve the formal blameless-postmortem ceremony (timeline / impact / action-items with owners + due dates) for incidents with user-visible or business-visible impact, and for the defect class below.

• A defect that escaped into a merged change, a release, or a user must get a written postmortem when all three hold — subtle, systemic, costly to rediscover. Subtle: the mechanism is non-obvious and a careful engineer would re-derive it the hard way. Systemic: it escaped through a gap in tests, tooling, or conventions, not a one-off typo. Costly: it burned real debugging time and would burn it again. Below all three and with no user-visible or business-visible impact, the formal write-up is not required — but this exempts only the ceremony: the simple-vs-complex analysis-depth rules above still apply in full, so a repeated, flaky, multi-component, or frame-changing defect still gets the widened multi-layer analysis even when nothing is written up. An impacted incident keeps the unconditional ceremony regardless of how obvious its mechanism was — "the mechanism was just a typo" is never an exemption once users or the business saw it. The bar exists only to stop ceremony over no-impact trivia: writing one up for an unmerged local slip trains people to skip postmortems, while skipping one for an incident that reached users trains them to hide impact.
• The write-up must open with a thirty-second executive summary — what broke, the root cause in plain terms, why it escaped, the durable lesson — before timeline and detail, and it must link the guardrails it produced (tests, rules, runbooks, decision records) so a reader can check that the class now fails loudly. A postmortem is not a decision record: it looks backward at a failure and its escaped defenses, while the design decision it triggers is written where decisions live.

Prevention Routing

• Product workflow issue -> 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.
• Node.js implementation, runtime/module/type path, package-manager or lockfile, async lifecycle, stream, worker, outbound-client, or node:test/runner issue -> nodejs-service-dev references. A Node.js architecture or service-boundary issue has no architecture sibling by decision and must not be filed under a sibling stack's architecture skill -> product-rd-workflow's architecture gate plus the relevant platform-* owner.
• 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.