workout-app / rules

---
description: Document templates for Epic Briefs, Tech Plans, and Tickets. Enforces consistent structure across all project documentation.
globs: docs/**/*.md
alwaysApply: false
---

# Document Templates

All docs in `docs/` follow one of three templates. Use the exact heading structure, separators, and conventions shown below.

## Naming Convention

- Underscores for spaces, em dash (`—`) as separator
- Epic Briefs: `Epic_Brief_—_{Title}.md`
- Tech Plans: `Tech_Plan_—_{Title}.md`
- Tickets: `T{n}_—_{Title}.md`
- Completed docs go in `docs/done/`

## File references

Use `file:path/to/file.ts` for codebase file references within docs.

---

## Epic Brief Template

```markdown
# Epic Brief — {Title}

## Summary

One paragraph: what this epic delivers, why it matters, what changes for the user.

---

## Context & Problem

**Who is affected:** ...

**Current state:**
- Bullet points describing the status quo and its limitations

**Pain points:**
| Pain | Impact |
|---|---|
| ... | ... |

---

## User Stories

A numbered list of user stories in the format `As a <persona>, I want <capability>, so that <outcome>`. Be exhaustive — cover every aspect of the feature, including edge-of-flow behaviors (errors, empty states, offline). Each story is independently verifiable and becomes a target for ticket acceptance criteria.

1. As a `<persona>`, I want `<capability>`, so that `<outcome>`.
2. ...

### Success measures

For the few stories that need a measurable threshold (performance, adoption, conversion), add a measure inline:

| Story # | Measure |
|---|---|
| 3 | p95 < 200ms on mid-tier mobile |
| 7 | >=80% of users complete the flow within 2 sessions |

Stories without a numeric measure are validated qualitatively via the user story itself.

---

## Scope

**In scope:**
- Numbered or bulleted list of features/workstreams

**Out of scope:**
- What is explicitly deferred

---

## Success Criteria

Aggregate, epic-level criteria — not per-story. Use these to decide "is the epic done":

- **Numeric:** measurable threshold (e.g. ">=95% of X within Y")
- **Qualitative:** user-observable outcome covering multiple stories
```

---

## Tech Plan Template

```markdown
# Tech Plan — {Title}

## Architectural Approach

### Key Decisions

| Decision | Choice | Rationale |
|---|---|---|
| ... | ... | ... |

### Critical Constraints

Paragraphs describing hard constraints, side effects, and coupling risks. Reference specific files with `file:path`.

---

## Data Model

Mermaid ER/class diagrams + table notes. Include schema snippets (SQL, TypeScript types, localStorage shapes) where relevant.

```mermaid
classDiagram
    ...
```

### Table Notes

Explain non-obvious design choices per entity.

---

## Component Architecture

### Layer Overview

Mermaid graph showing component hierarchy.

```mermaid
graph TD
    ...
```

### New Files & Responsibilities

| File | Purpose |
|---|---|
| ... | ... |

### Component Responsibilities

`**ComponentName**`
- Bullet points describing what it does, what it reads/writes, what it delegates to

### Failure Mode Analysis (if applicable)

| Failure | Behavior |
|---|---|
| ... | ... |

---

## i18n contract

Omit only when the epic adds no user-facing strings. Produced by the `microcopy` skill. Tickets copy these values — they do not invent new wording.

**Namespace:** `…`

| Key | EN | FR | Why this wording |
|---|---|---|---|
| `…` | … | … | … |
```

---

## Ticket Template

```markdown
# T{n} — {Title}

## Goal

One paragraph: what this ticket delivers and why.

## Dependencies

Which tickets or systems must be in place before this one.

## Scope

### {Sub-section per workstream}

Detailed description with tables, code snippets, config examples as needed.

| Item | Detail |
|---|---|
| ... | ... |

## Out of Scope

- Bulleted list of what this ticket explicitly does NOT cover

## Acceptance Criteria

- [ ] Checkbox-style criteria, each independently verifiable
- [ ] ...

## References

- Links to Epic Brief, Tech Plan, and any relevant specs
```