# /templates — Document Templates

> **When to invoke:** when creating task documentation files
> **Contains:** PRD, RFC, CONTEXT, PLAN, ACTIVE, BRIEF

**Rules:**
- Use templates EXACTLY as written — no improvisation
- **Acceptance criteria for behaviour-bearing work are Gherkin scenarios**, and the `.feature`
  file is the source of truth: the document references the scenario BY NAME and the suite holds
  its text. Non-behavioural work says so, with a reason
- No numbered sections (use `##` / `###` headings)
- Status: always `Draft` / `Approved` / `Done`
- Date in separate field, never inside status

---

## PRD.md — Product Requirements Document

Used for: `epic`, `feature`

```markdown
# PRD: {ISSUE-KEY} — [Name]

> **Status:** Draft
> **Created:** YYYY-MM-DD

---

## Problem

[What is broken / missing / suboptimal. Include evidence and data.]

## Impact

[Who is affected. Why it matters. What happens if we don't fix it.]

## Goals

- [ ] Goal 1 (measurable)
- [ ] Goal 2 (measurable)

## Non-goals

- What is explicitly out of scope

## User Stories

### US-1: [Name]
**As** [role], **I want** [action], **so that** [result].

**Acceptance criteria** (each references a scenario in `tests/acceptance/features/`):
- [ ] Scenario: `<the scenario's exact name>`
- [ ] Scenario: `<the scenario's exact name>`

### US-2: [Name]
**As** [role], **I want** [action], **so that** [result].

**Acceptance criteria** (each references a scenario in `tests/acceptance/features/`):
- [ ] Scenario: `<the scenario's exact name>`
- [ ] Scenario: `<the scenario's exact name>`

## Acceptance Criteria (overall)

Behaviour-bearing criteria are scenarios; the suite holds their text and this list references
them by name. `beadloom lint` reports a referenced scenario the suite does not contain.

- [ ] Scenario: `<the scenario's exact name>`
- [ ] Scenario: `<the scenario's exact name>`

**Non-behavioural criteria** stay checkboxes and are labelled, so the absence of a scenario is
a stated decision rather than a gap:

