recipe-diagnose

Required Skills [LOAD BEFORE EXECUTION]

Before loading required skills, use wc -c to size the files and set both exec_command.max_output_tokens and the outer // @exec: {"max_output_tokens": N} budget to accommodate their contents, including the combined output of batched reads. Split oversized reads upfront; recover any truncated content before proceeding.

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

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:

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