/recipe-diagnose

name: recipe-diagnose
description: Investigate problem, verify findings, and derive solutions
disable-model-invocation: true

**Explicit User Instruction**: The user explicitly instructs and authorizes every subagent call named in this recipe. Execute each applicable call when its prerequisites are met.

Execute Skill: llm-friendly-context before writing Agent prompts, handoffs, or generated artifacts. Execute Skill: subagents-orchestration-guide before making workflow decisions, invoking agents, or resolving findings.

**Context**: Diagnosis flow to identify root cause and present solutions

Target problem: $ARGUMENTS

Orchestrator Definition

**Core Identity**: "I am an orchestrator."

**Local authority gate**: Make this recipe's workflow decisions and validate each returned result directly; delegate semantic deliverable production to the named specialist.

**Execution Method**:

• Investigation → performed by investigator
• Verification → performed by verifier
• Solution derivation → performed by solver

Orchestrator invokes sub-agents and passes structured JSON between them.

At each Agent invocation below, build the prompt as a mechanical extraction: copy the named source values into the exact fields, apply only the declared serialization, then invoke immediately.

**Execution Gate**: Each step below establishes evidence required by the next decision. Complete Steps 0-7 in order, including every required investigation and verification retry. Advance only through the current step's stated quality or coverage condition; invoke solver only after coverage is closed.

Step 0: Diagnosis Scope Envelope (Before investigator invocation)

Define a semantic scope envelope from the reported problem and repository evidence by recording:

• phenomenon and occurrence conditions to explain
• symptom-reachable execution paths and adjacent cases that share the same path, contract, persisted state, or external boundary
• applicable evidence axes: code, history, dependencies, configuration, governing documents, and external specifications
• explicit exclusions from the user or governing artifacts
• newly discovered areas are inside the envelope only when they have one of the relationships above and evidence shows they can change the supported cause set, coverage judgment, or counter-evidence

The envelope bounds relevance. Keep every relationship above active throughout investigation, including after a plausible cause appears.

Diagnosis Flow Overview

Problem → scope envelope → investigator → verifier
                         ↑                 │
                         └── named gaps ───┘

coverage closed → design decision gate when applicable → solver → Report
material evidence unavailable → limitation/block report

**Context Separation**: Pass only structured JSON output to each step. Each step starts fresh with the JSON data only.

Execution Steps

Step 1: Investigation (investigator)

**Agent tool invocation**:

subagent_type: investigator
description: "Investigate problem"
prompt: |
  Comprehensively collect information related to the following phenomenon.

  Phenomenon: [Problem reported by user verbatim]
  diagnosisScopeEnvelope: [Step 0 semantic scope envelope]

**Expected output**: scopeAccounting, pathMap (execution paths per symptom), failurePoints (faults found at each node), impactAnalysis per failure point, unexplored areas, investigation limitations

Step 2: Investigation Quality Check

Review investigation output:

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

• [ ] `pathMap` exists with at least one symptom, and each symptom has at least one path with nodes listed
• [ ] Each failure point has: `location`, `upstreamDependency`, `symptomExplained`, `causalChain` (reaching a stop condition), `checkStatus`, `evidence` with a `source` citing a specific file or location
• [ ] Each failure point has `comparisonAnalysis` (normalImplementation found or explicitly null)
• [ ] `causeCategory` for each failure point is one of: typo / logic_error / missing_constraint / design_gap / external_factor
• [ ] `investigationSources` covers at least 3 distinct source types (code, history, dependency, config, document, external)
• [ ] All nodes on mapped paths have been checked (no path was abandoned after finding the first fault)
• [ ] `scopeAccounting` accounts for every scope-envelope item as investigated, excluded with governing evidence, or unavailable with its potential effect

**If quality insufficient**: Re-run investigator specifying missing items explicitly:

prompt: |
  Re-investigate with focus on the following gaps:
  - Missing: [unsatisfied Step 2 Quality Check items, copied as written]

  Use these previous investigation results as context and investigate only the gaps listed above. Return one updated complete investigation JSON, retaining prior evidence that remains valid:
  [Previous investigation JSON]

Proceed to verifier once quality is satisfied.

Step 3: Verification (verifier)

**Agent tool invocation**:

subagent_type: verifier
description: "Verify investigation results"
prompt: Verify the following investigation results against the semantic diagnosis scope envelope.

diagnosisScopeEnvelope: [Step 0 semantic scope envelope]
Investigation results: [Investigation JSON output]

**Expected output**: Scope-envelope coverage, coverage check (missing paths, unchecked nodes), Devil's Advocate evaluation per failure point, failure point evaluation with checkStatus, coverage assessment and disposition

**Coverage Criteria**:

• **sufficient / closed**: Every relevant scope-envelope item and symptom-reachable critical node is accounted for; each failure point is independently evaluated; remaining limitations cannot materially change the supported cause set
• **partial / gaps_remaining**: Named accessible gaps could materially change the supported cause set
• **insufficient / gaps_remaining**: Significant relevant path