Troubleshooting Command

You are executing the SYSTEMATIC TROUBLESHOOTING workflow - a methodical debugging process that prevents spinning wheels through hypothesis-driven investigation.

Contents

• •Problem Context
• •What Makes This Different
• •Workflow Overview
• •Phase Details
• •Ask For Help Mechanism
• •Error Handling

Problem Context

$ARGUMENTS

If no specific problem was provided above, you will help the user define the problem clearly.

What Makes This Different

Ad-hoc debugging: Try things randomly, hope something works Systematic troubleshooting (this command): Form hypotheses, gather evidence, verify fixes

Key capability: "Something is broken" → investigate → "Root cause identified and fixed"

This provides structured debugging rather than trial and error.

Relationship to Feature-Audit

Both complement each other - audit can prevent issues, troubleshoot resolves them.

Workflow Overview

This command orchestrates a 5-phase workflow:

Phase Details

Phase 1: Problem Definition

See: problem-definition.md

• •Gather problem details from user
• •Establish expected vs actual behavior
• •Identify when the problem started (if known)
• •Document reproduction steps
• •Scope the problem

Phase 2: Hypothesis Formation

See: hypothesis.md

• •Generate possible causes
• •Rank by likelihood
• •Identify evidence needed to test each
• •Create investigation plan
• •Track hypothesis status

Phase 3: Investigation

See: investigation.md

• •Systematically test hypotheses
• •Gather evidence (logs, code reading, testing)
• •Update hypothesis rankings based on evidence
• •Use audit-style log injection if needed
• •Ask for help if stuck

Phase 4: Resolution

See: resolution.md

• •Propose fix based on evidence
• •Get user approval
• •Apply the fix
• •Document what was changed

Phase 5: Verification

See: verification.md

• •Verify the fix works
• •Confirm original problem is resolved
• •Check for regressions
• •Document resolution

Ask For Help Mechanism

To prevent spinning wheels, this workflow includes an "ask for help" mechanism.

When to Trigger

Ask the user for help when:

1. •No progress on hypothesis - Investigated 3+ hypotheses with no root cause found
2. •Conflicting evidence - Evidence doesn't match any hypothesis
3. •Access limitations - Can't access needed logs, systems, or data
4. •Domain knowledge gap - Problem requires specific domain expertise
5. •Time threshold - Significant time spent without progress

How to Ask

## Seeking Additional Input

I've investigated [N] hypotheses but haven't identified the root cause.

### What I've Tried
1. [Hypothesis 1] - Ruled out because [evidence]
2. [Hypothesis 2] - Ruled out because [evidence]
3. [Hypothesis 3] - Inconclusive, need more data

### What Would Help
- [ ] Access to [specific logs/system]
- [ ] Information about [specific question]
- [ ] Someone with [domain] expertise
- [ ] Permission to [specific action]

### Questions for You

1. Have you seen this issue before?
2. Any recent changes that might be related?
3. Can you provide [specific information]?
4. Should we escalate to [team/person]?

Troubleshooting Session Storage

For complex issues, store session data:

docs/troubleshooting/
└── [session-id]/
    ├── session.json          # Problem definition, hypotheses, status
    ├── evidence/             # Captured logs, screenshots, test results
    └── resolution.md         # Final resolution documentation

Integration Points

• •Use with feature-audit: If you need runtime evidence, trigger /feature-audit for specific verification
• •Works with code-archaeologist: For understanding unfamiliar code during investigation
• •Complements feature workflow: Can debug issues found during /feature-ship

Error Handling

Philosophy: "Debug with Evidence, Not Intuition"

This workflow ensures:

• •Problems are clearly defined before debugging
• •Investigation is systematic, not random
• •Hypotheses are tested with evidence
• •Fixes are verified, not assumed
• •Knowledge is preserved for future issues

No more spinning wheels. No more "try this and see."

Let's identify the problem and fix it systematically!