dig git:20260918.7a11459A

Immutable. This exact content never changes and is served at /api/v1/blob/7b3e98d2de0e4beb.

---
name: dig
description: systematic investigation and debugging methodology. hypothesis-driven analysis with verification agents. use for incident response, codebase archaeology, dependency mapping, root cause analysis, or any investigation requiring verified findings.
---

# dig

structured approach to investigations that produces verified, actionable findings.

**load first:** `review` — provides epistemic standards (trace or delete, label confidence, falsify don't confirm). dig assumes these are active.

## core principles

1. **trust code over assumptions** — never assume intent. check git history.
2. **scripts > docs** — extraction scales, documentation doesn't.
3. **bidirectional analysis** — traverse dependencies forward AND reverse.
4. **autonomous discovery** — use seeds and graph traversal, don't hardcode.

## investigation phases

### phase 1: map

scope the problem. identify seeds (entry points) for traversal.

```
1. define the question precisely
2. identify seed artifacts (files, functions, types, API endpoints)
3. choose traversal strategy:
   - reverse: seed → importers → consumers (finds affected scope)
   - forward: seed → dependencies → leaves (finds implementation details)
   - bidirectional: both (complete picture)
4. extract, don't document — write scripts that produce structured output
```

when to check git:

- `git blame <file>` — who wrote this line? when? why?
- `git log -p --follow -- <file>` — full history of a file
- `git log --all --oneline -- <path>` — find when something was introduced
- `git log --grep="<term>"` — find commits mentioning a concept

### phase 2: verify

spawn verification agents to fact-check analysis claims; to avoid confirmation bias, use neutral claims, or invert your question: instead of asking what you believe, ask the opposite.

```
for each major claim:
  1. spawn a verification agent with ONLY the claim + file paths
  2. agent must independently confirm or refute
  3. record: VERIFIED, REFUTED, or INCONCLUSIVE
```

verification agent prompt template:

```
verify this claim: "<claim>"
files to check: <file list>
do not assume the claim is correct.
check the actual code and report what you find.
```

anti-patterns:

- trusting oracle/LLM statements without code verification
- assuming wrapper names without grep confirmation
- documenting before extracting

### phase 3: synthesize

structure findings for consumption.

**tables** for enumeration:
| location | code | effect |
|----------|------|--------|

**trees** for relationships:

```
RootComponent
├── ChildA → uses Feature
└── ChildB
    └── GrandchildC → also uses Feature
```

**appendices** for exhaustive lists (don't clutter main findings).

## output structure

```markdown
# <investigation title>

## summary

one paragraph. what did we find?

## context

why are we investigating? link to trigger (slack, ticket, etc.)

## findings

### 1. <finding title>

<evidence with file links>
<code snippets>

### 2. <finding title>

...

## open questions

numbered list of things we couldn't verify

## appendices

- [detailed-list-a.md](./detailed-list-a.md)
- [detailed-list-b.md](./detailed-list-b.md)

## related threads

table of source links with descriptions (URLs, tickets, prior write-ups)
```

## verification agent pattern

when coordinating investigation:

```
1. spawn analysis agents (stores, routes, components, etc.)
   - each produces claims with file:line citations

2. collect claims from all analysis agents

3. spawn verification agents (1 per analysis agent)
   - input: claims + file paths only
   - output: VERIFIED/REFUTED/INCONCLUSIVE for each claim

4. synthesizer combines verified claims into report
```

## autonomous discovery

never hardcode component lists. instead:

```bash
# start from seeds
SEEDS=$(grep -rl "import.*from.*deprecated-lib" --include="*.ts")

# build import graph
for seed in $SEEDS; do
  # find importers (reverse)
  grep -rl "import.*from.*$seed" --include="*.ts"

  # find imports (forward)
  grep "^import" "$seed" | extract_paths
done
```

bidirectional traversal discovers components you didn't know existed.

## references

- [AXM-10608-investigation-report.md](references/AXM-10608-investigation-report.md) — multi-dataset assumption mapping
- [2025-10-22T21-50-process-summary.md](references/2025-10-22T21-50-process-summary.md) — rc-menu dependency discovery evolution