readme-writinglisted

# README Writing A folder README is not a table of contents. It is the mental model a developer or agent needs before touching anything in that folder. A README that only lists files is worse than none -- it creates the impression the folder is understood when it is not. Gaia is event-driven. Every component has a trigger: a hook fires, a skill is injected, a command is dispatched, a config file is loaded. A README that does not explain WHEN and HOW a component activates leaves the reader guessing the most important thing. ## Step 1: Choose your target Write or update a README when: - A new folder is created (agents/, skills/<name>/, hooks/, etc.) - You add a file that changes what the folder does or when it activates - A drift report in `cross_layer_impacts` flags a README as stale ## Step 2: Write the 5 sections in order Every README uses this structure. Order is not optional -- a reader skimming top-to-bottom should understand activation before they see a file tree. **Section 1: Intro narrative** (2-4 paragraphs, no bullets, conversational) - One sentence on what lives here - Why this folder exists separately (the conceptual contract) - How to think about this folder (mental model or analogy) - Who touches it: developer, agent at runtime, CI, admin **Section 2: When activated** (the core -- do not skip) - The concrete trigger: what event, condition, or code path fires this - ASCII diagram if more than 2 steps chain together - Step-by-step list as complement when th