investigation-mode

name	investigation-mode
description	Use when there are 2+ consecutive failures, repeated errors, or the work feels stuck - pauses implementation, switches to root-cause investigation, gathers evidence, and resumes only after a verified plan and options

Investigation Mode

Overview

This skill provides a hard stop and a repeatable workflow when progress stalls or errors repeat. It prevents “random walk” fixes and forces evidence-first debugging.

Use when...

• There are 2+ consecutive failures/errors in the same feature or approach
• The same error comes back after “fixes”
• There is temptation to “just workaround” or change approach silently
• The problem statement is unclear and implementation would be guesswork

Symptoms / keywords

• “stuck”, “still failing”, “same error”, “again”, “flaky”, “intermittent”, “can’t reproduce”, “works on my machine”
• “quick workaround”, “let’s just do it manually”, “skip validation”, “good enough”
• CI-only failures, nondeterministic tests, repeating TypeScript/build/lint errors

Rules (verbatim triggers)

Failure response rules

• 2+ consecutive failures: Switch to investigation mode
• Ask before: Using workarounds or alternatives
• Explain: Why original approach failed
• Options: Use task-direction-approval (2–3 options + trade-offs; ask user when changing direction).

Core: Respect user's original intent. When stuck, find proper solutions rather than taking shortcuts.

After 2 consecutive errors in same feature

1. 🛑 PAUSE - Stop implementation immediately
2. 🔍 INVESTIGATION MODE - Switch focus to root cause analysis
3. 📖 Deep Research - Dispatch a research subagent to execute web fetch for official docs, RFCs, known issues and return a cited Context Package
4. 🧠 Sequential-thinking - Analyze fundamental misunderstanding
5. 🧪 Test First - Write comprehensive tests before continuing

Declare mode switch: "🔍 INVESTIGATION MODE: Pausing to research root cause"

Workflow

1. Freeze changes: stop making further edits that are not evidence-driven.
2. Capture evidence: record the exact error text, stack traces, logs, and minimal repro steps.
3. Constrain scope: isolate the smallest failing unit (single test, single endpoint, single build step).
4. Run root cause analysis:
   • REQUIRED SUB-SKILL: Use root-cause-tracing for systematic isolation techniques.
   • Use uncertainty-verification when the fix depends on exact tool/library behavior.
5. Propose options: Use task-direction-approval (2–3 options + trade-offs).
6. Ask approval if direction changes:
   • REQUIRED SUB-SKILL: Use task-direction-approval when switching library/tool/architecture or replacing automation with manual workaround.
7. Resume only after selecting a plan and (when applicable) verifying it with a small test.

Common mistakes

• Continuing to code while the failure mode is not understood
• Changing direction silently instead of asking for approval
• “Fixing” by adding retries/timeouts without evidence