Documentation

# [Module Name] Bug Report Title

## Problem and Context
(description of the end users issue, significance, and background)

## Module(s)
<Primary module(s) from artefacts/module-registry/modules.md where this bug occurs>

## Submodule(s)
<Specific submodule(s)/feature area(s) within the module(s) above. Also flag any additional module(s) likely impacted as a dependency, marked "(suggested — dependency)">

### Expected Behaviour

### Actual Behaviour

## How to Reproduce

### Preconditions (including roles tested, specific data point if any, or other)

## Checklist
(fixes required for this — restrict only to relevant steps)
- [ ] Item to fix 1
- [ ] Item to fix 2
- [ ] Item to fix 3

## Instances Tested
(If the input mentions instances, check them off here. If not, ignore this section.)
- [ ] Development
- [ ] Staging
- [ ] Demo
- [ ] Production

## Media (Including JAM.dev or video links if any)

# [Module Name] Feature Title
<prefix with the primary module name in square brackets, then a compact feature title>

## Summary
Clear explanation of why this is important to build and what value it brings.

## Problem & Context
<description of the users pain points and how this solution will help>

## User Story
As a [user], I want this [functionality] so that I can achieve this [benefit].

## Module(s)
<Primary module(s) from artefacts/module-registry/modules.md that this change affects>

## Submodule(s)
<Specific submodule(s)/feature area(s) within the module(s) above. Also flag any additional module(s) likely impacted as a dependency, marked "(suggested — dependency)">

## In Scope Checklist
- [ ] Item 1
- [ ] Item 2

## Out of Scope
(placeholder)

## Acceptance Criteria (QA Team)
(placeholder)

## Technical Notes (Dev Team)
(placeholder)

## Source Request URL (e.g. your issue tracker, Slack, email)
(placeholder)

# AI Feature Title

## Summary
What the AI feature does and the value it delivers.

## Problem & Context
What the user is currently doing manually, and why AI is the right solution.

## User Story
As a [user], I want [AI capability] so that [benefit].

## Input Data
What data the model receives as context (fields, records, history).

## Prompt(s)
```
System: {system prompt}
User: {user prompt template}
```

## Models & Fallback
Primary: {model}  |  Fallback: {model}

## Acceptance Criteria
- AC-01: {Observable, testable AI output outcome}

# Business Requirements Document (BRD)

> **Status:** DRAFT | IN REVIEW | APPROVED
> **Artefact ID:** `{YYYY-MM-DD}-{product-slug}-BRD`
> **Scope:** {Whole product — or the named module(s) this document covers}
> **Author:** Claude (AI) — **Verified by:** {Name / Role}

---

## 1. Overview
{Two or three sentences in plain English: what the product is, who it
serves, and the outcome it delivers.}

---

## 2. Who

### 2.1 Roles

| Role | Who they are | What they use the product for | Modules |
| --- | --- | --- | --- |

---

## 3. Why

### 3.2 Objectives

| # | Objective | Why it matters | How we know it worked |
| --- | --- | --- | --- |
| OBJ-01 | | | |

---

## 4. What

### 4.1 {Module Name} — {New | Existing}

**Purpose:** {One sentence — what this module does for the people who use it.}
**Used by:** {Roles from Section 2.}

**Features:**
- {Feature name} — {one line: what the user can do, and what they get.}

> Features are listed at capability level only. No field lists, rules, or
> acceptance criteria — those belong in the module's PRD and its CRs.

# Product Requirements Document (PRD)

> **Status:** DRAFT | IN REVIEW | APPROVED
> **Artefact ID:** `{YYYY-MM-DD}-{module-slug}-PRD`
> **Module:** {Module Name} (or named group of modules)
> **Version:** {e.g. 1.0}

---

## 1. Module Summary
{What this module does today, who uses it, and its scope within the product.}

---

## 2. Source Change Requests

| CR | Summary | Date |
|----|---------|------|
| [{CR title}]({relative path}) | {What it added or changed} | {YYYY-MM-DD} |

---

## 3. Functional Requirements

### FR-01: {Title}
**Description:** {What the system must do.}
**Source:** [{CR title}]({relative path}) — or — Baseline (existing behaviour, no CR)

**Acceptance Criteria:**
- AC-01-01: {Observable, testable outcome}

# Product Documentation (PD)

> **Status:** DRAFT | REVIEWED
> **Product:** {Product Name} | **Version:** {v2.4} | **Date:** {YYYY-MM-DD}

---

## Overview
{What it does, who uses it, problem solved. 2–3 sentences max.}

**Default roles:** [from the role registry — each as Display Name (`code_identifier`)]
**Related modules:** [from the module registry — names and groupings exactly as it has them]

---

## App Flow
```mermaid
flowchart LR
    Session --> A1[{Screen or action}]
    A2 --> B1[{Screen or action}]
```

---

## Features by Role

One column per role the product actually has — never padded, never truncated.

| Feature | What it does | {Role 1} (`{role_1_code}`) | {Role 2} (`{role_2_code}`) | Notes |
|---------|-------------|---------|---------|-------|
| {Feature A} | {Specific capability} | View | Create/Edit | {E.g. "Own records only"} |

---

## Module Connections

