---
name: investigate-bug
description: Investigate a reported defect and return supported diagnosis, reproduction and bounded fix/check recommendations without requiring a ticket. Use for diagnosis requests and bounded bug-evidence handoffs, including explicit ticket or fix compounds; investigation itself stops before repair.
---

# Investigate bug

Own bounded reproduction and cause diagnosis. Ordinary matching requests and authorized bounded handoffs use this procedure. Supported diagnosis can complete in conversation without tracker access, Write Tickets or publication. Reuse a complete current investigation rather than repeating it because delivery starts. Explicit compound requests can continue to their selected ticket/delivery owner; this procedure ships no product fix.

## Authority and dependencies

Reuse the target project's applicable instructions and agreement once per context, including relevant context/authority and directory/runtime restrictions. Check meaningful decision/effect, safety, verification, documentation and continuation guidance, not Setup provenance or a fixed layout. Missing or materially conflicting guidance blocks dependent project work: name the gap and recommend explicit reconciliation without starting setup or rewriting policy. Tracker-specific gaps affect only requested tracker work.

Identify requested diagnostic execution, local probes, artifact retention and any selected downstream effects under that agreement. Preserve unrelated work, partial changes, modes, links and history. Inspection and a conversation return are the default; source access grants no installation, external disclosure, service startup, model calls or delegation. Product repair, PRs, closure, merge and release are outside this owner.

Discover needed companions through runtime/project guidance, not sibling paths. Inspect complete entries and relevant references for semantic compatibility and source identity. Missing/ambiguous helpers block only their dependent route; keep supported findings and do not install or substitute a legacy procedure.

- `write-tickets` is conditional on an explicitly selected ticket stage, including an investigation-and-ticket request or authorized bounded ticket handoff. Read [ticket stage](references/ticket-stage.md) only then; it owns duplicate inspection, selected publication, exact graph/label authority and read-back. Diagnosis alone does not load it or search a tracker.
- `analyze` is conditional for material technical-readiness/method/check gaps; require current code/caller evidence, targeted reuse and recommendations without implementation. Direct cause inspection and a supported method recommendation need no automatic Analyze run.
- `research` is conditional for unresolved authoritative source/version questions; require cited findings and freshness/disclosure bounds. Reading unchanged domain definitions needs no modeling run; actual meaning/decision work uses discovered `domain-modeling` with its plan-only/approved gate.
- Optional delegation needs separate authorization and discovered Work On's documented conditional coordination library, not delivery invocation or its old universal policy contract. Require root-owned allocation, protected ownership, finite lifecycle bounds and inspectable returns; workers cannot recursively delegate. Preserve active/unknown ownership and spent allowances through interruption. An old universal-contract-only installation blocks delegation, not equivalent direct diagnosis. No model assessment is required.

For changes or validation read [validation](references/validation.md).

## 1. Bound the report and reuse current evidence

Identify the actual target, reported expected/actual behavior, impact and intended contract source. Record agreement/acceptance references, relevant environment, exclusions, protected files, authority/approval source, prior findings and expected return. Clarify only missing consequential intent, access or permissions; investigate discoverable facts directly. A standalone bug needs no spec hierarchy.

Choose a finite diagnostic bound appropriate to the report: named paths/question, maximum attempts or time, and stopping conditions. Each experiment has a hypothesis, deciding observation and permitted effects. Stop earlier on unsafe execution, missing material capability or decisive evidence; exhausting the bound yields an honest partial/investigation result, not an unlimited loop.

Pin deciding implementation, callers, configuration/tests, environment and contract identities, including staged/unstaged/included untracked content digests rather than HEAD alone. Inspect supporting prior artifacts and raw results. Compare those identities on receipt/resume: reuse complete current evidence, fill only missing coverage, invalidate dependent findings when deciding inputs change or conflict. Preserve unaffected findings and old-state history; if dependency impact cannot be isolated, mark the relevant set stale and explain the expanded check. A label, age or prior summary is not freshness proof.

Use supplied issue evidence when relevant to diagnosis, but do not require tracker access or duplicate search for a local diagnosis. On a selected ticket route, Write Tickets owns matching/reconciliation. Missing access to a genuinely deciding source is a diagnostic gap; an unrelated tracker outage is not.

**Done:** scope, expectation source, authority, deciding identities, diagnostic bound and prior-evidence dispositions are explicit.

## 2. Confirm and minimize reproduction

Inspect relevant existing checks, implementation and callers. Choose the smallest safe reproduction in the reported environment, or clearly label a synthetic/substitute environment and its limits. Record exact steps/command, inputs, dependency/runtime/configuration versions, relevant timing/seed and observed expected-versus-actual results. Redact secrets and private data under retention/disclosure policy; insufficient safe evidence remains a gap.

For intermittent symptoms, record attempts, failures, successes and triggering conditions within the finite bound. A passing attempt does not disprove the report; distinguish observed intermittent reproduction from an unconfirmed report. A failure from missing dependencies, permissions or harness setup is not confirmation of the bug. Minimize inputs only while preserving the deciding behavior; keep baseline/control observations where useful.

