Investigate

Do NOT proceed to Phase 1 until the user explicitly confirms.

Credential safety: Never log, print, or include API keys in any output, transcript, report, or dialogue. When capturing stdout/stderr, redact any strings that look like API keys or tokens.

Phase 1 — Investigation

Step Extraction

Parse the spec and extract an ordered list of testable steps. Look for:

• API calls with example payloads
• Scripts and CLI commands
• Data pipeline stages (extract, transform, load sequences)
• Success criteria and thresholds (hit rates, confidence scores, expected outputs)
• Validation or smoke test sections

Each step becomes a task:

• Name: Human-readable description (e.g., "Geolocate a dashcam frame with Claude")
• Command or code: The actual thing to run
• Expected outcome: What success looks like, per the spec
• Timeout: 5 minutes default per step
• Dependencies: Which previous steps must succeed first
• Safety check: Review the command before execution — no destructive operations

Safety Review

Before executing any command, check for:

• rm -rf, rm -r, or any recursive deletion
• DROP TABLE, DELETE FROM, or destructive SQL
• git push --force, git reset --hard, or destructive git operations
• Writes to system directories outside the project
• Any command that modifies production infrastructure

If a command looks destructive, skip it, log why, and continue.

Execution

For each step, in dependency order:

1. Log: step number, name, what is about to run
2. Execute the command with a 5-minute timeout
3. Capture: stdout, stderr, response payloads, generated files, wall-clock time
4. Record outcome: success, failure, unexpected result, or timeout
5. Save all artifacts to the investigation directory
6. Estimate cost for this step if possible (API calls made, tokens used)

Failure handling:

• Log the failure with the actual error message
• If the next step does NOT depend on this one: continue
• If the next step DOES depend on this one: skip it and log "skipped: depends on failed step N"
• If a step exceeds its timeout: kill it, log as timeout, continue

Surprise handling — branch and explore: When a step produces a surprising result (unexpected failure, large divergence between expected and actual, two approaches disagreeing wildly), don't just log it and move on. Investigate WHY.

• If two models disagree by a huge margin, dig into what each one saw and why they diverged
• If a result contradicts the spec's expectations, propose what would fix it — try an alternative approach if cheap and fast (e.g., "the VLM guessed coordinates badly — what if we took the business names it read and geocoded them via a Places API instead?")
• If something failed in a way the spec didn't anticipate, note it as a spec gap with a concrete suggestion for how to address it
• Budget: spend up to 2 extra API calls per surprise to explore alternatives. These branching explorations are often the most interesting content for the podcast.

Total timeout: 30 minutes for the entire investigation. If hit, stop execution, generate the report with whatever has completed so far.

Investigation Directory

Create this structure at docs/superpowers/podcasts/<name>-investigation/:

<name>-investigation/
  report.md                    # Structured summary (generated after all steps)
  cost-summary.json            # Total cost breakdown by service
  steps/
    01-<step-slug>/
      command.sh               # What was run
      stdout.txt               # Standard output
      stderr.txt               # Standard error (redacted of credentials)
      artifacts/               # Any generated files
    02-<step-slug>/
      ...

The <name> is derived from the input filename (strip path and extension).

Investigation Report

After all steps complete (or total timeout), generate report.md:

# Investigation Report: <spec name>

**Date:** <today>
**Spec:** <filepath>
**Duration:** <total wall-clock time>

## Summary

- Steps attempted: N
- Succeeded: N
- Failed: N
- Skipped: N
- Timed out: N

## Steps

### 1. <step name>
- **Status:** success | failure | skipped | timeout
- **Duration:** Xs
- **Command:** `<what was run>`
- **Result:** <what happened>
- **Key finding:** <the interesting part>

### 2. <step name>
...

## Surprises

<anything that contradicted the spec's expectations>

## Cost Breakdown

| Service | Calls | Est. Cost |
|---------|-------|-----------|
| ...     | ...   | ...       |
| **Total** |     | **$X.XX** |

## Artifacts Index

| File | Description |
|------|-------------|
| ...  | ...         |

Also generate cost-summary.json:

{
  "total_usd": 0.00,
  "by_service": {
    "service_name": { "calls": 0, "cost_usd": 0.00 }
  },
  "duration_seconds": 0
}

Prior Investigation Awareness

Before generating narration, check for prior investigation reports and podcasts for the same spec:

• Look in docs/superpowers/podcasts/ for existing *-investigation/report.md files matching this spec
• Look for existing transcripts and audio files

If prior investigations exist:

• Read their reports to understand what was already tried and found
• The new podcast REPLACES all prior episodes — it is the single definitive episode
• Incorporate prior findings as baseline knowledge, not as "last time we found..."
• The hosts should present a complete picture: everything discovered across all runs
• Delete or note that prior audio files are superseded (don't delete without asking)

The goal: someone receiving this ONE file gets the full story. No "part 1 of 3." No "as we discussed in the previous episode." One standalone episode with everything.

Phase 2 — Narration

Generate podcast dialogue from ALL investigation results (current run + any prior runs).

Personas

Person A — The investigator. Ran the whole thing, has the results, walks through what happened. Practitioner energy: "when I ran this" and "look at what came back." Gets excited about surprising results. Defends the spec when it was right, roasts it when it was wrong.

Person B — The skeptic. Didn't run it but is reacting to real data. Asks the hard