- [ ] [what is done] — non-behavioural: [why no observer can see a change]
```

### The scenario the criteria reference

```gherkin
@bead:{ISSUE-KEY}.N @node:<ref-id>
Feature: [the capability, in the user's words]

  Scenario: [what an observer can see happen]
    Given [the state the world is in]
    When [the one thing that happens]
    Then [the observable consequence]
```

---

## RFC.md — Technical Specification

Used for: `epic`, `feature`

```markdown
# RFC: {ISSUE-KEY} — [Name]

> **Status:** Draft
> **Created:** YYYY-MM-DD

---

## Overview

[1-2 paragraphs: what we are doing and why]

## Motivation

### Problem
[Current situation and pain points]

### Solution
[How the proposed solution addresses the problem]

## Technical Context

### Constraints
- [Language/runtime constraint — see the STACK section appended below, composed
  from `.beadloom/flow.yml`; the core does not assume a language]
- [Additional constraints specific to this task]

### Affected Areas
[Which domains/services/modules will be touched — discover via `beadloom ctx`]

## Proposed Solution

### Approach
[Description of the chosen approach]

### Changes

| File / Module | Change |
|---------------|--------|
| `path/to/file.py` | Description of change |

### API Changes
[New/changed public interfaces, if any]

## Alternatives Considered

### Option A: [Name]
[Description, pros, cons, why rejected]

## Risks

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Risk 1 | Low/Med/High | Low/Med/High | Action |

## Open Questions

| # | Question | Decision |
|---|----------|----------|
| Q1 | Question? | Pending / Decided: [answer] |
```

---

## CONTEXT.md — Core Memory

Used for: `epic`, `feature`

```markdown
# CONTEXT: {ISSUE-KEY} — [Name]

> **Status:** Draft
> **Created:** YYYY-MM-DD
> **Last updated:** YYYY-MM-DD

---

## Goal

[1-2 sentences: what should be achieved. Immutable after approval.]

## Key Constraints

- [Technical constraint]
- [Business constraint]

## Code Standards

### Language and Environment
- Filled from the STACK section appended below (composed from
  `.beadloom/flow.yml`). Do NOT hardcode a language here: this template ships to
  every adopter, and most of them are not on the one Beadloom happens to use.

### Methodologies

| Methodology | Application |
|-------------|-------------|
| TDD | Red -> Green -> Refactor |
| Clean Code | SRP, DRY, KISS |
| Architecture | see the ARCHITECTURE section appended below (from `.beadloom/flow.yml`) |

### Testing
- **Framework:** see the STACK section appended below
- **Coverage:** minimum 80%

### Code Quality
- **Linter/type-checker:** see the STACK section appended below

### Restrictions
- No unjustified escape hatch from the type system
- No stray debug output — use the language's logging facility
- No catch-all exception handler — name the exception
- Language-specific restrictions: see the STACK section appended below

## Architectural Decisions

| Date | Decision | Reason |
|------|----------|--------|
| YYYY-MM-DD | Decision | Because... |

## Related Files

(discover via `beadloom ctx <ref-id>` — never hardcode)

## Current Phase

- **Phase:** Planning | Development | Review | Done
- **Current bead:** BEAD-XX
- **Blockers:** none
```

---

## PLAN.md — DAG and Beads

Used for: `epic`, `feature`

```markdown
# PLAN: {ISSUE-KEY} — [Name]

> **Status:** Draft
> **Created:** YYYY-MM-DD

---

## Epic Description

[What should be achieved]

## Dependency DAG

```mermaid
graph TD
    B01[BEAD-01 P0] --> B02[BEAD-02 P0]
    B01 --> B03[BEAD-03 P1]
    B02 --> B04[BEAD-04 P0]
```

**Critical path:** BEAD-01 -> BEAD-02 -> BEAD-04

## Beads

| ID | Name | Priority | Depends On | Status |
|----|------|----------|------------|--------|
| BEAD-01 | [Name] | P0 | - | Pending |
| BEAD-02 | [Name] | P0 | 01 | Pending |
| BEAD-03 | [Name] | P1 | 01 | Pending |

## Bead Details

### BEAD-01: [Name]

**Priority:** P0
**Depends on:** -
**Blocks:** BEAD-02, BEAD-03

**What to do:**
[Clear description of the work]

**Done when:**
- [ ] Criterion 1
- [ ] Criterion 2
```

---

## ACTIVE.md — Current Focus

Used for: ALL types

```markdown
# ACTIVE: {ISSUE-KEY} — [Name]

> **Last updated:** YYYY-MM-DD
> **Phase:** Development | Completed

---

## Current Bead

**Bead:** BEAD-XX — [Name]
**Goal:** [what we are doing]
**Done when:** [criterion]

## Progress

- [ ] Step 1: description
- [x] Step 2: description (completed HH:MM)

## Results

| Bead | Status | Details |
|------|--------|---------|
| BEAD-01 | Done | [brief result] |
| BEAD-02 | In Progress | [current state] |

## Notes

[Decisions, blockers, discoveries]
```

---

## BRIEF.md — Simplified Task Document

Used for: `bug`, `task`, `chore`

```markdown
# BRIEF: {ISSUE-KEY} — [Name]

> **Type:** bug | task | chore
> **Status:** Draft
> **Created:** YYYY-MM-DD

---

## Problem

[What is broken / what needs to be done / what needs cleanup]

## Solution

[How we will solve it]

## Beads

| ID | Name | Priority | Status |
|----|------|----------|--------|
| BEAD-01 | [Name] | P0 | Pending |

## Acceptance Criteria

- [ ] Scenario: `<the scenario's exact name>`

## Non-behavioural declaration

Only for a `chore` or a `task` no observer can see the result of. Fill BOTH fields or delete
the section — an exclusion without a stated reason is a check switched off without saying so.

| Node | Reason it carries no behaviour |
|------|-------------------------------|
| [ref-id] | [why no observer can see a change — not a restatement of "it is a chore"] |
```
