Files

Gabriel Radureau 7647a68cdc 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>

2026-06-23 11:52:37 +02:00

2.7 KiB

Raw Blame History

vibe > Investigations

Investigations

Status: 🟢 Active Last Updated: 2026-06-23 Related: vibe/ADR · vibe/PRD

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.

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	Prod blast-radius couplings	✅ Complete	2026-06-23

Rules to contribute

Copy _template.md to INV-NNN-slug.md using the next free sequence number and delete the top HTML-comment note.
Fill in the blockquote (Status / Date / Priority / Related), Objectives, Executive summary, Findings (Brief → evidence → Finding each), Summary table, Classification, Open questions, References.
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.
Add a row to the Index table above.
Cross-link any ADR or PRD this investigation informs (and have them link back). Bidirectional links are mandatory.

2.7 KiB Raw Blame History