git:20261017.0144de9 to git:20261023.aaf52b6

---

name: recipe-diagnose

description: "Investigate problem, verify findings, and derive solutions through structured diagnosis."

---

## Required Skills [LOAD BEFORE EXECUTION]

1. [LOAD IF NOT ACTIVE] `ai-development-guide` — AI development patterns

2. [LOAD IF NOT ACTIVE] `coding-rules` — coding standards

3. [LOAD IF NOT ACTIVE] `llm-friendly-context` — clear prompts, handoffs, and generated artifacts

**Invocation rule**: Start each named agent with `spawn_agent` and `fork_turns="none"`. When invoking the same named agent again within this flow, use `followup_task` on its existing instance with the inputs specified for the current invocation.

**Context**: Diagnosis flow to identify concrete failure points and present solutions

Target problem: $ARGUMENTS

## Orchestrator Definition

**Execution Method**:

- Investigation -> Invoke investigator agent

- Verification -> Invoke verifier agent

- Solution derivation -> Invoke solver agent

The orchestrator structures the reported problem, coordinates the three specialist stages, evaluates their results, and passes only the context needed by the next stage.

**Execution Plan**: Reuse the active execution plan. When the workflow has multiple dependent actions and no plan exists, create one that tracks them through final verification. Complete a plan step after verifying its result; start a dependent step after its prerequisites are satisfied.

## Step 0: Problem Structuring (Before invoking investigator)

Keep the user's current symptom report and corrections verbatim, separate from investigation interpretations. Record observed and expected behavior, location, trigger, conditions, and onset when known. Resolve target-changing uncertainty from available evidence; ask the user only for a fact the investigation cannot obtain, and continue unaffected work.

When a correction changes the symptom's location, expected behavior, timing, or conditions, update this record and return to investigator for path mapping and affected findings, then verifier before solution derivation. In follow-up calls, identify which prior interpretation the correction supersedes; retain evidence that remains valid. Prior readiness and recommendations apply only to the symptom and evidence they evaluated. An evidence-only addition for the same symptom reopens only the judgments it affects.

### 0.1 Problem Type Determination

| Type | Criteria |

|------|----------|

| Change Failure | Indicates some change occurred before the problem appeared |

| New Discovery | No relation to changes is indicated |

If uncertain, keep the type provisional and let repository history and investigation evidence resolve it.

### 0.2 Information Supplementation for Change Failures

For change failures, resolve the following from the supplied report and repository evidence when available:

- What was changed (cause change)

- What broke (affected area)

- Relationship between both (shared components, etc.)

Carry unresolved details into the investigator prompt as investigation targets and continue.

## Diagnosis Flow Overview

```

Problem -> investigator -> verifier

verifier needs_more_investigation -> investigator while new evidence can change coverage

verifier ready_for_solution -> solver

solver recommendation -> Report

solver null recommendation -> investigator while new evidence can change the result

evidence saturated before recommendation -> unresolved Report

```

**Context Separation**: Supply the current symptom record from Step 0 alongside the structured results named below, including on follow-up calls. Each agent's first invocation starts fresh; the symptom record supplies the user's report independently of upstream interpretations.

## Execution Steps

Execute the registered steps:

### Step 1: Investigation (investigator)

Invoke investigator agent with the following prompt:

```text

Collect decision-relevant information about the following phenomenon.

Current symptom: [Step 0 report, corrections, and known or unresolved symptom facts]

For change failures, include available facts and unresolved investigation targets for:

- what changed

- what broke

- what both areas share

```

**Expected output**: Evidence matrix, path map, failure points, comparison analysis results, list of unexplored areas, investigation limitations

### Step 2: Investigation Quality Check

Review investigation output:

**Quality Check** (verify output contains the following):

- [ ] `comparisonAnalysis` is present and `normalImplementation` is non-null, or explicitly states that no working implementation was found

- [ ] `pathMap` is present with ordered nodes or explicit unknown segments

- [ ] causalChain for each failure point reaches a stop condition

- [ ] causeCategory for each failure point

- [ ] `investigationSources` covers the source types needed to support or refute the causal path

- [ ] each failure point has supporting evidence with a concrete source

When required evidence is missing, re-run investigator with the current symptom record, missing items, and previous output. Proceed to verifier when the causal path and its material unknowns are explicit.

Proceed to verifier once quality is satisfied.

### Step 3: Verification (verifier)

Invoke verifier agent: "Verify the following investigation results against the current reported symptom. Current symptom: [Step 0 symptom record]. Investigation results: [Investigation output]"

**Expected output**: Path coverage findings, independent failure-point evaluation, final conclusion, coverageAssessment/finalStatus

Use the verifier's `coverageAssessment` and its Coverage Determination Criteria as the single coverage definition.

### Step 4: Solution Derivation (solver)

When `finalStatus=ready_for_solution`, invoke solver agent: "Derive solutions for the current symptom based on the following verified conclusion. Current symptom: [Step 0 symptom record]. Verified conclusion: [verifier's conclusion]. Failure-point evaluations: [verifier's failurePointsEvaluation]. Verification limitations: [verifier's verificationLimitations]. Impact analysis: [investigator output impactAnalysis]."

**Expected output**: Credible materially distinct solutions, relevant tradeoffs, and either a supported recommendation with implementation steps or a null recommendation with exact missing evidence. One solution is sufficient when evidence rules out a meaningful alternative.

**Completion condition**: `finalStatus=ready_for_solution` and solver returns a non-null evidence-supported recommendation.

**When not reached**: Return to Step 1 with the current symptom record and the verifier's material unknowns or solver's `uncertaintyHandling.missingEvidence` as investigation targets while repository or supplied evidence can change the result. When further investigation produces no new decision-relevant evidence, report the unresolved input and its effect instead of repeating the loop.

### Step 5: Final Report Creation

**Prerequisite**: a non-null solver recommendation. When available evidence stops changing without producing one, report the exact unresolved input and its effect, and mark recommendation, implementation steps, and alternatives N/A.

After diagnosis completion, report to user in the following format:

```

## Diagnosis Result Summary

### Identified Failure Points

[Failure point list from verification results]

- Failure-point relationships: [independent/upstream_of/downstream_of/amplifies/same_boundary]

### Verification Process

- Investigation scope: [Scope confirmed in investigation]

- Additional investigation: [material evidence added, or none]

- Coverage assessment: [sufficient/partial/insufficient]

### Recommended Solution

[Solution derivation recommendation]

Rationale: [Selection rationale]

### Implementation Steps

1. [Step 1]

2. [Step 2]

...

### Alternatives

[Material alternative descriptions, or none]

### Residual Risks

[solver's residualRisks]

### Post-Resolution Verification Items

- [Verification item 1]

- [Verification item 2]

```

## Completion Criteria

- [ ] Invoked investigator and obtained evidence matrix, comparison analysis, and causal tracking

- [ ] Performed investigation quality check and re-ran if insufficient

- [ ] Invoked verifier and obtained coverage assessment

- [ ] Invoked solver when `finalStatus=ready_for_solution`

- [ ] Reached `ready_for_solution` with a supported recommendation, or reported the exact unresolved input after available evidence stopped changing coverage

- [ ] Presented final report to user