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 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 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

text

PRD (Persistent) → Specification (Temporary) → Implementation → Archive Spec

Shell

git mv specs/task-tags/specification.md specs/_archive/2024-01-task-tags-spec.md

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

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.

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%

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

Markdown

## Verification Criteria

**Tests:**
- User can create tag → test passes
- Invalid tag rejected → test passes
- Tag filtering <200ms → benchmark measures 45ms
- Coverage ≥90% → achieved 94%

## Verification Criteria

**Tests:**
- User can create tag → test passes
- Invalid tag rejected → test passes
- Tag filtering <200ms → benchmark measures 45ms
- Coverage ≥90% → achieved 94%

Markdown

## Success Metrics (Post-Deployment)

Measured after release, inform future iterations:
- Target: 70% of users create 3+ tags within first week
- Measured via: Analytics dashboard
- Review date: 2 weeks after launch

Note: NOT verification criteria. Product analytics goals.

## Success Metrics (Post-Deployment)

Measured after release, inform future iterations:
- Target: 70% of users create 3+ tags within first week
- Measured via: Analytics dashboard
- Review date: 2 weeks after launch

Note: NOT verification criteria. Product analytics goals.

Markdown

- 70% of users adopt tags within the first week

- 70% of users adopt tags within the first week

Markdown

- Test: Tag creation succeeds with valid name → passes
- Performance: Tag API responds <100ms → measured at 45ms

- Test: Tag creation succeeds with valid name → passes
- Performance: Tag API responds <100ms → measured at 45ms

Markdown

- Target: 70% user adoption within the first week (analytics, post-deployment)

- Target: 70% user adoption within the first week (analytics, post-deployment)

Markdown

# PRD: [Feature Name]

**Version:** [X.Y]  
**Status:** [Draft | Implemented | Superseded]  
**Created:** [Date]

## Problem This Feature Solves
[Past/neutral tense - "This feature adds..." not "Currently broken..."]

## Requirements
[Numbered functional requirements]

## Constraints
- Technical: [Integration points, patterns to follow]
- Business: [Rules, policies]
- Performance: [Specific targets]

## Success Metrics (Post-Deployment)
[Clearly marked as analytics goals, not verification criteria]
Review date: [When to assess]

## Out of Scope
[What we're NOT building in this version]

# PRD: [Feature Name]

**Version:** [X.Y]  
**Status:** [Draft | Implemented | Superseded]  
**Created:** [Date]

## Problem This Feature Solves
[Past/neutral tense - "This feature adds..." not "Currently broken..."]

## Requirements
[Numbered functional requirements]

## Constraints
- Technical: [Integration points, patterns to follow]
- Business: [Rules, policies]
- Performance: [Specific targets]

## Success Metrics (Post-Deployment)
[Clearly marked as analytics goals, not verification criteria]
Review date: [When to assess]

## Out of Scope
[What we're NOT building in this version]

Markdown

# PRD: Task Priority (Revised)

**Version:** 2.0  
**Status:** Implemented  
**Supersedes:** v1.0

## Problem This Update Solves
User research showed numeric priority confused 68% of users.
This update replaces 1-5 scale with self-explanatory enum.

## Requirements
- Priority field: enum low/medium/high
- Migration: 1-2→high, 3→medium, 4-5→low

# PRD: Task Priority (Revised)

**Version:** 2.0  
**Status:** Implemented  
**Supersedes:** v1.0

## Problem This Update Solves
User research showed numeric priority confused 68% of users.
This update replaces 1-5 scale with self-explanatory enum.

## Requirements
- Priority field: enum low/medium/high
- Migration: 1-2→high, 3→medium, 4-5→low

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

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.

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

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

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.

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

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

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.

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%

Markdown

## Verification Criteria

**Tests:**
- User can create tag → test passes
- Invalid tag rejected → test passes
- Tag filtering <200ms → benchmark measures 45ms
- Coverage ≥90% → achieved 94%

Markdown

## Success Metrics (Post-Deployment)

Measured after release, inform future iterations:
- Target: 70% of users create 3+ tags within first week
- Measured via: Analytics dashboard
- Review date: 2 weeks after launch

Note: NOT verification criteria. Product analytics goals.

Markdown

- 70% of users adopt tags within the first week

Markdown

- Test: Tag creation succeeds with valid name → passes
- Performance: Tag API responds <100ms → measured at 45ms

Markdown

- Target: 70% user adoption within the first week (analytics, post-deployment)

Markdown

# PRD: [Feature Name]

**Version:** [X.Y]  
**Status:** [Draft | Implemented | Superseded]  
**Created:** [Date]

## Problem This Feature Solves
[Past/neutral tense - "This feature adds..." not "Currently broken..."]

## Requirements
[Numbered functional requirements]

## Constraints
- Technical: [Integration points, patterns to follow]
- Business: [Rules, policies]
- Performance: [Specific targets]

## Success Metrics (Post-Deployment)
[Clearly marked as analytics goals, not verification criteria]
Review date: [When to assess]

## Out of Scope
[What we're NOT building in this version]

Markdown

# PRD: Task Priority (Revised)

**Version:** 2.0  
**Status:** Implemented  
**Supersedes:** v1.0

## Problem This Update Solves
User research showed numeric priority confused 68% of users.
This update replaces 1-5 scale with self-explanatory enum.

## Requirements
- Priority field: enum low/medium/high
- Migration: 1-2→high, 3→medium, 4-5→low

Markdown

# PRD: Task Tags

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

Markdown

## Problem This Feature Solves

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

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

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

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.

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

Markdown

## Integration

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

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