Recipe Diagnose

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 paths or critical nodes remain uninvestigated
• partial or insufficient / evidence_unavailable: Unavailable material evidence could change the supported cause set and no available action can close that gap