<!-- Generated from workflows/diagnostic-fix.md by tools/generate_integrations.py. Edit the source file, not this one. This is an execution WORKFLOW packaged as an Agent Skill so it is discoverable and directly invocable ("/diagnostic-fix") in every compatible tool. -->

Workflow: Diagnostic-then-Fix

When to Use

Criteria	Match
Intention	bug_fix, error_investigation
Complexity	unknown root cause, needs tracing
Power Mode	Balanced or Deep
Clarity	symptom is known, cause is unknown

Required Skills

• codebase-understanding (GitNexus): HEAVY use
• file-operations
• code-execution
• code-quality-testing
• communication-tone
• build-discipline
• safety-profiles (default)

Flow

Phase 0: Thinking Stage (Pre-Action)

• What is the exact symptom? Error message, wrong output, crash?
• Have I gathered all available diagnostic context? (logs, stack traces, state)
• Do NOT jump to fixing: root cause must be identified first
• Re-evaluate intent: is this diagnostic or fix?

Phase 1: Gather Symptoms

• What is the exact error message / unexpected behavior?
• When does it happen? (always, intermittent, specific conditions)
• What changed recently that might have caused it?

Phase 2: Trace Root Cause (Ariya-4 Problem Frame)

Before proposing any fix, complete all 4 fields of the Ariya-4 Problem Frame:

• Problem: What is actually broken (the root mechanism, not the symptom).
• Cause: Root causes (structural constraints, misaligned incentives, or reinforcing feedback loops).
• Cessation: Definition of Done (measurable, specific, bounded criteria for resolution).
• Path: Least-friction route from Problem to Cessation.

1. query({search_query: "<error text or symptom>"})
   → Identify suspect symbols and execution flows

2. context({name: "<suspect>"})
   → See all callers, callees, and processes

3. trace({from: "<entry_point>", to: "<suspect>"})
   → Find the shortest call chain if needed

4. READ gitnexus://repo/{name}/process/{name}
   → Step-by-step execution trace

Phase 3: Confirm Hypothesis

• Read source files at identified locations
• Add targeted logging to confirm the flow
• Reproduce the issue if possible
• If hypothesis is wrong: return to Phase 2 with new information

Phase 4: Fix

• Apply minimal targeted change addressing root cause
• DO NOT fix symptoms: fix the root
• DO NOT refactor unrelated code

Phase 5: Verify

• Run tests for affected execution flows
• Verify the original symptom is resolved
• Run detect_changes() to check blast radius

Phase 5b: Sanity Check

• Did I fix the ROOT CAUSE, not just the symptom?
• Have I verified the original symptom is actually resolved?
• Are there other places with the same pattern that need fixing?
• Did detect_changes() show only expected files changed?
• Is the fix minimal? No unrelated refactoring?

Phase 6: Report

• Root cause (1 sentence)
• Fix applied (1-2 sentences)
• Verification result

Token Budget

• Typical: 10K-40K tokens
• Max recommended: 80K tokens
• Warning threshold: >80K → consider session summarization

GitNexus Integration: Required

This workflow depends on GitNexus for:

• query: find code related to error
• context: 360° view of suspect symbols
• trace: call chain between entry point and error site
• detect_changes: verify fix scope

If GitNexus index is stale, run npx gitnexus analyze first.

Hallucination Watchpoints

• Fixing symptoms instead of root cause (most common)
• Making changes without tracing the full path
• Applying multiple fixes at once (which one worked?)
• Editing files in a loop without verifying results
• Assuming the error source based on surface similarity

Example

User: "Payment endpoint returns 500 intermittently"

Phase 2:
1. query({search_query: "payment error handling"})
   → CheckoutFlow: processPayment → validateCard → chargeStripe
   → ErrorHandling: handlePaymentError

2. context({name: "validatePayment"})
   → Outgoing calls: verifyCard, fetchRates (external API!)

3. trace({from: "checkoutHandler", to: "fetchRates"})
   → checkoutHandler → processPayment → validatePayment → fetchRates

4. Read fetchRates → no timeout configured on HTTP call

Phase 4: Add 5s timeout to fetchRates HTTP call
Phase 5: detect_changes() → only fetchRates.ts changed ✓