Project Management

Standards, templates, and conventions for product planning and feature development documents.

When to Use

• Establishing product vision, mission, and roadmap

• Defining feature requirements (use cases, user stories, functional/non-functional requirements)

• Writing technical specifications with data models and API contracts

• Breaking specifications into implementation tasks

• Tracking implementation progress via changelog

• Creating or updating any document in the prd/ directory

Document Hierarchy

Product documents follow a progressive disclosure model. Each level adds detail:

prd/ ├── README.md # Master index linking all documents ├── mission.md # Vision, users, differentiators, metrics ├── tech-stack.md # Architecture, technology choices ├── roadmap.md # Now/Next/Later feature priorities ├── changelog.md # LLM memory: what's been built, mapped to requirements └── specs/ └── YYYYMMDD-HHmm-{slug}/ ├── requirements.md # UC/US/FR/NFR definitions ├── spec.md # Data models, API contracts, diagrams └── tasks.md # Vertical slices with story points

ID Scheme

Every ID includes a 4-character feature tag derived from the feature folder's creation timestamp. This prevents collisions across parallel branches.

Prefix Meaning Format Example

UC Use Case UC-{tag}-NNN UC-0Fy0-001

US User Story US-{tag}-NNN US-0Fy0-001

FR Functional Requirement FR-{tag}-NNN FR-0Fy0-001

NFR Non-Functional Requirement NFR-{tag}-NNN NFR-0Fy0-001

Base-62 Tag Algorithm

Compute the tag from the feature folder's YYYYMMDD-HHmm timestamp (always UTC):

• Parse the timestamp as a UTC datetime

• Compute total minutes since epoch 2026-01-01 00:00 UTC

• Repeatedly divide by 62, collecting remainders

• Map remainders: 0-9 → '0'-'9' , 10-35 → 'A'-'Z' , 36-61 → 'a'-'z'

• Read characters MSB-first (last quotient to first remainder)

• Left-pad to 4 characters with '0'

Worked example: 20260212-1500 → 42 days × 1440 + 15 × 60 + 0 = 61,380 min → 61380 ÷ 62 = 990 r 0, 990 ÷ 62 = 15 r 60, 15 ÷ 62 = 0 r 15 → digits [F, y, 0] → pad to 0Fy0 → UC-0Fy0-001

Tasks use dot notation within their feature: N.M (e.g., 1.1 , 3.7 ). Task references include the full UC ID: UC-{tag}-NNN/N.M .

Formatting Rules

Text checkboxes only

Use - [ ] and - [x] for all checklists. Never use HTML checkboxes, Unicode symbols, or custom markers.

No emojis

Never use emojis in any product document. Use text labels and markdown formatting instead.

Mermaid-only diagrams

All diagrams in spec.md must use Mermaid syntax. No ASCII art, no embedded images. Acceptable diagram types: sequence, class, flowchart, state, ER.

Single-checklist rule

Each document has exactly ONE canonical checklist for tracking progress. Never duplicate tracking sections. In tasks.md, the feature-level checkboxes (## N. [x] Feature title ) and task-level checkboxes (- N.M [x] Task title ) are the single source of truth. Do not add separate "Progress Tracking" or "Status" tables.

Tables for structured data

Use markdown tables for requirements, metrics, risks, and any data with consistent columns. Use bullet lists only for narrative content.

Feature Folder Naming

Feature specification folders use the format: YYYYMMDD-HHmm-{slug}/

• Timestamp is when the feature was first scoped, always in UTC

• Slug uses underscores, lowercase, derived from the feature name

• Example: 20260131-1430-patient_onboarding/

Estimation

Use story points on a Fibonacci-like scale. Never use time estimates (hours, days, sprints).

Points Meaning

1 Trivial — config change, rename, copy-paste with minor edits

2 Small — single-file change with clear approach

3 Medium — multi-file change, some decisions required

5 Large — cross-layer feature slice, multiple decisions

8 Very large — significant complexity, unknowns, or integration work

If a task exceeds 8 points, split it into smaller tasks.

Vertical Feature Slicing

Tasks must be organized as vertical slices through all layers, not horizontal layers. Each task delivers a complete, testable piece of functionality from database to UI.

Correct (vertical): "Create patient generals form with GraphQL mutation and database migration" Wrong (horizontal): "Create all database migrations", "Create all GraphQL schemas", "Create all forms"

Organize tasks by use case (UC-{tag}-NNN). Within each use case, order tasks by dependency — earlier tasks unblock later ones.

Changelog as LLM Memory

The changelog (prd/changelog.md ) is designed as an LLM memory document — organized by domain area rather than chronologically. It describes what exists in the codebase, mapped back to requirement IDs. This allows any agent to quickly understand what has been built without reading every file.

Reference Templates

Template Purpose

references/readme-template.md Master index linking all product context

references/mission-template.md Vision, target users, differentiators, metrics

references/tech-stack-template.md Architecture, technology choices, integrations

references/roadmap-template.md Now/Next/Later feature prioritization

references/changelog-template.md LLM memory: what's built, mapped to requirements

references/requirements-template.md UC/US/FR/NFR with consistent IDs

references/spec-template.md Data models, API contracts, Mermaid diagrams

references/tasks-template.md Vertical slices organized by UC, with story points