Skip to content

PRD Creation Guide

How to write a Product Requirements Document for a Smartsapp module. This guide extracts the conventions used in the existing School PRD and Canteen PRD so that all future PRDs follow a consistent structure.

1. File Conventions

Convention Rule
File name <Module>_PRD.md (e.g., Attendance_PRD.md)
Location docs/modules/<module>/ alongside the module's C4 architecture doc
PRD index Add a row to the relevant table in docs/PRD.md and link to the new file

2. PRD Template

Copy the template below and replace the placeholder text.

# <Module Name>

**Product Requirements Document** — <subtitle describing scope, e.g., "Admin Portal Full Feature Specification">

| Field | Value |
|-------|-------|
| Document Version | v1.0 |
| Status | Draft |
| Date | <month year> |
| Audience | Engineering, Product, Design, QA |

---

## 1. Product Overview

<Brief paragraph explaining what this module does, who uses it, and why it exists.>

### 1.1 Strategic Goals

- <Goal 1>
- <Goal 2>

### 1.2 Scope

**In scope:**

- <Feature or capability>
- <Feature or capability>

**Out of scope:**

- <Excluded item and reason>

---

## 2. <First Major Feature or Entity Group>

> **Definition**
> <One-sentence definition of the core concept.>

### 2.1 <Subsection>

<Description or workflow steps.>

#### Attributes / Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| **field_name** | String | Yes | <What this field represents> |

#### Business Rules

> <Rule 1 — use blockquotes for every business rule.>

> <Rule 2>

---

## 3. <Next Major Feature or Entity Group>

<!-- Repeat the pattern from Section 2 for each major area. -->

---

## N-2. Non-Functional Requirements

- **Data integrity:** <constraints, e.g., cascade deletes, uniqueness>
- **Performance:** <expectations, e.g., response times, batch sizes>
- **Multi-tenancy:** <isolation rules>

---

## N-1. Open Questions

| # | Question | Owner | Status |
|---|----------|-------|--------|
| 1 | <Unresolved question> | <Person or team> | Open |

---

## N. Revision History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| v1.0 | <date> | <name> | Initial draft |

3. Section Reference

Every PRD should include these sections. The order and numbering adapt to the module's size.

Section Purpose Required
Header & metadata table Version, status, date, audience Yes
Product Overview Goals, scope, boundaries Yes
Core content Entity definitions or feature specifications (see Section 4) Yes
Business Rules Constraints and invariants, written as blockquotes Yes
Non-Functional Requirements Data integrity, performance, multi-tenancy Recommended
Open Questions Unresolved decisions tracked with owner and status Recommended
Revision History Version log with date, author, and summary of changes Yes

4. Entity-Focused vs. Feature-Focused PRDs

Choose the style that best fits the module. Both are valid and can be mixed.

Entity-focused (data-model style)

Best for modules that define core data structures used across the platform.

  • Organise sections around entities (e.g., School, Campus, Student)
  • Each entity gets: description, attributes table, and business rules
  • Include an Entity Relationship Summary table
  • Example: School PRD

Feature-focused (workflow style)

Best for modules with rich user-facing workflows and UI.

  • Organise sections around functional areas (e.g., Dashboard, Feeding List, Reports)
  • Each area gets: description, UI fields/columns, filters, actions, and business rules
  • Include status lifecycle tables where applicable
  • Example: Canteen PRD

5. Formatting Conventions

These conventions are enforced across all PRDs for consistency.

  • ## (H2) for major numbered sections
  • ### (H3) for subsections (e.g., 2.1, 2.2)
  • #### (H4) for sub-subsections or grouped fields
  • Tables for structured data: attributes, statuses, roles, filters, permissions
  • Blockquotes (>) for business rules, definitions, and important notes
  • Bold (**text**) for emphasis on key terms and field names
  • Numbered lists for sequential workflows and steps
  • Bullet lists for non-sequential items (features, goals, scope items)
  • Horizontal rules (---) between major sections

6. AI Maintenance Rules

These rules (from AI_CONTEXT.md) govern how AI assistants update PRDs.

AI should update PRDs when:

  • Implementation diverges from the PRD (code is truth — PRD must match)
  • Open questions get resolved during development
  • New entities or fields are added within the PRD's existing scope
  • User explicitly asks for a PRD update

AI should NOT update PRDs when:

  • Product direction changes (new features, scope changes)
  • Removing or deprecating features
  • Adding speculative content
  • Changing business rules (flag to user instead)

Principle: AI updates PRDs to keep them accurate with what was built. Product updates PRDs to define what should be built next.