Product Requirements Strategy

Introduction: The Human-AI Partnership in SDD

Many teams write detailed specifications, implement features, and then struggle to maintain those specifications forever. This creates specification debt—outdated documentation that drifts from reality. This lesson introduces a better mental model: specifications are temporary implementation guides, while product requirements documents (PRDs) persist as business context. Understanding this distinction prevents documentation debt and keeps your development process lightweight.

Core Documentation Principles

The correct mental model treats different documentation types according to their purpose and lifetime. text PRD (Persistent) \to Specification (Temporary) \to Implementation \to Archive Spec What persists in your codebase: Product requirements document: Business requirements and rationale (lives in docs/prds/) CODEX.md : Project constitution ADRs: Architecture decisions (immutable records) API schema: API contracts Code + Tests: Executable implementation What serves temporarily: Specification: Implementation guide (archived after use) Technical plan: Implementation approach Task list: Execution checklist This separation prevents the common mistake of treating all documentation as equally permanent.

Why Specifications Are Temporary

A specification guides implementation right now. Once you've implemented and tested the feature, the specification has served its purpose. The actual behavior now lives in code, the API contract exists in the API schema, and the business context remains in the PRD. After implementation completes, archive the specification: Shell git mv specs/task-tags/specification.md specs/_archive/2024-01-task-tags-spec.md When modifying a feature later, don't try to "update" an old specification. Instead, follow this workflow: Start from the PRD—are business requirements still current? Generate a new specification—a fresh implementation guide Implement and archive the new specification Specifications are like scaffolding: essential during construction, but removed once the building stands.

What Is A PRD?

A PRD defines the WHAT and WHY at the business level. It explains what problem you're solving and why it matters to users or the business. A PRD contains: Problem statement: What problem does this solve? Users and personas Functional requirements Constraints: Technical, business, and performance Success metrics: Post-deployment analytics goals Out of scope: What you're deliberately not building The PRD is written for product managers, stakeholders, developers, and future team members. It provides business context that helps people understand why features exist without reverse-engineering intent from code. A PRD is not: As detailed as a specification, an implementation guide, or runtime reference documentation.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

PRD Vs Specification

Document	Primary Purpose	When Consulted
API Schema	Define current contracts	Every API-related task
CODEX.md	Project-wide standards	Start of work sessions
Code + Tests	Current implementation	When modifying features
ADRs	Architectural decisions	When working on related areas
PRDs	Business context	When understanding requirements history

Understanding the difference between PRDs and specifications prevents documentation confusion. They serve completely different purposes.

PRD example (high-level):

Markdown

## Problem This Feature Solves

Users managing multiple projects needed a way to categorize tasks 
beyond status and priority. This feature adds tagging capability.

## Requirements
- Users can add/remove tags from tasks
- Maximum 10 tags per task
- Tags are alphanumeric strings with hyphens (1-30 chars)
- Users can filter tasks by tags

## Success Metrics (Post-Deployment)
- Target: 70% of active users create 3+ tags within first week
- Review date: 2 weeks after launch

Note: Product analytics goals, not verification criteria.

## Problem This Feature Solves

Users managing multiple projects needed a way to categorize tasks 
beyond status and priority. This feature adds tagging capability.

## Requirements
- Users can add/remove tags from tasks
- Maximum 10 tags per task
- Tags are alphanumeric strings with hyphens (1-30 chars)
- Users can filter tasks by tags

## Success Metrics (Post-Deployment)
- Target: 70% of active users create 3+ tags within first week
- Review date: 2 weeks after launch

Note: Product analytics goals, not verification criteria.

Specification example (precise):

Markdown

## API Contract

POST /api/tasks/{task_id}/tags
Request: { "name": "string" }  // Regex: ^[a-zA-Z0-9-]{1,30}$
Response (201): { "id": "uuid", "name": "string", ... }
Response (400): { "detail": "Tag name must be 1-30 alphanumeric..." }

## Verification Criteria (Must Pass Before Merge)

**Functional Tests:**
- User can add tag with valid name
- System rejects 11th tag (max 10 enforced)
- System rejects invalid characters
- Tag filter returns correct tasks

**Performance Tests:**
- Tag filtering <200ms for 1000 tasks
- Tag list query <50ms

**Coverage:**
- Test coverage ≥90%

## API Contract

POST /api/tasks/{task_id}/tags
Request: { "name": "string" }  // Regex: ^[a-zA-Z0-9-]{1,30}$
Response (201): { "id": "uuid", "name": "string", ... }
Response (400): { "detail": "Tag name must be 1-30 alphanumeric..." }

## Verification Criteria (Must Pass Before Merge)

**Functional Tests:**
- User can add tag with valid name
- System rejects 11th tag (max 10 enforced)
- System rejects invalid characters
- Tag filter returns correct tasks

**Performance Tests:**
- Tag filtering <200ms for 1000 tasks
- Tag list query <50ms

