Claude-code-workflows recipe-diagnose

Context: Diagnosis flow to identify root cause and present solutions

Target problem: $ARGUMENTS

Orchestrator Definition

Core Identity: "I am not a worker. I am an orchestrator."

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.

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

Type	Criteria
Change Failure	Indicates some change occurred before the problem appeared
New Discovery	No relation to changes is indicated

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: [Problem reported by user]

Confirm from rule-advisor output:

• taskAnalysis.mainFocus

  : Primary focus of the problem

• mandatoryChecks.taskEssence

  : Root problem beyond surface symptoms

• selectedRules

  : Applicable rule sections

• warningPatterns

  : Patterns to avoid

0.4 Reflecting in investigator Prompt

Include the following in investigator prompt:

1. Problem essence (taskEssence)
2. Key applicable rules summary (from selectedRules)
3. Investigation focus (investigationFocus): Convert warningPatterns to "points prone to confusion or oversight in this investigation"
4. For change failures, additionally include:
   • Detailed analysis of the change content
   • Commonalities between cause change and affected area
   • Determination of whether the change is a "correct fix" or "new bug" with comparison baseline selection

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]

  Problem essence: [taskEssence from Step 0.3]
  Investigation focus: [investigationFocus from Step 0.4]

  [For change failures, additionally include:]
  Change details: [What was changed]
  Affected area: [What broke]
  Shared components: [Commonalities between cause and effect]

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 covers

  investigationFocus

  items (when provided in Step 0.4)
• 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: [list specific missing items from quality check]

  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