Why

Why

Contract

Inputs

• Mode: one of full (default) or source-tiers. Source-tiers mode fires when the user asks for the evidence organized strictly by source-confidence tier with unknowns retained and no inference filling gaps.

Establish:

• The exact decision, implementation, regression, incident, or threshold whose rationale is in question.
• The relevant component, owner, repository, service, product area, and approximate time range when known.
• Any candidate explanation supplied by the user; treat it as a hypothesis, not evidence.
• Which of these seven evidence categories are reachable through tools already available in the environment: source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, and product analytics warehouse.
• Source-tiers mode optional input: a subset of the available source categories to query. Default is all available categories.

Availability means a read-only tool or authenticated MCP can actually query the category. Do not request new credentials, add an integration, or substitute a web search for an unavailable private source. Record every unavailable category explicitly.

Use this epistemic vocabulary throughout:

• Direct finding: the cited source explicitly states the claim, or the cited primary artifact directly records the event or measurement.
• Inference: the claim follows from cited findings but is not explicitly stated by a source. Show the reasoning bridge.
• Hypothesis: a plausible explanation that the evidence does not establish. State what evidence would confirm or falsify it.
• High confidence: explicit primary evidence or multiple independent, mutually consistent sources directly support the claim.
• Medium confidence: one credible direct source or several consistent indirect sources support the claim, with a material gap remaining.
• Low confidence: the claim rests on circumstantial evidence, an ambiguous recollection, or a single indirect source.

Source-tiers mode classifies every claim into one of four tiers instead of the inference labels:

• Well-sourced: multiple independent citations or one strong primary source support the claim.
• Weakly-sourced: a single indirect or secondary citation supports the claim.
• Unsupported: citations are absent, mismatched, or inaccessible.
• Unknown: no source yielded evidence.

Confidence qualifies support, not importance. Chronology alone does not establish causation. Separate what happened from why it happened, distinguish contemporaneous evidence from hindsight, and prefer source-proximate records over later summaries while retaining material contradictions.

Procedure

1. Frame the investigation. Restate the question as a neutral rationale question, define the likely decision window, and list the seven categories with status available or unavailable and the reason. Do not assume the user's candidate explanation is correct. Mode source-tiers: confirm the investigation question is concrete enough to direct evidence collection; if ambiguous, state the ambiguity and the assumed interpretation before proceeding, and map the question to the categories that can yield evidence for it (or to the user-supplied subset). Done when: question is framed and all seven categories are listed with status.
2. Dispatch one parallel scout batch. In one task batch, launch exactly one read-only investigator scout for each category marked available (in source-tiers mode, each selected category). Do not launch scouts for unavailable categories and do not combine two available categories under one scout. Give every scout the same question, entity/time scope, epistemic vocabulary, and this response schema: category and query scope; direct findings (each with a stable citation or permalink, source date, and short quoted or precisely paraphrased evidence); inferences (each linked to supporting findings, carrying High/Medium/Low confidence); hypotheses (each carrying Low confidence unless direct evidence raises it, plus confirming or falsifying evidence); contradictions and chronology; null result or access gap; sources consulted. Every scout is read-only and must report a null result rather than filling silence with general knowledge. Done when: one scout per available category is dispatched.
3. Apply the category playbook inside each scout using references/category-playbook.md. Done when: each scout applies its category-specific source instructions.
4. Collect the batch without erasing nulls. Build a seven-row evidence ledger. For each category record available with evidence, available but no relevant evidence, unavailable, or failed read, plus its citations or exact gap. This null accounting is required even when another category appears decisive. Done when: seven-row ledger is built with null accounting.
5. Run one read-only synthesizer. Supply the synthesizer only the framed question, the seven-row ledger, and the scouts' cited packets. Instruct it to: answer the question directly before narrating the search; preserve the Direct finding / Inference / Hypothesis labels and High/Medium/Low confidence; merge duplicate evidence without dropping citations; reconcile chronology and surface contradictions rather than choosing silently; distinguish original rationale, later rationalization, observed outcome, and current constraint; state which alternatives were considered or explicitly say none were found; account for every category and every material gap; end with a Preserve / Change / Avoid / Risk handoff grounded only in the evidence packet. Mode source-tiers: the synthesizer instead places every claim into the well-sourced, weakly-sourced, unsupported, or unknown tier, presents contradictions with each position cited, and retains unknowns without filling gaps by inference or speculation. Done when: synthesizer is run with complete instructions.
6. Verify the synthesis before returning it. Check that every direct finding resolves to a supplied citation, every inference names its supporting findings, every hypothesis is visibly non-factual, all seven categories appear in source coverage, and no confidence label exceeds its evidence. Remove unsupported claims; never backfill them from model memory. Mode source-tiers: verify that each citation supports its attached claim and flag mismatches as unsupported; check that every claim sits in exactly one tier and every unknown stays unknown. Done when: synthesis passes all verification checks.

Failure and recovery

• No read access for a category: mark it unavailable with the reason and continue the single batch with the remaining available categories. Never request credentials or mutate configuration.
• Available scout returns no evidence: retain available but no relevant evidence as a meaningful null. Do not convert it into support for or against the explanation.
• A read fails: record failed read, the attempted scope, and the observed failure. Continue with other category results; do not launch a replacement scout that would violate the one-scout-per-available-category batch.
• Evidence conflicts: present each supported account with its date, provenance, and confidence. Prefer neither recency nor seniority by default; explain which primary evidence would resolve the conflict. Never resolve a contradiction by majority vote or speculation.
• Citation is missing or unstable: downgrade the statement to an explicitly unsupported hypothesis or omit it. Do not present an uncited recollection as a direct finding. In source-tiers mode, a citation mismatch downgrades the claim to the unsupported tier; do not reinterpret the citation to force a match.
• The synthesizer drops labels, citations, null accounting, or the handoff: rerun the read-only synthesis over the same evidence packet with the missing output field named. Do not repeat source collection or invent evidence.
• No category yields relevant evidence: return an insufficient-evidence narrative with all seven null/gap entries and the most useful next read-only evidence to locate. Do not manufacture a rationale.
• Scope creep: stop at the original scope boundary. Report partial results with the boundary stated.
• A source contains secrets or unnecessary personal data: omit or minimally redact that material while retaining a stable citation and enough non-sensitive context to support the claim.

Output

Full mode: a cited narrative in chat with sections in order: Answer (best-supported rationale with overall High/Medium/Low confidence), What the evidence says (Direct findings, then Inferences, then Hypotheses, each with confidence and citations), Decision chronology and alternatives, Source coverage and gaps (all seven categories with status), Handoff (Preserve/Change/Avoid/Risk tied to cited evidence or marked as inference), and Sources (deduplicated stable links with category and date). Source-tiers mode: a structured report with the investigation question, the confidence-tiered narrative (well-sourced, weakly-sourced, unsupported, unknown), the source coverage summary, and open unknowns, ordered as listed.