resolve-investigate

Establish the cause and intended behavior

Use this in every mode before choosing assertions or changing code. Keep the investigation proportional to the reported problem; reuse evidence that still matches the checkout. Record concise findings in the existing root_cause, fix_summary, and test_audit fields, not a separate report.

Before editing product code, complete the applicable checks below and record their commands and observations. A plan to check later is not evidence. When a check cannot run, name the concrete blocker and keep the cause unresolved.

1. Reconstruct the report. Read the report and relevant discussion, including linked evidence. Separate reported facts, observations, and hypotheses. Pin the entry point, build, harness, authentication mode/profile, configuration, and starting state. Mark unknowns; do not silently swap an OAuth user login for a service principal or PAT because they produce similar errors.
2. Distinguish symptom from cause. Trace the actual path from trigger to failure. Treat the reporter's diagnosis, Repro leads, and proposed fixes as hypotheses. Check the strongest competing explanation suggested by code, logs, or history with an observation or focused test that distinguishes it. Explain why the selected cause accounts for the reported configuration and symptom. If no credible alternative emerges, say so briefly; do not invent one or implement a plausible generic fix without evidence. Exercise the reported configuration through the implementation being diagnosed. Controlled external services, clocks, and credentials are useful substitutes; replacing the suspected component with canned results assumes the cause instead of testing it. For example, a fake token factory proves how its caller handles those tokens, not how the configured credential provider behaves. Record which parts actually ran and which were substituted. A fail-before/pass-after test of that substitute does not confirm the incident. For credential-lifetime or recovery hypotheses, first establish a working control through the reported credential-selection code and SDK. When external auth services are unavailable or sanitized, substitute only boundaries this provider uses, with bounded local services and fake credentials. Static credentials need no invented issuance or refresh service. Keep application token resolution and the installed SDK intact. Record which provider actually returns the credential, including any fallback, using its runtime type or call trace. Starting SDK configuration or discovery does not prove SDK-provider success. Bound discovery and subprocess calls with timeouts. Get credential resolution working on its own before adding the host/reconnect loop. If initialization hangs, inspect the blocking stack. If it identifies external configuration metadata/discovery calls, provide controlled responses and record whether the control reached them. Preserve other concrete blockers. Load an isolated reported profile and use its credential at the caller's transport boundary. Keep the same application credential object while exercising the suspected expiry or rejection; record whether it refreshes or recovers before proposing a cache reset. Mocking that object or its factory cannot satisfy this check. Retain the controlled boundaries and remaining incident uncertainty. If you change this path, rerun the same configured control and discriminator on the candidate. A new mock-only regression test cannot verify recovery through the implementation you diagnosed; limit the fix claim accordingly.
3. Find the design intent. Read nearby tests and documentation, targeted git log -S/git blame, and relevant commit/PR discussion. Cite the source and revision; distinguish documented rationale from inference and note unavailable history. A fallback, fail-open path, default, or restriction may be deliberate. Do not reverse it just to satisfy a repro assertion. Check whether later decisions supersede the original rationale. Follow the reported path to any shared registry, default, or policy definition that governs the behavior, then read its rationale, relevant callers, and tests. Do not infer the full contract from one local fallback. Even when the local fallback is explicit, follow the phase or operation type to its declaration and inspect other consumers for a shared table or default controlling error behavior. Cite that declaration, or a bounded search if absent. Follow imported policy symbols to their defining files. Search for the declaration and other consumers; a filename in search output or a symbol in a caller is not a definition read. Record the controlling symbol/value, definition path, historical rationale, and pinning test in test_audit. If there is no shared definition, record the search that established that.
4. Choose and explain. Preserve intended behavior when correcting the defect. For a necessary policy change, explain the old behavior, the proposed behavior, affected users/configurations, alternatives, and supporting evidence. Existing tests are evidence of intent, not unquestionable policy. Repair unsupported repro expectations with the original evidence preserved; label tests of a proposed policy as such, not proof the old policy was a bug. Before adding a retry, trace the retried operation's state writes and external effects. If there are none, record the inspected read-only path. Otherwise, test failure after an effect commits but before success reaches the caller; retry counts alone do not show safety. Preserve existing behavior when the proposed retry lacks that evidence, and record the unsupported proposal as remaining work.