**Coverage:**
- Test coverage ≥90%

Key differences:

Aspect	PRD	Specification
Purpose	Business requirements	Implementation guide
Detail	High-level (WHAT/WHY)	Precise (HOW)
Lifetime	Persistent	Temporary
Metrics	Post-deployment analytics	Pre-merge verification
Active Use	Historical reference	Read during implementation

The PRD explains why you need tags. The specification explains exactly how to build them.

Task Tags PRD Example

Let's examine a real PRD section by section to understand how each part serves its purpose.

Header and metadata:

Markdown

# PRD: Task Tags

**Version:** 1.0  
**Status:** Implemented (2024-01-28)  
**Created:** 2024-01-15

# PRD: Task Tags

**Version:** 1.0  
**Status:** Implemented (2024-01-28)  
**Created:** 2024-01-15

The status field immediately shows this PRD's lifecycle state. "Implemented" means we can reference it for historical context.

Problem statement:

Markdown

## Problem This Feature Solves

Users managing multiple projects needed a way to categorize tasks 
beyond status and priority. This feature adds tagging capability.

## Problem This Feature Solves

Users managing multiple projects needed a way to categorize tasks 
beyond status and priority. This feature adds tagging capability.

Notice the past/neutral tense ("needed") instead of "currently broken." The PRD documents what problem existed, not the current system state.

Functional requirements:

Markdown

## Requirements

1. Users can add/remove tags (alphanumeric + hyphens, 1-30 chars)
2. Maximum 10 tags per task
3. Tags are case-insensitive and per-user
4. Users can filter tasks by tags
5. Users can list tags with usage counts

## Requirements

1. Users can add/remove tags (alphanumeric + hyphens, 1-30 chars)
2. Maximum 10 tags per task
3. Tags are case-insensitive and per-user
4. Users can filter tasks by tags
5. Users can list tags with usage counts

Business requirements at a high level. A specification would detail the exact regex, API endpoints, and error codes.

Constraints:

Markdown

## Constraints

**Technical:**
- Extends Task model (src/models/task.py)
- Follows repository pattern (CODEX.md)
- JWT auth via get_current_user

**Performance:**
- Tag filtering <200ms for 1000 tasks
- Tag list query <50ms

## Constraints

**Technical:**
- Extends Task model (src/models/task.py)
- Follows repository pattern (CODEX.md)
- JWT auth via get_current_user

**Performance:**
- Tag filtering <200ms for 1000 tasks
- Tag list query <50ms

This references actual codebase structure. Architecture-aware documentation connects business requirements to real implementation touchpoints, helping developers understand where changes need to occur.

Success metrics:

Markdown

## Success Metrics (Post-Deployment)

Measured after release, these inform v2.0:
- Target: 70% of users create 3+ tags within the first week
- Target: Tag filtering used in 50%+ of task views
- Review: 2 weeks after launch

Note: Product analytics goals, not verification criteria.

## Success Metrics (Post-Deployment)

Measured after release, these inform v2.0:
- Target: 70% of users create 3+ tags within the first week
- Target: Tag filtering used in 50%+ of task views
- Review: 2 weeks after launch

Note: Product analytics goals, not verification criteria.

Clearly marked as analytics goals that cannot be verified during development. These require real users over time.

Scope boundaries:

Markdown

## Out of Scope

v1.0 does NOT include:
- Tag sharing between users (team tags in v2.0)
- Tag colors or visual customization
- Tag hierarchies

## Out of Scope

v1.0 does NOT include:
- Tag sharing between users (team tags in v2.0)
- Tag colors or visual customization
- Tag hierarchies

This prevents scope creep and documents what you're deliberately not building.

Integration notes:

Markdown

## Integration

- New tables: `tags`, `task_tags`
- Testing: 90%+ coverage per CODEX.md
- Migration: Alembic following existing patterns

## Integration

- New tables: `tags`, `task_tags`
- Testing: 90%+ coverage per CODEX.md
- Migration: Alembic following existing patterns

Technical touchpoints that the specification expands into detailed API contracts and test cases.

Documentation usage in practice:

When implementing new features, developers start with the PRD to understand business requirements, then generate detailed specifications for implementation. When modifying existing features, developers work from the current implementation (code, tests, API schemas) since these reflect actual system state. The PRD remains available for understanding original business context when needed.

Introduction: The Human-AI Partnership in SDD

Core Documentation Principles

Why Specifications Are Temporary

What Is A PRD?

Join the 1M+ learners on CodeSignal

PRDs As Historical Records

Documentation Hierarchy

When To Consult PRDs

PRD Vs Specification

Verification Criteria Vs Success Metrics

Verification Criteria In Specifications

Success Metrics In PRDs

Practical Examples

PRD Structure Best Practices

PRD Versioning

AI-Assisted PRD Generation

Task Tags PRD Example

Summary