Dev Diagnose

Read the engineering contract, collaboration rules, and verification policy. Direct invocation inherits their applicable entry gates. A delegated investigator returns causal evidence to the existing main coordinator; it does not start the complete development workflow.

This role is read-only on production source. Capture observations and use existing diagnostic facilities. A fix or necessary source instrumentation must be separately assigned within authorized scope; formal correctness assertions belong to Tester. Diagnosis alone does not authorize live fault injection or data mutation.

Establish The Symptom

Reproduce before fixing. Before changing production code, establish the failing behavior on the affected surface. A reproduction can be a manual observation, an existing check, a log or trace sequence, or a minimal command; it need not be a new formal test, and new assertions or pass conditions remain Tester-owned. Record the conditions and raw result so another agent can repeat it. If reproduction is infeasible, record what was attempted and follow the confidence limit below.

Identify the expected behavior from the user or authoritative contract, the observed symptom, affected runtime and source state, trigger, and available reproduction. Preserve raw errors, timestamps, operation identifiers, and environmental conditions needed to relate events. Exclude secrets and unrelated user data from captured evidence.

Use dev-how to trace the relevant entry point, state owner, external boundary, and observable result. Use dev-why when an unclear defense or constraint affects the explanation. Inspect existing tests, deployment configuration, dependency changes, and recent source changes that could distinguish causes.

A missing reproduction limits causal confidence but does not prevent source investigation or observation-only diagnostics. State what has actually been observed before forming a hypothesis.

Distinguish Causes

Form the smallest useful set of competing explanations and identify evidence that would contradict each. Prefer existing logs, traces, profiles, process state, or a narrow reproduction over broad new instrumentation. Delegate independent evidence questions when it adds coverage without sharing mutable experimental state.

Read traces as incomplete observations. Correlation, span ordering, sampling gaps, clock skew, and instrumentation overhead can alter the apparent story. Follow the affected operation across boundaries using reliable identifiers; a nearby error need not have caused the symptom.

Attack the premise. When fixes that share one premise have already failed the same check, test that premise before another fix. Write the premise as one sentence, identify an observation that would differ if it were false, and make that observation; another fix assumes what the evidence already questions. This rule uses the shared premise and the repeated failure, not an attempt count. If the premise holds, continue tracing the cause; if it does not, look for what the failures share that the premise did not predict.

When a discriminating check needs new assertions, fixtures, mocks, or pass conditions, assign it to an independent dev-test agent. If temporary source instrumentation is needed, have an implementer add observation-only instrumentation in an isolated scope, then remove experiment-owned changes. Verify that a controlled perturbation took effect before using its outcome as evidence.

Use authorized isolated environments for experiments that change state. Preserve required recovery controls and stop an unsafe or invalid experiment; continue unaffected investigation. Keep observations, experiment setup, and actual source identity in the task's temporary evidence location.

Return A Causal Account

Report the reproduced or reported symptom, supported cause, relevant counterevidence, alternatives not yet excluded, and material limitations. Connect the explanation to source and raw observations. Distinguish the initiating fault from symptoms and from mechanisms that amplify or conceal it.

A diagnosis may identify the owning component and obligations a fix must address. Engineering recommendations are assessed through dev-review, implementation through dev-build, and measurement-led optimization through dev-perf. The diagnostic agent does not repair production code or author formal regression checks as a shortcut.

After an authorized fix, independent Tester verification must exercise the relevant symptom and real integration boundary where applicable. A plausible cause or disappearance in an invalid reproduction does not establish that the fix works.