Gabriel Radureau
7647a68cdc
Add a root AGENTS.md (ecosystem map of factory/tools/cms + agent operating rules + the persona cohort & workflow) and a new vibe/ knowledge base for LLM agents, modeled on tree-docs conventions and the factory house style. vibe/ folders (each with a README hub + contribution rules): - ADR/ optimized MADR-lite; canonical home going forward (doc/adr stays historical) - PRD/ one subfolder per PRD, mandatory STATUS.md, QA strategy for big ones - investigations/ single INV-NNN-slug.md, or stub + folder w/ notebooks - guidebooks/ tree-docs maps; lab-ecosystem guidebook of factory+tools+cms - runbooks/ [AGENT]/[HUMAN] step procedures (EN; doc/runbooks stays FR) - shareouts/ dated FR handouts (decks/mp4) Seed content (first ADR + PRD): a safe, production-like environment to rehearse risky changes and recovery without touching real prod — local-only sandbox (k3d + arm64 VMs) with a hard prod/sandbox isolation boundary. Includes INV-001 (prod blast-radius couplings), the ecosystem guidebook, and a FR shareout. Conventions enforced: no-tombstone rule, breadcrumb spine, bidirectional cross-links, theme:base mermaid (MCP-validated) + ordered-list-after-diagram. Built with a Workflow + persona cohort; 24 files, zero dead links. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
46 lines
2.7 KiB
Markdown
46 lines
2.7 KiB
Markdown
[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.
|