[vibe](../README.md) > **Investigations**

# Investigations

> **Status**: 🟢 Active
> **Last Updated**: 2026-06-23
> **Related**: [vibe/ADR](../ADR/README.md) · [vibe/PRD](../PRD/README.md)

`vibe/investigations/` collects focused inquiries: a question is asked, evidence is gathered, and findings are recorded. Investigations feed ADRs (a decision often rests on an investigation) and PRDs (scoping rests on what we learned). Start from [`_template.md`](_template.md).

## Convention

- **Prefer a single numbered file** named `INV-NNN-slug.md`. Most investigations need nothing more.
- **When notebooks or data are involved**, keep `INV-NNN-slug.md` as a short **stub** (an origin note + a link) sitting *beside* a same-named folder `INV-NNN-slug/` that holds:
  - notebooks — each `.ipynb` paired with an exported `.py` (so diffs and review work on plain text),
  - a `_data/` directory for inputs/outputs,
  - a `notebook_simple.md` — a plain-language walkthrough (visuals + explanations anyone can follow, no code required).
- **Diagonal-reading style.** Each finding section is written so a skimmer gets the point fast: lead with a one-line **Brief**, then the **evidence**, then a bold **Finding**. A reader can scan the Briefs and Findings alone and still understand the conclusion.
- **No-tombstone rule** applies: write findings as currently true. Corrections are made in place; git history is the audit trail.

## Classification legend

Use these on findings and in the Classification table to signal severity / nature:

| Emoji | Meaning |
| --- | --- |
| 🔴 | Critical — data-loss or breaking risk confirmed |
| 🟠 | Significant — degraded but working, or a real coupling to watch |
| 🟡 | Minor — worth noting, low impact |
| 🟢 | Healthy — verified safe / no issue found |
| 🔵 | Informational — context, no action implied |

## Index

| # | Title | Status | Date |
| --- | --- | --- | --- |
| [INV-001](INV-001-prod-blast-radius-couplings.md) | Prod blast-radius couplings | ✅ Complete | 2026-06-23 |

## Rules to contribute

1. Copy [`_template.md`](_template.md) to `INV-NNN-slug.md` using the next free sequence number and delete the top HTML-comment note.
2. Fill in the blockquote (Status / Date / Priority / Related), Objectives, Executive summary, Findings (Brief → evidence → Finding each), Summary table, Classification, Open questions, References.
3. If the investigation needs notebooks or data, convert the file into a stub and create the matching `INV-NNN-slug/` folder with paired `.ipynb`/`.py`, `_data/`, and `notebook_simple.md`.
4. Add a row to the Index table above.
5. Cross-link any ADR or PRD this investigation informs (and have them link back). Bidirectional links are mandatory.