recipe-diagnose · diff
git:20260802.aa3bfed to git:20260802.c018280
19 added, 25 removed. Audit A to A.
---
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
**Spawn rule**: every `spawn_agent` call uses `fork_turns="none"` so the subagent receives only the task message and explicitly provided context.
**Context**: Diagnosis flow to identify concrete failure points and present solutions
Target problem: $ARGUMENTS
## Orchestrator Definition
**Execution Method**:
- Investigation -> Spawn investigator agent
- Verification -> Spawn verifier agent
- Solution derivation -> Spawn 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 Gate**: Before substantive work, call `update_plan` with first "Map active rules to this task", then problem structuring, investigation, verification, and solution, and final "Verify outputs and rule adherence". While work remains, keep exactly one step `in_progress`; after final report evidence exists, mark every step `completed`.
+ **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 spawning investigator)
### 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 -> solver --+
- ^ |
- +-- coverage insufficient -----+
- (max 2 iterations)
-
- coverage sufficient -> Report
+ 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**: Pass only structured output to each step. Each step starts fresh with the data only.
## Execution Steps
Execute the registered steps:
### Step 1: Investigation (investigator)
Spawn investigator agent with the following prompt:
```text
Comprehensively collect information related to the following phenomenon.
Phenomenon: [Problem reported by user]
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 at least 3 distinct source types
+ - [ ] `investigationSources` covers the source types needed to support or refute the causal path
- [ ] each failure point has supporting evidence with a concrete source
- **If quality insufficient**: MUST re-spawn investigator agent specifying the missing items and include the previous investigation output for context
- ENFORCEMENT: Proceeding to verifier with incomplete investigation data produces unreliable conclusions.
+ When required evidence is missing, re-run investigator with the missing items and previous output. Proceed to verifier when the causal path and its material unknowns are explicit.
Carry `causeCategory: design_gap` and `recurrenceRisk: high` through verification and solution derivation as evidence. Diagnosis presents the resulting trade-offs without changing implementation scope.
Proceed to verifier once quality is satisfied.
### Step 3: Verification (verifier)
Spawn verifier agent: "Verify the following investigation results. Investigation results: [Investigation output]"
**Expected output**: Path coverage findings, independent failure-point evaluation, final conclusion, coverageAssessment/finalStatus
**Coverage Criteria**:
- **sufficient**: No major uncovered boundary affects solution selection or implementation
- - **partial**: Some uncertainty exists but a bounded next investigation is possible
+ - **partial**: Some uncertainty remains, but the cause, applicable contract or expected behavior, and affected boundary are usable; verifier states which response-selection constraints remain uncertain
- **insufficient**: Fundamental information gap exists on the relevant path
### Step 4: Solution Derivation (solver)
- Spawn solver agent: "Derive solutions based on the following verified conclusion. Failure points: [verifier's conclusion.confirmedFailurePoints]. Failure-point relationships: [verifier's conclusion.failurePointRelationships]. Coverage assessment: [verifier's conclusion.coverageAssessment]. Final status: [verifier's conclusion.finalStatus]. Impact analysis: [investigator output impactAnalysis]."
+ When `finalStatus=ready_for_solution`, spawn solver agent: "Derive solutions based on the following verified conclusion. Verified conclusion: [verifier's conclusion]. Failure-point evaluations: [verifier's failurePointsEvaluation]. Verification limitations: [verifier's verificationLimitations]. Impact analysis: [investigator output impactAnalysis]."
- **Expected output**: Multiple solutions (at least 3), tradeoff analysis, recommendation and implementation steps, residual risks
+ **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**: `coverageAssessment=sufficient` and `finalStatus=ready_for_solution`
+ **Completion condition**: `finalStatus=ready_for_solution` and solver returns a non-null evidence-supported recommendation.
- **When not reached**:
- 1. Return to Step 1 with uncertainties identified by solver as investigation targets
- 2. Maximum 2 additional investigation iterations
- 3. After 2 iterations without reaching sufficient coverage, present user with options:
- - Continue additional investigation
- - Execute solution at current coverage level
+ **When not reached**: Return to Step 1 with 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**: sufficient coverage achieved
+ **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 iterations: [0/1/2]
+ - 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
- [Alternative description]
+ [Material alternative descriptions, or none]
### Residual Risks
[solver's residualRisks]
### Post-Resolution Verification Items
- [Verification item 1]
- [Verification item 2]
```
## Completion Criteria
- [ ] Spawned investigator and obtained evidence matrix, comparison analysis, and causal tracking
- [ ] Performed investigation quality check and re-ran if insufficient
- [ ] Spawned verifier and obtained coverage assessment
- - [ ] Spawned solver
- - [ ] Achieved sufficient coverage (or obtained user approval after 2 additional iterations)
+ - [ ] Spawned 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