capsule

# Concept Capsule Create a **concept capsule** — a short, precise document that anchors all subsequent work to a shared vocabulary (ubiquitous language, DDD) and a set of constraints (design by contract). The capsule is the durable semantic authority for a project or feature area. It should change slowly after initial establishment. ## Authority boundary Use the capsule for durable conceptual truths only: - Glossary terms and boundaries - Invariants/laws - One concrete happy path - Permanent non-goals Do **not** use the capsule for: - Phase status, candidate sequencing, or temporary deferments (milestone owns) - Confidence tracking or uncertain hypotheses (assumptions ledger owns) - Decision history with rationale/evidence chronology (roadmap/decisions own) ## Input The project or feature area: $ARGUMENTS If the user hasn't described the domain clearly enough, interview them: 1. What is this thing? (one sentence) 2. What are the key concepts / nouns / entities? 3. What rules must always hold? (invariants) 4. What is the simplest thing it should do? (happy path) 5. What should it explicitly *not* do? (non-goals) ## Output: The Capsule Write a document with exactly these four sections. Keep it to **one screen** (~250-500 words). Each bullet should be **one sentence**. ### 1. Glossary (Ubiquitous Language) 5-15 domain terms with their **exact intended meanings** in this project. These are the names that must appear in code — types, functions, modules, test suites. Format: ``` - **Term**: Definition (one sentence) ``` - If two terms could be confused, clarify the boundary - Every term should eventually have a code home (type, module, function, or test suite) - If you need more than ~15 terms, split into project capsule + feature capsule(s) ### 2. Invariants / Laws 3-10 statements that **must always be true**. Constraints, not features. Format: ``` - An X must always have a Y - X can never be Z while W is true ``` - Each invariant should be testable - Decide where each lives: type system (best), constructor/validator (good), or tests (minimum) - If an invariant can't be stated clearly, the concept isn't understood yet — stop and clarify ### 3. Happy Path (one scenario) A single concrete **input → output** story. This becomes the first integration test. Format: ``` Given: [concrete starting state] When: [concrete action] Then: [concrete observable result] ``` Must be specific ("Given a file `post.md` with front-matter...", not "Given some input..."). ### 4. Non-Goals (exactly two) Two things this project or feature **explicitly will not do**. These prevent scope creep and stop the agent from "helpfully" adding features. Format: ``` - This will NOT do X (because Y) - This will NOT do Z (because W) ``` These are deliberate exclusions, not "not yet" items. ## Capsule change policy Update a capsule when one of these is true: - A glossary term is ambiguous, conflicting, or missing - An invariant is proven wrong, incomplete, or unverifiable - The happy path no longer reflects the first integration scenario - A non-goal is no longer a durable exclusion Do not append changelogs, progress logs, milestone status, or decision journals inside the capsule. When an assumption stabilizes into a durable law, promote it from `docs/assumptions.md` into capsule invariants and track enforcement via `/pragma:contract`. ## Where to put it - `docs/capsule.md` for project-level - `docs/capsule-<feature>.md` for feature-level - If a capsule already exists, update it — don't create a second one ## Validation After writing, check: 1. Can every glossary term map to a code construct? 2. Can every invariant be tested? 3. Is the happy path specific enough to be an integration test? 4. Do the non-goals clearly exclude something the agent might otherwise build? 5. Does the document avoid milestone status, assumption confidence, and historical decision logs? If any check fails, revise before proceeding. ## Lifecycle tail (required) Append to the response: - **State**: `foundation` - **Next**: `/pragma:skeleton` - **Loop**: `/pragma:consult` (default unless user explicitly continues directly)