docs(vibe): bootstrap vibe/ knowledge tree + ecosystem AGENTS.md

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>
This commit is contained in:
2026-06-23 11:52:37 +02:00
parent 827af6b392
commit 7647a68cdc
25 changed files with 1878 additions and 0 deletions

View File

@@ -0,0 +1,45 @@
[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.