/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:

• the user's symptom report and corrections verbatim, with linked evidence; distinguish these from investigation interpretations
• observed and expected behavior, observed location, trigger, occurrence conditions, and onset when known; mark unresolved facts rather than selecting a location or condition by plausibility
• 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.

Resolve facts that change the investigation target from available evidence. Ask the user only for a target-changing fact that the investigation cannot obtain; continue unaffected investigation.

When the user corrects the symptom's location, expected behavior, timing, or conditions, update this envelope and return to path mapping for the corrected symptom. Re-evaluate affected exclusions and failure points through investigator and verifier before invoking solver. Retain evidence that remains valid; prior coverage closure applies only to the symptom and evidence it verified. When new information only adds evidence for the same symptom, reopen only the judgments it affects.

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**: Each specialist starts fresh with the current diagnosis scope envelope and the structured results named in its invocation. The envelope supplies the user's report independently of upstream interpretations.

Execution Steps

Step 1: Investigation (investigator)

**Agent tool invocation**:

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

  diagnosisScopeEnvelope: [Current 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` supplies decisive evidence for the reported causes and scope coverage; material evidence gaps are explicit
• [ ] 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]

  diagnosisScopeEnvelope: [Current Step 0 semantic scope envelope]

  Use these previous investigation results as context and investigate only the gaps listed above. Return one updated complete investigation JSON, retaining prior evide