recipe-diagnose

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.

Task Registration: Register execution steps using TaskCreate and proceed systematically. Update status using TaskUpdate.

Step 0: Problem Structuring (Before investigator invocation)

0.1 Problem Type Determination

If uncertain, ask the user whether any changes were made right before the problem occurred.

0.2 Information Supplementation for Change Failures

If the following are unclear, ask with AskUserQuestion before proceeding:

• What was changed (cause change)
• What broke (affected area)
• Relationship between both (shared components, etc.)

0.3 Problem Essence Understanding

Invoke rule-advisor via Agent tool:

subagent_type: rule-advisor
description: "Problem essence analysis"
prompt: Identify the essence and required rules for this problem: [user-reported problem verbatim]

Confirm from rule-advisor output:

• taskAnalysis.essence: Primary purpose of the diagnosis
• metaCognitiveGuidance.taskEssence: Root problem beyond surface symptoms
• selectedRules: Applicable skill and section names
• warningPatterns: Patterns to avoid

Execute each selected skill by its skill name and apply the named sections in the context of the complete skill before constructing the investigator prompt.

Diagnosis Flow Overview

Problem → investigator → verifier → solver ─┐
                 ↑                          │
                 └── coverage insufficient ─┘
                      (max 2 iterations)

coverage sufficient → Report

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

Execution Steps

Register the following using TaskCreate and execute:

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]
  Problem essence: [exact `metaCognitiveGuidance.taskEssence` from Step 0.3]
  Selected rules: [complete `selectedRules` from Step 0.3]
  Warning patterns: [complete `warningPatterns` from Step 0.3]

  [For change failures, additionally include:]
  Change details: [user-confirmed change-details statement verbatim]
  Affected area: [user-confirmed affected-area statement verbatim]
  Stated relationship: [user-confirmed relationship statement verbatim]

Expected output: 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)
• Investigation accounts for each supplied warningPatterns item
• All nodes on mapped paths have been checked (no path was abandoned after finding the first fault)

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]

  Previous investigation results (for context, do not re-investigate covered areas):
  [Previous investigation JSON]

design_gap Escalation:

When investigator output contains causeCategory: design_gap or recurrenceRisk: high:

1. Insert user confirmation before verifier execution
2. Use AskUserQuestion: "A design-level issue was detected. How should we proceed?"
   • A: Attempt fix within current design
   • B: Include design reconsideration
3. If user selects B, pass includeRedesign: true to solver

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.

Investigation results: [Investigation JSON output]

Expected output: Coverage check (missing paths, unchecked nodes), Devil's Advocate evaluation per failure point, failure point evaluation with checkStatus, coverage assessment

Coverage Criteria:

• sufficient: Main paths traced, all critical nodes checked, each failure point individually evaluated
• partial: Main paths traced, some nodes unchecked or some failure points at blocked/not_reached
• insufficient: Significant paths untraced, or critical nodes not investigated

Step 4: Solution Derivation (solver)

Agent tool invocation:

subagent_type: solver
description: "Derive solutions"
prompt: Derive solutions based on the following verified failure points.

Confirmed failure points: [verifier's conclusion.confirmedFailurePoints]
Refuted failure points: [verifier's conclusion.refutedFailurePoints]
Failure point relationships: [verifier's conclusion.failurePointRelationships]
Impact analysis: [investigator's impactAnalysis]
Coverage assessment: [sufficient/partial/insufficient]

Expected output: Multiple solutions (at least 3), tradeoff analysis, recommendation and implementation steps, residual risks

Completion condition: coverageAssessment=sufficient

When not reached:

1. Return to Step 1 with unchecked areas identified by verifier as investigation targets
2. Maximum 2 additional investigation iterations
3. After 2 iterations without reaching sufficient, present user with options:
   • Continue additional investigation
   • Execute solution at current coverage level

Step 5: Final Report Creation

Prerequisite: coverageAssessment=sufficient achieved

After diagnosis completion, report to user in the following format:

## Diagnosis Result Summary

### Identified Failure Points
[Confirmed failure points from verification results]
- Per failure point: location, symptom explained, finalStatus

### Verification Process
- Path coverage: [Paths traced and nodes checked]
- Additional investigation iterations: [0/1/2]
- Coverage assessment: [sufficient/partial/insufficient]

### Recommended Solution
[Solution derivation recommendation]

Rationale: [Selection rationale]

### Implementation Steps
1. [Step 1]
2. [Step 2]
...

### Alternatives
[Alternative description]

### Residual Risks
[solver's residualRisks]

### Post-Resolution Verification Items
- [Verification item 1]
- [Verification item 2]

Completion Criteria

• Executed investigator and obtained pathMap, failurePoints, and impactAnalysis
• Performed investigation quality check and re-ran if insufficient
• Executed verifier and obtained coverage assessment
• Executed solver
• Achieved coverageAssessment=sufficient (or obtained user approval after 2 additional iterations)
• Presented final report to user