bm-systematic-troubleshooting

name: bm.systematic-troubleshooting description: "Systematic root cause troubleshooting: 4-phase method (Reproduce → Isolate → Hypothesize → Verify). Use when something is broken, wrong, slow, weird, unexpected, intermittent, 出错, 报错, bug, 问题, 不对, 慢, 卡, 怪, 排查, 定位, debug, troubleshoot. Applicable to code bugs, product anomalies, process errors, data issues — any scenario where 'things are not happening as expected'." source: opencrew version: "20260530.01"

Skill: Systematic Troubleshooting

First reproduce, then isolate, then hypothesize, finally verify. Never rely on guessing. Applicable to all scenarios where "things are not happening as expected".

Not just code bugs — product process anomalies, data mismatches, device malfunctions, operations not responding, processes stuck — all apply.

Core Principles

1. Evidence before hypotheses: Don't start fixing without reproducing
2. Narrow the scope, don't broaden it: Each step should make the problem boundary clearer
3. Hypotheses must be falsifiable: Can be verified with a single yes/no action
4. Change the minimum: Only manipulate one variable at a time
5. Must verify after fixing: Otherwise you may have just masked the issue

4-Phase Method

Phase 1: Reproduce

Goal: Make the problem appear in a controlled, stable, minimal-step manner.

Key actions:

• Find the minimal reproduction steps (remove all non-essential steps)
• Record environmental differences: when it occurs vs. when it doesn't
• Cannot stably reproduce: Record frequency and conditions, don't skip

Problem classification (determines next-step strategy):

Anti-patterns:

• ❌ Start modifying code without reproducing → You won't know if the fix worked
• ❌ Reproduce once and think it's handled → Intermittent issues need multiple confirmations

Phase 2: Isolate

Goal: Compress the boundary of "where the problem is" from large to small.

Methods:

Ask "Why" 5 Times:

• Surface: Error thrown
• Why the error? → Function returned None
• Why None? → Database query returned nothing
• Why nothing? → Field name was misspelled
• Why misspelled? → Schema was changed last week without syncing
• Root cause: Change management process missing

Fix the deepest layer you can fix, not the surface layer.

Phase 3: Hypothesize

Goal: Based on evidence, list 2-3 most likely root causes, each verifiable.

Criteria for a good hypothesis:

• ✅ Specific: "port field in config.json is string '8080' instead of number 8080"
• ✅ Falsifiable: Running one action tells you if it's right or wrong
• ❌ "Might be a configuration issue" — too vague
• ❌ "Probably a caching problem" — no evidence

List hypotheses ordered by probability:

Hypothesis 1 (most likely): A broke B
  - Verification: Run X and check Y
  - Evidence source: Error message mentions A

Hypothesis 2: Environment difference
  - Verification: Reproduce on staging
  - Evidence source: Works locally, doesn't work in production

Hypothesis 3 (fallback): Third-party dependency
  - Verification: Check dependency versions
  - Evidence source: Recently upgraded

Phase 4: Verify

Goal: Confirm whether the hypothesis is correct, then confirm whether the fix is effective.

Two-step verification:

1. Verify root cause: Use Phase 3's verification action to confirm the hypothesis

   • Hypothesis wrong → Return to Phase 3, try next hypothesis
   • Hypothesis correct → Proceed to fix

2. Verify fix:

   • Change the minimum code / configuration / steps
   • Run Phase 1's reproduction steps again — must no longer trigger the problem
   • Run related tests / adjacent scenarios — no new issues introduced
   • Use bm.verification to provide a completion report

Output Format

Document the troubleshooting process for user follow-up / future retrospectives:

# Troubleshooting Record: {Problem}

## Symptoms
- {One-sentence description}
- Reproduction steps:
  1. ...
  2. ...

## Environment
- {OS / version / configuration}

## Troubleshooting Timeline

### Phase 1: Reproduce ✅
- Successfully reproduced, always reproducible
- Minimal steps: ...

### Phase 2: Isolate
- Bisected X, problem is in module Y
- 5 Whys: ... → Root cause guess: ...

### Phase 3: Hypothesize
1. ❌ A: Ruled out after verification (evidence: ...)
2. ✅ B: Confirmed (evidence: ...)

### Phase 4: Verify
- Fixed ...
- Reproduction steps no longer trigger the issue ✅
- Adjacent tests passed ✅

## Root Cause
{One sentence}

## Fix
{What was changed, why it was changed this way}

## Prevention
- {Process/checklist item}

Anti-Patterns

Non-Code Scenario Examples

Scenario: User says "one of my files is missing"

1. Reproduce: Ask the user which file specifically, when they noticed, when they last saw it
2. Isolate: Was it actually deleted or just can't be found? Trash/recent files/git log?
3. Hypothesize: Accidental deletion / renamed / sync issue / path changed
4. Verify: Each hypothesis corresponds to a search action

Scenario: No one showed up to the meeting

1. Reproduce: Who came to the previous few meetings?
2. Isolate: Is this one unusual or has it always been like this? Who sent the invitations?
3. Hypothesize: Invitations didn't reach people / time conflicts / topic wasn't compelling / no one felt they should attend
4. Verify: Spot-check a few people and ask

File Locations

• Troubleshooting records → ./working/troubleshoot-{topic}.md
• Root cause summaries for important issues → Archive to ./postmortems/{date}-{topic}.md (code project → ./docs/postmortems/{date}-{topic}.md)

Code Project Detection: If code project markers exist under cwd (package.json, Cargo.toml, go.mod, pyproject.toml, setup.py, pom.xml, Gemfile, composer.json, or src/ + .git/), final artifacts go under ./docs/ in corresponding subdirectories instead of the project root. Intermediate artifacts in ./working/ remain unchanged. User-specified paths take priority.