Create probes or runnable reproduction artifacts only within approved diagnostic-write scope. Record owned paths, original identities, permitted edits, output home and retention/cleanup disposition before editing. Use isolated scratch copies where possible; never stash/reset unrelated work or turn a diagnostic experiment into product repair. Potentially destructive/load/production checks require exact environment and effects approval. Required unavailable checks are not-run, not passed.

**Done:** the symptom is confirmed with applicable raw observations, or attempts and the confirmation blocker are recorded. Unconfirmed work stays investigation-only.

## 3. Establish cause and bounded readiness

Trace the reproduced behavior through affected implementation and callers. Separate observations, hypotheses and established cause. For each material hypothesis choose a bounded discriminating check or inspection, record its result and rejected alternatives. Evidence must explain the causal path from trigger to actual behavior, not merely a suspicious line or correlation. A safe diagnostic intervention may support the cause, but its changed output is not a shipped fix or delivery acceptance.

Identify affected source locations/revisions and scope of impact. When decisive source/version or readiness gaps remain, use the conditional companions with only the bounded question, current evidence, protected work and exact authority. Inspect their cited support and actual results on return; reuse them directly. Ask the agreement owner about consequential behavior changes rather than inventing expected behavior.

End diagnostic probing when the cause is sufficiently established to bound a fix and regression strategy, or the diagnostic bound/capability limit is reached; then account for artifacts and return the evidence. Unresolved cause supplies attempted checks, remaining hypotheses, smallest next diagnostic action and owner. Confirmation alone is insufficient for an implementation-ready diagnosis.

**Done:** cause and readiness have deciding evidence, or the unresolved material gap prevents a ready fix claim.

## 4. Account for artifacts and assemble the diagnosis

Compare current content with owned probe changes before removing/restoring them under recorded cleanup authority. Intervening unrelated changes block conflicting cleanup; report remaining instrumentation exactly. Retain useful reproductions with runnable instructions and disclosure-safe output at an approved home, otherwise propose a location or return conversation evidence. Inspect final scoped diff/state for unapproved fixes or unexplained temporary changes.

Assemble the following conversation return, usable by a later delivery or ticket owner without a mandatory template or issue URL. Planned checks remain distinct from executed observations:

| Diagnosis content | Required evidence or decision |
| --- | --- |
| Identity/agreement | Target, expectation source/revision, acceptance references and approval boundaries; existing issue identity only if applicable |
| Behavior/impact | Confirmed expected/actual behavior, user/data/operational impact and relevant affected environment/versions |
| Reproduction | Exact steps or retained runnable artifact, observed results and attempt counts/intermittency, controls, environment limits |
| Cause | Established causal path, supporting/rejected-hypothesis evidence, affected code/callers and deciding committed/dirty identities |
| Fix boundary | Recommended bounded outcome/owned paths, constraints, exclusions, true dependencies, risks and non-blocking uncertainty |
| Acceptance/checks | Checkable regression acceptance IDs, meaningful failure sensitivity, sufficient existing/needed checks and environment; method or sequence recommendation with rationale, lead retains selection |
| State/reuse | Reused/refreshed/stale findings and input coverage, raw evidence pointers, protected work, probe cleanup and retained-artifact disposition |

For unconfirmed or unresolved cases, replace ready-fix scope with **investigation-only** outcome, attempted evidence, material blocker, diagnostic acceptance and next action. Preserve supported findings without manufacturing cause or repair scope. Failed artifact cleanup or missing material readiness prevents a complete ready handoff.

**Done:** every applicable field is supported or explicitly unresolved, and owned artifacts/diffs are accounted for.

## 5. Return diagnosis and honor only selected continuations

Compare deciding identities again before return and after any companion work. Refresh affected claims within the remaining diagnostic bound, or label them stale with the missing next check. Inspect actual support, not a success label.

Return **diagnosis complete — implementation-ready** only for a confirmed symptom, established causal path, complete current fix/check recommendation and accounted artifacts. Otherwise return **partial/blocked — investigation-only**, with the missing confirmation, cause, freshness, material capability or cleanup obligation, supported findings and smallest bounded diagnostic next action. Publication, a readiness label or an issue URL proves none of these facts.

Return the step 4 evidence with failed/not-run checks, uncertainty, companion identities and documentation disposition. Keep same-session evidence in conversation unless persistence is selected; no ticket, durable report or handoff is required. Retain active-owner, uncertain-operation and spent-allowance obligations under project guidance.

Recommend the useful next step based on size, importance and remaining uncertainty: direct delivery for a bounded ready fix, tickets for work that benefits from tracking/decomposition, or further bounded diagnosis for unresolved cause. Offer rather than execute an unrequested stage. A later advice request can recommend direct work from current complete diagnosis; an unpublished or absent ticket does not itself block readiness.

For an explicitly selected ticket stage, follow [ticket stage](references/ticket-stage.md) in this context without asking for another command. Report diagnostic readiness and actual ticket outcome separately: failed publication blocks the requested artifact, not an otherwise supported diagnosis. Honor draft/local overrides and declined publication.

For explicit investigation-and-fix authority, hand the current complete diagnosis and original approved effects to a compatible delivery lead, without a ticket or another command. The lead checks deciding identities/build readiness and fills only actual gaps. Missing delivery capability blocks continuation, not diagnosis. Discovery or investigation alone grants no fix authority; this procedure stops before product repair.