@imix-js/taproot 0.2.0

package/docs/workflows.md

@@ -0,0 +1,151 @@
+# Workflows
+
+Taproot supports several development patterns. The right starting point depends on where you are: building something new, fixing a bug, joining an existing project, or onboarding a codebase that has no specs yet.
+
+---
+
+## I have an idea or requirement
+
+Use `/tr-ineed` when you have a requirement but aren't sure where it belongs in the hierarchy, or when the requirement is vague and needs sharpening before you can write a spec.
+
+```
+/tr-ineed "users need to be able to export their data as CSV"
+```
+
+The agent classifies the requirement (clear vs. vague), searches the existing hierarchy for near-duplicates, and proposes the right placement. If the requirement is ambiguous or under-specified, it runs a structured discovery conversation — problem, persona, success criteria, scope boundary — before proposing a placement. It then calls `/tr-intent` or `/tr-behaviour` to write the actual document.
+
+If you already know what you want and where it goes, skip `/tr-ineed` and call `/tr-intent` or `/tr-behaviour` directly.
+
+---
+
+## Building a new feature (top-down)
+
+When you're starting from a business goal and working toward code, the typical sequence is:
+
+```
+/tr-intent "users need to reset their password without contacting support"
+/tr-review taproot/password-reset/intent.md
+/tr-decompose taproot/password-reset/
+/tr-implement taproot/password-reset/request-reset/
+taproot coverage --path taproot/password-reset/
+```
+
+1. **`/tr-intent`** — writes `intent.md` with goal, stakeholders, and success criteria. Asks clarifying questions before writing.
+2. **`/tr-review`** — stress-tests the intent: challenges success criteria, surfaces scope ambiguity, flags missing stakeholders. Run this before writing behaviours — it's much cheaper to find gaps at the intent level.
+3. **`/tr-decompose`** — breaks the intent into a set of behaviours (UseCases). Each behaviour covers one observable thing the system does. For each proposed behaviour the agent asks a probing question to validate it's a real, testable system behaviour — not a technical module.
+4. **`/tr-implement`** — for one behaviour at a time: writes the code, writes the tests, creates `impl.md`, and commits using the conventional tag format.
+5. **`taproot coverage`** — shows what's implemented vs. still planned.
+
+---
+
+## Fixing a bug or investigating unexpected behaviour (bottom-up)
+
+When you're starting from code and need to understand what it's supposed to do:
+
+```
+/tr-trace src/auth/password-reset.ts
+/tr-refine taproot/password-reset/request-reset/ "missing rate limit allows spam"
+/tr-implement taproot/password-reset/request-reset/
+```
+
+1. **`/tr-trace`** — navigates from a source file up through impl → behaviour → intent, showing you the full context: why this code exists, what behaviour it implements, what the success criteria are. Also works top-down (intent → impl) and laterally (sibling behaviours).
+2. **`/tr-refine`** — updates the behaviour spec based on what you found. If the bug reveals a gap in the spec (e.g., rate limiting wasn't specified), refine adds it before you fix the code. This keeps the spec honest.
+3. **`/tr-implement`** — re-implements the behaviour with the updated spec as the source of truth.
+
+---
+
+## Onboarding an existing codebase
+
+If your project has working code but no taproot hierarchy, use `/tr-discover` to reverse-engineer one:
+
+```
+/tr-discover
+```
+
+The skill works in phases:
+
+1. **Orient** — reads README, package manifests, and any existing taproot documents to understand the project
+2. **Intents** — proposes top-level business intents one at a time, asking a probing question about each to validate it reflects a real business goal (not just a technical module)
+3. **Behaviours** — for each confirmed intent, reads the source code and proposes use cases as observable system behaviours
+4. **Implementations** — for each confirmed behaviour, identifies source files, tests, and commits, then writes `impl.md`
+
+You confirm each proposed item before anything is written. Discovery can be stopped and resumed at any time — it saves a status file after each confirmed item.
+
+Use the `depth` argument to limit scope: `intents-only` for a quick intent capture session, `behaviours` to stop before writing impl records.
+
+---
+
+## Health check and maintenance
+
+```
+/tr-status
+```
+
+Or via CLI:
+
+```bash
+taproot coverage && taproot check-orphans && taproot sync-check
+```
+
+- **`/tr-status`** — an AI-driven health dashboard: coverage by intent, orphaned files, stale specs, unlinked commits. Produces a prioritized list of what to address next.
+- **`taproot coverage`** — counts implementations vs. planned behaviours across the hierarchy.
+- **`taproot check-orphans`** — finds folders missing their marker files, source files that no impl references, and commits not linked to any impl.
+- **`taproot sync-check`** — detects staleness: source files modified after the `impl.md` was last verified, or specs reviewed after the implementation was completed.
+
+Run these before a release, after a refactor, or when you suspect the specs have drifted from the code.
+
+---
+
+## Keeping specs current after implementation
+
+Implementations teach you things the spec didn't anticipate — edge cases, performance constraints, API quirks. Capture those learnings:
+
+```
+/tr-refine taproot/password-reset/request-reset/ "discovered that the email service has a 10s timeout"
+/tr-promote taproot/password-reset/request-reset/ "all email-sending features are constrained by the 10s timeout"
+```
+
+- **`/tr-refine`** — updates a behaviour spec with post-implementation learnings. Preserves the existing spec structure; only adds or adjusts what changed.
+- **`/tr-promote`** — escalates a finding to the intent level. Use when something discovered during implementation has implications for the business goal itself (e.g., a third-party constraint that affects success criteria).
+
+---
+
+## Before making a significant change
+
+Before editing a behaviour or intent that already has implementations, assess the impact:
+
+```
+/tr-analyse-change taproot/password-reset/intent.md
+```
+
+The skill walks the hierarchy below the artifact and identifies: which implementations would break, which sibling behaviours share preconditions, and what tests would need updating. Run this before refactoring an intent or splitting a behaviour.
+
+---
+
+## Stress-testing a spec
+
+```
+/tr-review taproot/password-reset/request-reset/usecase.md
+/tr-review-all taproot/password-reset/
+```
+
+- **`/tr-review`** — stress-tests a single artifact: challenges assumptions, asks adversarial questions, identifies coverage gaps and contradictions.
+- **`/tr-review-all`** — comprehensive review of an entire subtree: runs validation, checks orphans and staleness, cross-checks every intent criterion against the behaviours below it, and identifies duplication or contradictions across siblings.
+
+Use `/tr-review` on a fresh spec before starting implementation. Use `/tr-review-all` before a release or after significant scope changes.
+
+---
+
+## When you need to think something through
+
+```
+/tr-grill-me
+```
+
+Use `/tr-grill-me` when you want to stress-test a plan or design before committing it to a spec. The agent interviews you relentlessly — one decision branch at a time, always providing a recommended answer — until you've worked through every significant trade-off. Use it when:
+
+- You have a rough idea for an architecture and want to pressure-test it
+- You're about to write an intent for a domain you don't fully understand yet
+- You want to surface assumptions before they become bugs
+
+`/tr-grill-me` is a conversation, not a document. It produces a decision summary at the end, which you can use as input to `/tr-intent` or `/tr-behaviour`.

package/languages/de.json

@@ -0,0 +1,20 @@
+{
+  "Goal": "Ziel",
+  "Actor": "Akteur",
+  "Preconditions": "Vorbedingungen",
+  "Main Flow": "Hauptablauf",
+  "Alternate Flows": "Alternative Abläufe",
+  "Postconditions": "Nachbedingungen",
+  "Error Conditions": "Fehlerfälle",
+  "Acceptance Criteria": "Akzeptanzkriterien",
+  "Status": "Status",
+  "Stakeholders": "Stakeholder",
+  "Success Criteria": "Erfolgskriterien",
+  "Given": "Gegeben",
+  "When": "Wenn",
+  "Then": "Dann",
+  "specified": "spezifiziert",
+  "implemented": "implementiert",
+  "complete": "vollständig",
+  "active": "aktiv"
+}

package/languages/en.json

@@ -0,0 +1,20 @@
+{
+  "Goal": "Goal",
+  "Actor": "Actor",
+  "Preconditions": "Preconditions",
+  "Main Flow": "Main Flow",
+  "Alternate Flows": "Alternate Flows",
+  "Postconditions": "Postconditions",
+  "Error Conditions": "Error Conditions",
+  "Acceptance Criteria": "Acceptance Criteria",
+  "Status": "Status",
+  "Stakeholders": "Stakeholders",
+  "Success Criteria": "Success Criteria",
+  "Given": "Given",
+  "When": "When",
+  "Then": "Then",
+  "specified": "specified",
+  "implemented": "implemented",
+  "complete": "complete",
+  "active": "active"
+}

package/languages/es.json

@@ -0,0 +1,20 @@
+{
+  "Goal": "Objetivo",
+  "Actor": "Actor",
+  "Preconditions": "Precondiciones",
+  "Main Flow": "Flujo Principal",
+  "Alternate Flows": "Flujos Alternativos",
+  "Postconditions": "Postcondiciones",
+  "Error Conditions": "Condiciones de Error",
+  "Acceptance Criteria": "Criterios de Aceptación",
+  "Status": "Estado",
+  "Stakeholders": "Partes Interesadas",
+  "Success Criteria": "Criterios de Éxito",
+  "Given": "Dado",
+  "When": "Cuando",
+  "Then": "Entonces",
+  "specified": "especificado",
+  "implemented": "implementado",
+  "complete": "completo",
+  "active": "activo"
+}

package/languages/fr.json

@@ -0,0 +1,20 @@
+{
+  "Goal": "Objectif",
+  "Actor": "Acteur",
+  "Preconditions": "Préconditions",
+  "Main Flow": "Flux Principal",
+  "Alternate Flows": "Flux Alternatifs",
+  "Postconditions": "Postconditions",
+  "Error Conditions": "Conditions d'Erreur",
+  "Acceptance Criteria": "Critères d'Acceptation",
+  "Status": "Statut",
+  "Stakeholders": "Parties Prenantes",
+  "Success Criteria": "Critères de Succès",
+  "Given": "Étant donné",
+  "When": "Quand",
+  "Then": "Alors",
+  "specified": "spécifié",
+  "implemented": "implémenté",
+  "complete": "complet",
+  "active": "actif"
+}

package/languages/ja.json

@@ -0,0 +1,20 @@
+{
+  "Goal": "目標",
+  "Actor": "アクター",
+  "Preconditions": "前提条件",
+  "Main Flow": "メインフロー",
+  "Alternate Flows": "代替フロー",
+  "Postconditions": "事後条件",
+  "Error Conditions": "エラー条件",
+  "Acceptance Criteria": "受け入れ基準",
+  "Status": "ステータス",
+  "Stakeholders": "ステークホルダー",
+  "Success Criteria": "成功基準",
+  "Given": "前提として",
+  "When": "実行時",
+  "Then": "結果として",
+  "specified": "指定済み",
+  "implemented": "実装済み",
+  "complete": "完了",
+  "active": "アクティブ"
+}

package/languages/pt.json

@@ -0,0 +1,20 @@
+{
+  "Goal": "Objetivo",
+  "Actor": "Ator",
+  "Preconditions": "Pré-condições",
+  "Main Flow": "Fluxo Principal",
+  "Alternate Flows": "Fluxos Alternativos",
+  "Postconditions": "Pós-condições",
+  "Error Conditions": "Condições de Erro",
+  "Acceptance Criteria": "Critérios de Aceitação",
+  "Status": "Status",
+  "Stakeholders": "Partes Interessadas",
+  "Success Criteria": "Critérios de Sucesso",
+  "Given": "Dado",
+  "When": "Quando",
+  "Then": "Então",
+  "specified": "especificado",
+  "implemented": "implementado",
+  "complete": "completo",
+  "active": "ativo"
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@imix-js/taproot",
+  "version": "0.2.0",
+  "description": "Folder-based requirement hierarchy with CLI validation and AI skills",
+  "type": "module",
+  "bin": {
+    "taproot": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "languages/",
+    "docs/",
+    "README.md"
+  ],
+  "keywords": [
+    "requirements",
+    "traceability",
+    "cli",
+    "ai",
+    "specs",
+    "documentation"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "node --import tsx/esm src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/imix/taproot"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inquirer/checkbox": "^5.1.2",
+    "@inquirer/confirm": "^6.0.10",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.5.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/skills/analyse-change.md

@@ -0,0 +1,101 @@
+# Skill: analyse-change
+
+## Description
+
+Analyse the impact of a proposed change to an existing hierarchy artefact before any edits are made. Identifies what is currently in place, which sections the change affects, and what downstream and upstream artefacts will need review. Produces an impact report and gates on caller confirmation. Read-only — never modifies the hierarchy.
+
+## Inputs
+
+- `path` (required): Path to the existing artefact being changed (`intent.md`, `usecase.md`, or `impl.md`).
+- `change` (required): Natural language description of the proposed change.
+
+## Steps
+
+1. **Verify the target exists.** If the path does not exist, report: "No artefact found at `<path>`. If you're adding something new, use `/tr-ineed` instead." Then stop.
+
+2. **Read the target artefact.** Identify its type (intent / behaviour / implementation) by filename.
+
+3. **Confirm interpretation.** State which sections and fields you believe the change affects:
+   > "I interpret this change as affecting: [list of sections — e.g., Goal, Success Criteria, Main Flow step 3]. Is that right?"
+
+   Wait for confirmation. If the caller corrects the interpretation, update your understanding and re-confirm before continuing.
+
+4. **Check scope.** If the change only affects status, dates, or notes fields — report: "This is a minor update (status/date/notes only) — no impact analysis needed." Then stop.
+
+5. **Build the hierarchy map.** Run `taproot coverage --format json` and parse the output to get the full intent → behaviour → implementation tree.
+
+6. **Walk for dependencies** using three methods:
+
+   **Structural** (definitive):
+   - If target is an `intent.md`: all behaviours and their implementations are downstream
+   - If target is a `usecase.md`: its parent intent is upstream; all its `impl.md` files are downstream
+   - If target is an `impl.md`: its parent `usecase.md` and grandparent `intent.md` are upstream
+
+   **Implementing** (definitive):
+   - Scan all `impl.md` files in the hierarchy for a `## Behaviour` field referencing the changed `usecase.md`
+   - These are direct implementing dependents
+
+   **Conceptual** (advisory — agent reasoning):
+   - Identify 3–5 key terms from the changed sections (actor names, capability phrases, postcondition states)
+   - Scan other `intent.md` and `usecase.md` files for these terms
+   - Flag matches as "possibly affected — review recommended", not confirmed impact
+
+7. **Classify every found artefact:**
+   - **Direct** — the target itself
+   - **Downstream** — structural children or implementing impls
+   - **Upstream** — structural parents
+   - **Possibly affected** — conceptual matches
+
+8. **Present the impact summary:**
+
+   ```
+   ## Change Impact Report
+   Target: <path>
+   Change: <summary of proposed delta>
+
+   ### Current State
+   <key fields being changed, quoted from the artefact>
+
+   ### Proposed Delta
+   <what changes>
+
+   ### Confirmed Impact
+   Downstream:
+   - taproot/<path> [behaviour/impl — reason]
+   Upstream:
+   - taproot/<path> [intent — reason]
+
+   ### Possibly Affected (review recommended)
+   - taproot/<path> — shares term "<term>" in <section>
+
+   ### Next Step
+   [A] Proceed with full scope   [N] Narrow the change   [C] Cancel
+   ```
+
+9. **Gate on confirmation:**
+   - **[A] Proceed**: return the impact report as context and indicate the caller may now make edits. Then:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+     **What's next?**
+     [A1] `/tr-refine <path>` — apply the change to the behaviour spec
+     [A2] `/tr-intent <path>` — revise the intent if upstream is affected
+
+   - **[N] Narrow**: ask "What would you like to change about the proposed delta?" then return to Step 3 with the revised description
+   - **[C] Cancel**: report "No changes made." and stop
+
+## Output
+
+An impact report presented in the conversation, followed by a confirmed go/no-go for the calling skill to proceed with edits. No files are written unless the caller explicitly requests the report saved to `.taproot/change-analysis.md`.
+
+## CLI Dependencies
+
+- `taproot coverage`
+
+## Notes
+
+- This skill is read-only. It reports impact; it does not apply changes.
+- Conceptual matching (Step 6) is agent reasoning, not a deterministic algorithm — it may miss indirect dependencies or flag false positives. Treat "possibly affected" as a prompt for human review, not a definitive list.
+- This skill is typically called by other skills (`tr-intent` in refine mode, `tr-refine`, `tr-promote`, `tr-ineed` when detecting a change) rather than directly by the user. Direct invocation is also valid.
+- Concurrent invocations are not protected by any locking mechanism. In parallel agent pipelines, external coordination is required.
+- `/tr-analyse-change` is the Claude Code adapter command name for this skill.

package/skills/behaviour.md

@@ -0,0 +1,179 @@
+# Skill: behaviour
+
+## Description
+
+Define a UseCase (observable system behaviour) under an intent or another behaviour. Each behaviour is testable, has a clear actor, and describes what the system does — not how it does it.
+
+## Inputs
+
+- `parent` (required): Path to the parent intent folder or parent behaviour folder.
+- `description` (required): Natural language description of the behaviour to define.
+
+## Steps
+
+1. Read the parent artifact at `parent`:
+   - If `parent` contains `intent.md`: read the intent to understand the goal and success criteria.
+   - If `parent` contains `usecase.md`: read the parent behaviour — this new behaviour is a sub-behaviour.
+
+1a. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the behaviour description for semantic matches. Match signals:
+   - "apply to all / every implementation / every skill" → `check-if-affected-by`
+   - "enforce a rule / architectural constraint / agents should follow" → `check-if-affected-by`
+   - "keep docs current / enforce documentation quality" → `document-current`
+   - "every new feature must update X" → `check-if-affected: X`
+
+   If a match is found, **interrupt before asking clarifying questions**:
+   > "Before I write this spec — that sounds like the **`<pattern-name>`** pattern. <one-line description>. See `.taproot/docs/patterns.md`."
+   > **[A] Use this pattern now** — I'll guide you through applying it instead of writing a spec
+   > **[B] Continue writing the spec** — the spec is distinct from the pattern
+
+   - **[A]**: guide the user through applying the pattern. Do not write a new `usecase.md`.
+   - **[B]** or no match: proceed to step 2.
+
+2. Read all sibling `usecase.md` files (other behaviours already under the same parent). Identify any overlap with the described behaviour and flag it: "There's an existing behaviour `<slug>` that covers X — should this new behaviour focus on Y specifically?"
+
+3. Ask clarifying questions through dialogue until you have enough to write the full UseCase. Minimum required:
+   - Who or what initiates this behaviour? (the Actor)
+   - What must be true before this can happen? (Preconditions)
+   - Walk me through the main steps — what does the user/system do, and what does the system respond?
+   - What's true when it succeeds? (Postconditions)
+   - What can go wrong, and how should the system respond? (Error Conditions)
+
+4. Identify alternate flows and error conditions proactively — don't just ask for them. Walk every step in the main flow and challenge it:
+   - "What if the input at this step is invalid or missing?"
+   - "What if an external call here times out or returns an error?"
+   - "What if the user navigates away or cancels mid-flow?"
+   - "What if this step is attempted twice in a row?"
+   Each recoverable branch becomes an **Alternate Flow** (with trigger + steps + outcome). Each unrecoverable failure becomes an **Error Condition** (with trigger + system response). Do not accept vague answers like "the request fails" — push for the specific trigger and the exact system response (e.g., "API returns 5xx — system shows inline error, preserves form state, and allows retry").
+
+5. Generate a Mermaid diagram that visualises the main flow and key alternate/error branches. Use `sequenceDiagram` for actor–system interactions or `flowchart TD` for branching logic — choose whichever makes the flow most readable. This is the human-readable visual contract for the behaviour. Include it in the `## Flow` section of `usecase.md`.
+
+6. Identify related behaviours. Scan sibling and parent behaviours for any that: share the same actor, share a precondition with this behaviour, produce an outcome this behaviour depends on, or are commonly triggered alongside this one. List them in `## Related` with a one-line note on the relationship (e.g., "must precede", "shares actor", "produces input for this flow").
+
+7. Draft the `usecase.md`. Write main flow steps as active-voice actions: subject + verb + object. Bad: "The form is submitted." Good: "User submits the registration form."
+
+7a. After writing the main flow, alternate flows, and error conditions, generate a `## Acceptance Criteria` section. Derive one Gherkin scenario per flow: the main flow, each named alternate flow, and each error condition. Assign stable IDs starting at `AC-1`. Insert the section immediately before `## Status`:
+
+   ```markdown
+   ## Acceptance Criteria
+
+   **AC-1: <Happy path title>**
+   - Given <precondition>
+   - When <actor action>
+   - Then <observable outcome>
+
+   **AC-2: <Alternate flow title>**
+   - Given <context>
+   - When <trigger>
+   - Then <system response>
+   ```
+
+   Note to developer: "I've generated N acceptance criteria — review and adjust the Given/When/Then wording before committing. IDs are immutable once assigned."
+
+7b. After generating functional ACs, ask: "Are there quality constraints on this behaviour — performance targets, security requirements, reliability thresholds, or accessibility standards?" If yes, derive one `**NFR-N:**` entry per constraint using the NFR Gherkin pattern:
+   - **Given** — the environmental or load condition (e.g. "500 concurrent users", "mobile network", "authenticated session")
+   - **When** — the actor action that triggers measurement
+   - **Then** — a measurable threshold: number + unit, named standard, or testable boolean condition
+
+   Assign IDs starting at `NFR-1`, placed after the last functional AC. Note: "I've generated N NFR criteria — confirm the thresholds are specific and measurable before committing."
+
+   If no quality constraints are identified, skip silently.
+
+8. Determine the folder slug: kebab-case, verb-noun or noun phrase (e.g., `register-account`, `reset-password`, `verify-email-address`). Should be distinct from sibling behaviour slugs.
+
+9. Create the directory `<parent>/<slug>/` and write `usecase.md`.
+
+10. Update the parent document's `## Behaviours <!-- taproot-managed -->` section:
+    - Read the parent `intent.md` (or parent `usecase.md` for sub-behaviours).
+    - If the `## Behaviours` section does not exist, insert it immediately before `## Status` (or append at end of file if `## Status` is absent), with the heading `## Behaviours <!-- taproot-managed -->`.
+    - Derive the link title from the first `# Heading` line of the new `usecase.md`; strip any type prefix (e.g. `# Behaviour: Foo` → `Foo`). Fall back to the folder slug if no heading is found.
+    - Append `- [<Title>](./<slug>/usecase.md)` to the section if the link is not already present.
+    - Write the updated parent document.
+
+11. Run `taproot validate-structure --path <taproot-root>` and `taproot validate-format --path <parent>/<slug>/`.
+
+12. If the behaviour has clear sub-components, suggest decomposition: "This behaviour has three distinct phases — would you like to break it into sub-behaviours: `<sub-slug-1>`, `<sub-slug-2>`, `<sub-slug-3>`?"
+
+13. Present next steps:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-implement taproot/<parent>/<slug>/` — start building
+   [B] `/tr-review taproot/<parent>/<slug>/usecase.md` — stress-test the spec first
+
+## Output
+
+A new `usecase.md` in `<parent>/<slug>/usecase.md`.
+
+## CLI Dependencies
+
+- `taproot validate-structure`
+- `taproot validate-format`
+
+## Document Format Reference
+
+```markdown
+# Behaviour: <Title>
+
+## Actor
+<Who or what initiates this behaviour>
+
+## Preconditions
+- <What must be true before this behaviour can occur>
+
+## Main Flow
+1. <Actor does something>
+2. <System responds>
+3. <Actor does something>
+
+## Alternate Flows
+### <Alternate flow name>
+- **Trigger:** <When does this alternate flow occur?>
+- **Steps:**
+  1. <Step>
+  2. <Step>
+
+## Postconditions
+- <What is true after successful completion>
+
+## Error Conditions
+- **<Trigger>**: <Exact system response — specific, not generic>
+
+## Flow
+```mermaid
+sequenceDiagram
+    Actor->>System: <initiating action>
+    System-->>Actor: <response>
+```
+
+## Related
+- `<path/to/sibling/usecase.md>` — <relationship: must precede / shares actor / produces input / commonly co-triggered>
+
+## Acceptance Criteria
+
+**AC-1: <Happy path title>**
+- Given <precondition>
+- When <actor action>
+- Then <observable outcome>
+
+**AC-2: <Alternate flow title>**
+- Given <context>
+- When <trigger>
+- Then <system response>
+
+## Status
+- **State:** proposed | specified | implemented | tested | deprecated
+- **Created:** <YYYY-MM-DD>
+- **Last reviewed:** <YYYY-MM-DD>
+
+## Notes
+<Edge cases, open questions>
+```
+
+## Notes
+
+- A behaviour should be completable in one user session. If it spans sessions or days, it is likely multiple behaviours.
+- Aim for 3–7 steps in the main flow. Fewer usually means the behaviour is too abstract; more usually means it should be decomposed.
+- The Mermaid diagram is the human-readable contract — it should be understandable by a non-technical stakeholder. Prefer `sequenceDiagram` for flows with clear actor–system turns; use `flowchart TD` for decision-heavy branching.
+- Error conditions should be specific: name the exact trigger (HTTP 5xx, timeout, duplicate key) and the exact system response (error message shown, state preserved, retry offered). Vague conditions ("request fails") are not acceptable.
+- Related behaviours are not just cross-references — they define the dependency graph that `/tr-analyse-change` uses for impact analysis.