**Outbound to:**
- {Module}: Sends {payload} when {trigger} — {impact or dependency}

**Inbound from:**
- {Module}: Receives {payload} when {trigger} — {how it is used}

---

## Notifications & Triggers

- **{Event}** (triggered by {role or action}): Notifies {recipient role} via
  {in-app / email / SMS / webhook} — {what the message conveys}

---

## Known Limitations

- {Constraint — e.g. "Bulk imports limited to 1,000 records per file"}

# Technical Implementation Plan (TIP)

> **Status:** DRAFT | IN REVIEW | APPROVED
> **Linked BRD:** [{BRD filename}](../business-requirements/{BRD-filename}.md)
> **Effort:** S (<1 day) / M (1–3 days) / L (3–7 days) / XL (>7 days)

---

## 1. Implementation Tasks

### Backend
| #     | Task | FR(s) | Effort |
|-------|------|-------|--------|
| BE-01 |      |       |        |

### API
| #      | Task                     | FR(s) | Effort |
|--------|--------------------------|-------|--------|
| API-01 | {Endpoint to add/modify} |       |        |

### Frontend
| #     | Task                           | FR(s) | Effort |
|-------|--------------------------------|-------|--------|
| FE-01 | {Component/page to add/modify} |       |        |

---

## 2. API Contracts

### `{METHOD} /api/{endpoint}`
**Auth:** {the project's auth mechanism} — min role: {Role}

```json
{ "field_name": "string" }
```

---

## 3. Data Model Changes

| Column    | Type      | Nullable | Default         |
|-----------|-----------|----------|-----------------|
| id        | {id type} | No       | {generated how} |
| {field}   | {type}    | No       | —               |

# Test Case: {MODULE}_TC{NN}_{Short_Name}

> **Status:** DRAFT | READY | PASS | FAIL | BLOCKED
> **Priority:** High / Medium / Low
> **Type:** Happy Path / Negative / Role-Based / Edge Case
> **Linked PRD:** [{PRD filename}](../../product-requirements/{PRD-filename}.md) — what should happen
> **Linked PD:** [{PD filename}](../../product-documentation/{PD-filename}.md) — what currently happens
> **FR/AC:** FR-{xx}, AC-{xx}-{xx}

---

## Preconditions
- Tester is logged in as **{Role}** on **{environment}**
- {Any required data or system state}

---

## Test Steps

| Step | Action                              | Input Data    | Expected Result      |
|------|-------------------------------------|---------------|----------------------|
| 1    | {Click / Navigate / Enter / Select} | {Exact value} | {Observable outcome} |
| 2    |                                     |               |                      |

---

## Postconditions
- {What must be true in the system after the test passes}

---

## Execution

| Field       | Value                       |
|-------------|-----------------------------|
| Executed by |                             |
| Environment | Staging / Demo / Production |
| Result      | PASS / FAIL / BLOCKED       |

# Diagram: {Title}

> **Status:** DRAFT | IN REVIEW | APPROVED
> **Type:** Flowchart / Sequence / ER / State / User Journey
> **Linked artefact:** [{CR or BRD filename}](../change-requests/{filename}.md)

---

## Purpose
{1–2 sentences: what this diagram shows, why it was created, and who the audience is.}

---

## Diagram

```mermaid
flowchart LR
    A[{Start — e.g. User logs in}] --> B{Decision point}
    B -- Yes --> C[{Outcome A}]
    B -- No --> D[{Outcome B}]
    C --> E[{End state}]
    D --> E
```

---

## Key
- {Symbol or shape} — {what it represents}
- {Arrow style} — {what it means}

---

## Notes & Assumptions
- {Any decisions made in drawing the diagram that the reader should know about}

# ERD: {Title}

> **Status:** DRAFT | IN REVIEW | APPROVED
> **Linked artefact:** [{BRD, CR, or TIP filename}](../../path/to/artefact.md)

---

## Purpose
{Which tables are shown, why this diagram was created, and who the audience is.}

---

## Diagram

```mermaid
erDiagram
    TABLE_NAME {
        int id PK
        varchar name
        int foreign_id FK
        date created_at
    }
    OTHER_TABLE {
        int id PK
        varchar description
    }
    TABLE_NAME ||--o{ OTHER_TABLE : "has many"
```

---

## Relationship Key

| Notation   | Meaning                      |
|------------|------------------------------|
| ||--||     | One to one                   |
| ||--o{     | One to zero or many          |
| ||--|{     | One to one or many           |
| }o--o{    | Zero or many to zero or many |

---

## Notes & Assumptions
- {Any tables or columns omitted for clarity}

# Client Clarification Request (CLQ)

> **Status:** DRAFT | SENT | RESOLVED
> **Related Artefact:** [{artefact filename}](../{path}/{filename}.md)
> **Date:** {YYYY-MM-DD}

---

**Subject: {Feature or Module Name} — Clarification Required Before We Proceed**

{Opening: reviewed the request, conducted a full review, N points to raise before work can begin.}

---

## 1. {Blocker title — plain language}

{Context: what the request assumes, what the system currently does, why they conflict.}

**Question:** {One precise, answerable question.}

---

## Next Steps

Once you have reviewed these points, please reply with your answers or preferred approach.
We will not begin scoping or development until these are resolved.