---
name: resolve-investigate
description: Verify the reported path, cause, and historical intent before choosing a fix.
---

# 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.

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.
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.
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.

## PR review is the human decision boundary

Continue with the best-supported proposal within the authorized task. Ambiguous
design intent alone is not `needs_more_info` and does not require an interactive
question. Implement and validate the proposal; state assumptions and unresolved
tradeoffs in the PR and `fix_summary` so a maintainer can decide on concrete work.

If a material choice remains unresolved, use `partially_fixed` and list that
choice in `remaining_work`; do not claim `fixed` or approve the PR. In direct
author mode, open a draft with `--draft` and follow `resolve-publish`'s draft
exception. For an existing PR, leave the supported recommendation on that PR,
continue independent work, and respect branch ownership and trusted human
reviews; do not create a replacement just to resolve a policy disagreement.
For workflow-owned publication, prepare the proposal body and incomplete handoff
under the supplied publisher contract; never bypass it or invent a draft flag.
For `skip_push`, leave the proposal in the local commit and handoff.

Apply the same distinction to an unverified cause. If a proposed fix is supported
only by a substitute configuration or canned failure, describe it as a hypothesis,
use `partially_fixed`, and name the missing discriminator in `remaining_work`.
When a reliable reproduction cannot be established, use the existing
`needs_more_info` outcome. Passing tests that assume the cause do not justify
`fixed`.

Concrete blockers still apply: missing required inputs or credentials, unsafe
evidence, an unrecoverable verification environment, conflicting authoritative
requests, or work outside authorization. Name the blocker and complete independent
authorized work. Never weaken security controls, guess missing facts, silently
expand scope, or claim an unrun check passed to get a proposal through review.