Feature Spec

Software Engineering Feature Specification and Planning Best Practices

Comprehensive feature specification and planning guide for software engineers, product managers, and technical leads. Contains 42 rules across 8 categories, prioritized by impact to prevent scope creep and ensure project success.

When to Apply

Reference these guidelines when:

• Writing PRDs or feature specifications
• Defining requirements or user stories
• Managing scope and preventing scope creep
• Prioritizing features and backlog items
• Handling change requests
• Aligning stakeholders on project goals

Rule Categories by Priority

Quick Reference

1. Scope Definition (CRITICAL)

• scope-define-boundaries - Define explicit scope boundaries
• scope-document-assumptions - Document all assumptions explicitly
• scope-work-breakdown - Break scope into measurable work items
• scope-define-mvp - Define MVP before full feature set
• scope-stakeholder-signoff - Get stakeholder signoff on scope

2. Requirements Clarity (CRITICAL)

• req-specific-measurable - Write specific, measurable requirements
• req-user-stories - Structure requirements as user stories
• req-avoid-solution-language - Avoid solution-specific language
• req-functional-nonfunctional - Separate functional and non-functional
• req-consistent-terminology - Use consistent terminology
• req-traceability - Maintain requirements traceability

3. Prioritization Frameworks (HIGH)

• prio-moscow-method - Use MoSCoW prioritization method
• prio-rice-scoring - Apply RICE scoring for objectivity
• prio-value-vs-effort - Map value vs effort explicitly
• prio-dependencies-first - Identify and order dependencies
• prio-kano-model - Apply Kano model for feature classification

4. Acceptance Criteria (HIGH)

• accept-given-when-then - Use Given-When-Then format
• accept-testable-criteria - Write testable acceptance criteria
• accept-edge-cases - Include edge cases in acceptance
• accept-definition-of-done - Define clear definition of done
• accept-avoid-over-specification - Avoid over-specification

5. Stakeholder Alignment (MEDIUM-HIGH)

• stake-identify-stakeholders - Identify all stakeholders early
• stake-early-feedback - Gather feedback early and often
• stake-conflict-resolution - Resolve conflicts explicitly
• stake-communication-plan - Establish communication cadence
• stake-success-metrics - Align on success metrics

6. Technical Specification (MEDIUM)

• tech-system-context - Document system context and dependencies
• tech-api-contracts - Define API contracts before implementation
• tech-data-model - Specify data models and schema changes
• tech-error-handling - Plan error handling and recovery
• tech-performance-requirements - Specify performance requirements
• tech-security-considerations - Document security considerations

7. Change Management (MEDIUM)

• change-formal-process - Use formal change request process
• change-impact-assessment - Assess full impact before approval
• change-version-tracking - Version all specification documents
• change-scope-freeze - Implement scope freeze periods
• change-defer-log - Maintain deferred items log

8. Documentation Standards (LOW)

• doc-single-source - Maintain single source of truth
• doc-consistent-templates - Use consistent document templates
• doc-decision-records - Document key decisions with context
• doc-accessible-format - Keep documentation accessible
• doc-glossary-terms - Define project terminology

Feature Specification and Planning

Version 1.0.0 Software Engineering January 2026

Note:

This document is mainly for agents and LLMs to follow when maintaining,

generating, or refactoring codebases. Humans may also find it useful,

but guidance here is optimized for automation and consistency by AI-assisted workflows.

---

Abstract

Comprehensive feature specification and planning guide for software engineers, product managers, and technical leads. Contains 42 rules across 8 categories, prioritized by impact from critical (scope definition, requirements clarity) to foundational (documentation standards). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct approaches, and specific impact metrics to prevent scope creep and ensure project success.

---

Table of Contents

1. Scope Definition — CRITICAL

• 1.1 Create Work Breakdown Structure for Complex Features — CRITICAL (reduces estimation error by 50%)
• 1.2 Define Explicit In-Scope and Out-of-Scope Boundaries — CRITICAL (prevents 40% of project failures from scope creep)
• 1.3 Define MVP Separately from Full Vision — CRITICAL (enables faster time-to-value)
• 1.4 Document Assumptions and Constraints Early — CRITICAL (prevents mid-project surprises and rework)
• 1.5 Obtain Stakeholder Sign-off on Scope — CRITICAL (prevents scope disputes and rejected deliverables)

2. Requirements Clarity — CRITICAL

• 2.1 Maintain Requirements Traceability — CRITICAL (catches 95% of missing requirements before launch)
• 2.2 Separate Functional and Non-Functional Requirements — CRITICAL (prevents 75% of late-stage NFR surprises)
• 2.3 State Requirements Without Prescribing Solutions — CRITICAL (enables optimal technical solutions)
• 2.4 Use Consistent Terminology with a Glossary — CRITICAL (eliminates cross-team miscommunication)
• 2.5 Use User Story Format for Feature Requirements — CRITICAL (reduces feature misalignment by 60%)
• 2.6 Write Specific and Measurable Requirements — CRITICAL (reduces interpretation disputes by 80%)

3. Prioritization — HIGH

• 3.1 Identify and Prioritize Dependencies — HIGH (prevents blocked work and idle teams)
• 3.2 Map Features by Value vs Effort — HIGH (focuses 80% of effort on high-value work)
• 3.3 Use Kano Model for Customer Satisfaction Prioritization — HIGH (avoids over-investing in features users expect)
• 3.4 Use MoSCoW Method for Scope Prioritization — HIGH (reduces scope disputes by 70%)
• 3.5 Use RICE Scoring for Data-Driven Prioritization — HIGH (reduces priority disputes by 65%)

4. Acceptance Criteria — HIGH

• 4.1 Avoid Over-Specifying Acceptance Criteria — HIGH (preserves developer flexibility)
• 4.2 Ensure All Criteria Are Testable — HIGH (enables objective verification of completion)
• 4.3 Establish Definition of Done Beyond Code — HIGH (reduces post-launch issues by 60%)
• 4.4 Include Edge Cases in Acceptance Criteria — HIGH (prevents production bugs from untested scenarios)
• 4.5 Use Given-When-Then Format for Acceptance Criteria — HIGH (reduces acceptance ambiguity by 80%)

5. Stakeholder Alignment — MEDIUM-HIGH

• 5.1 Align on Success Metrics Before Building — MEDIUM-HIGH (eliminates 90% of post-launch success disputes)
• 5.2 Establish Stakeholder Communication Cadence — MEDIUM-HIGH (reduces stakeholder surprises by 80%)
• 5.3 Gather Stakeholder Feedback Early and Often — MEDIUM-HIGH (reduces late-stage direction changes)
• 5.4 Identify All Stakeholders Early — MEDIUM-HIGH (prevents late-stage surprises from overlooked parties)
• 5.5 Resolve Stakeholder Conflicts Explicitly — MEDIUM-HIGH (prevents passive-aggressive scope battles)

6. Technical Specification — MEDIUM

• 6.1 Define API Contracts Before Implementation — MEDIUM (prevents 70% of integration rework)
• 6.2 Document Security Considerations — MEDIUM (prevents 90% of security review surprises)
• 6.3 Document System Context and Dependencies — MEDIUM (reduces integration surprises by 60%)
• 6.4 Plan Error Handling and Recovery — MEDIUM (reduces production incidents by 50%)
• 6.5 Specify Data Models and Schema Changes — MEDIUM (reduces database migration failures by 80%)
• 6.6 Specify Performance Requirements Upfront — MEDIUM (avoids 40% of late-stage performance rewrites)

7. Change Management — MEDIUM

• 7.1 Assess Full Impact Before Approving Changes — MEDIUM (prevents 80% of timeline surprises from scope changes)
• 7.2 Implement Scope Freeze Periods — MEDIUM (reduces late-stage changes by 85%)
• 7.3 Maintain a Deferred Items Log — MEDIUM (captures 100% of good ideas for future consideration)
• 7.4 Use Formal Change Request Process — MEDIUM (reduces uncontrolled scope growth by 70%)
• 7.5 Version All Specification Documents — MEDIUM (eliminates 95% of "which version is current" confusion)

8. Documentation Standards — LOW

• 8.1 Define Project Terminology in a Glossary — LOW (eliminates term confusion across team)
• 8.2 Document Key Decisions with Context — LOW (preserves decision rationale for future reference)
• 8.3 Keep Documentation Accessible and Searchable — LOW (reduces information retrieval time by 70%)
• 8.4 Maintain Single Source of Truth — LOW (eliminates version confusion across team)
• 8.5 Use Consistent Document Templates — LOW (reduces document creation time by 50%)

---

References

1. https://www.wrike.com/project-management-guide/faq/what-is-scope-creep-in-project-management/ 2. https://www.atlassian.com/agile/product-management/requirements 3. https://www.scaledagileframework.com/user-stories/ 4. https://www.productplan.com/glossary/rice-scoring-model/ 5. https://www.karlwiegers.com/requirements-traceability/ 6. https://owasp.org/www-project-application-security-verification-standard/ 7. https://adr.github.io/ 8. https://sre.google/sre-book/service-level-objectives/

---

Source Files

This document was compiled from individual reference files. For detailed editing or extension:

Rule Title Here

Brief description of the rule and why it matters. Explain the problem this rule prevents.

Incorrect (description of anti-pattern):

Example showing the wrong approach
with comments explaining what goes wrong

Correct (description of best practice):

Example showing the correct approach
with clear structure and best practices

Key points:

• Point 1
• Point 2
• Point 3

Reference: Source Name

Feature Specification and Planning Best Practices

Feature specification and planning guidelines for software engineers, product managers, and technical leads. This skill provides a comprehensive framework for writing clear specifications, preventing scope creep, and managing requirements effectively.

Overview

This skill contains 42 rules across 8 categories, covering the complete feature planning lifecycle from scope definition to documentation.

Directory Structure

feature-spec-planning/
├── SKILL.md              # Entry point with quick reference
├── AGENTS.md             # Compiled comprehensive guide
├── metadata.json         # Version, organization, references
├── README.md             # This file
└── rules/
    ├── _sections.md      # Category definitions
    ├── scope-*.md        # Scope definition rules
    ├── req-*.md          # Requirements clarity rules
    ├── prio-*.md         # Prioritization framework rules
    ├── accept-*.md       # Acceptance criteria rules
    ├── stake-*.md        # Stakeholder alignment rules
    ├── tech-*.md         # Technical specification rules
    ├── change-*.md       # Change management rules
    └── doc-*.md          # Documentation standards rules

Getting Started

Installation

pnpm install

Building

pnpm build

Validation

pnpm validate

Creating a New Rule

1. Determine the appropriate category and prefix 2. Create a new file in rules/ following the naming convention 3. Use the rule template structure 4. Run validation to check compliance

Category Prefixes

Rule File Structure

Each rule file should follow this template:

---
title: Rule Title
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified impact description
tags: prefix, technique, related-concepts
---

## Rule Title

Brief explanation of WHY this matters (1-3 sentences).

**Incorrect (what's wrong):**

\`\`\`language
// Bad code example
\`\`\`

**Correct (what's right):**

\`\`\`language
// Good code example
\`\`\`

Reference: [Reference Title](URL)

File Naming Convention

Rule files follow the pattern: {prefix}-{description}.md

Examples:

• scope-define-boundaries.md
• req-user-stories.md
• change-formal-process.md

Impact Levels

Scripts

• pnpm validate - Validate all rules against guidelines
• pnpm build - Compile rules into AGENTS.md
• pnpm lint - Check markdown formatting

Contributing

1. Read the existing rules to understand the style and format 2. Ensure your rule has both incorrect and correct examples 3. Include a quantified impact description 4. Reference authoritative sources 5. Run validation before submitting

References

• Wrike - What is Scope Creep
• Atlassian - Product Requirements
• SAFe - User Stories
• ProductPlan - RICE Scoring
• ADR GitHub
• Google SRE - Service Level Objectives

Acknowledgments

This skill draws on feature planning best practices from product management methodologies, agile frameworks, and established specification techniques including MoSCoW prioritization, RICE scoring, and Architecture Decision Records.

Sections

This file defines all sections, their ordering, impact levels, and descriptions. The section ID (in parentheses) is the filename prefix used to group rules.

---

1. Scope Definition (scope)

Impact: CRITICAL Description: Clear scope boundaries prevent scope creep, which causes over 40% of project failures. Defining what's in and out of scope upfront enables accurate estimation and stakeholder alignment.

2. Requirements Clarity (req)

Impact: CRITICAL Description: Vague requirements cause costly rework and interpretation disputes. Specific, testable requirements enable accurate estimation and reduce development waste by 30-50%.

3. Prioritization (prio)

Impact: HIGH Description: Proper prioritization ensures highest-value features ship first, maximizing ROI and reducing time-to-value for stakeholders.

4. Acceptance Criteria (accept)

Impact: HIGH Description: Testable acceptance criteria define "done" unambiguously, preventing interpretation disputes and enabling QA to validate deliverables objectively.

5. Stakeholder Alignment (stake)

Impact: MEDIUM-HIGH Description: Early and continuous stakeholder alignment prevents late-stage surprises, rejected deliverables, and costly direction changes.

6. Technical Specification (tech)

Impact: MEDIUM Description: Clear technical specifications bridge business requirements to implementation, reducing developer ambiguity and architectural misalignment.

7. Change Management (change)

Impact: MEDIUM Description: Controlled change processes preserve timeline and budget while allowing legitimate scope evolution through proper impact analysis.

8. Documentation Standards (doc)

Impact: LOW Description: Consistent documentation standards improve long-term maintainability, onboarding, and knowledge transfer across teams.

Avoid Over-Specifying Acceptance Criteria

Acceptance criteria should specify what, not how. Over-specified criteria constrain developers, stifle better solutions, and create maintenance burden when implementation details change.

Incorrect (implementation specified):

## Acceptance Criteria

- [ ] Use a modal dialog with class "confirmation-modal"
- [ ] Modal should have a blue #0066CC "Confirm" button on the right
- [ ] Cancel button should be gray #666666 and on the left
- [ ] Modal should use CSS animation "fadeIn" lasting 200ms
- [ ] Store confirmation state in Redux under user.confirmationStatus
- [ ] Call POST /api/v2/confirmations with JSON payload

Correct (intent without implementation):

## Acceptance Criteria

### User Intent
- [ ] User must confirm before destructive actions
- [ ] Confirmation clearly states the consequence
- [ ] User can cancel without any side effects
- [ ] Confirmation state is persisted across page refreshes

### User Experience
- [ ] Confirmation appears immediately (< 100ms)
- [ ] Primary action is visually prominent
- [ ] Escape key dismisses without confirming
- [ ] Focus is trapped within confirmation UI

### Accessibility
- [ ] Confirmation is announced to screen readers
- [ ] Both actions are keyboard accessible
- [ ] Focus returns to trigger element on dismiss

---

_Implementation notes (non-binding):_
_Team may use modal, inline confirmation, or separate page._
_Design system components preferred but not required._

Signs of over-specification:

• CSS classes or specific styling mentioned
• Specific API endpoints or data formats
• Framework-specific implementation details
• Database column names or schema

When implementation details are appropriate:

• Regulatory requirements mandate specific approaches
• Integration with existing systems constrains options
• Team explicitly requests guidance

Reference: StoriesOnBoard - Acceptance Criteria Examples

Establish Definition of Done Beyond Code

Definition of Done (DoD) includes everything required for a feature to be truly complete—not just working code. Missing DoD items like documentation, monitoring, or accessibility become technical debt.

Incorrect (code-only definition):

## Definition of Done

- [ ] Code written
- [ ] Tests pass
- [ ] Code reviewed

// Missing: Documentation, monitoring, accessibility, security
// Result: "Done" features that break in production, lack docs, exclude users

Correct (comprehensive definition):

## Definition of Done Checklist

### Code Quality
- [ ] Code written and compiles without warnings
- [ ] Unit tests written with > 80% coverage
- [ ] Integration tests for critical paths
- [ ] Code reviewed and approved by 2 team members
- [ ] No known bugs (or documented with tickets)

### Documentation
- [ ] README updated if setup steps changed
- [ ] API documentation updated (OpenAPI/Swagger)
- [ ] User-facing help docs written/updated
- [ ] Changelog entry added

### Testing
- [ ] Manual QA completed and signed off
- [ ] Cross-browser testing (Chrome, Firefox, Safari)
- [ ] Mobile responsive testing completed
- [ ] Accessibility testing (keyboard, screen reader)

### Observability
- [ ] Logging added for key operations
- [ ] Metrics/monitoring dashboards updated
- [ ] Alerts configured for error conditions
- [ ] Feature flag configured (if applicable)

### Security
- [ ] Security review completed (if auth/data changes)
- [ ] No secrets in code
- [ ] Input validation implemented

### Deployment
- [ ] Database migrations tested
- [ ] Rollback plan documented
- [ ] Environment variables documented
- [ ] Deployed to staging and verified

### Sign-off
- [ ] Product owner accepts feature
- [ ] Release notes drafted

DoD per feature type:

• Bug fix: Code, tests, verification
• New feature: Full checklist above
• Refactor: Code, tests, performance comparison

Reference: Scrum.org - Definition of Done

Include Edge Cases in Acceptance Criteria

Explicitly document edge cases and boundary conditions in acceptance criteria. Edge cases not in the spec are often not tested, leading to production bugs when users encounter unusual scenarios.

Incorrect (only happy path):

## Feature: Shopping Cart

### Acceptance Criteria
- User can add items to cart
- User can update quantity
- User can remove items
- User can proceed to checkout

Correct (including edge cases):

## Feature: Shopping Cart

### Happy Path
- User can add items to cart
- User can update item quantity (1-99)
- User can remove items from cart
- User can proceed to checkout with items in cart

### Edge Cases - Empty States
- [ ] Empty cart shows "Your cart is empty" message
- [ ] Empty cart shows "Continue shopping" link
- [ ] Checkout button is disabled when cart is empty

### Edge Cases - Quantity Boundaries
- [ ] Quantity cannot be set below 1 (minimum)
- [ ] Quantity cannot exceed 99 (maximum)
- [ ] Quantity cannot exceed available stock
- [ ] Non-numeric input is rejected (letters, symbols)
- [ ] Decimal quantities are rounded down

### Edge Cases - Inventory Changes
- [ ] Item removed from store while in cart shows warning
- [ ] Price change while in cart shows notification
- [ ] Stock reduction below cart quantity prompts adjustment
- [ ] Out-of-stock item cannot proceed to checkout

### Edge Cases - Concurrent Sessions
- [ ] Cart syncs across browser tabs
- [ ] Cart persists across login/logout
- [ ] Abandoned cart is preserved for 30 days

### Edge Cases - Error Conditions
- [ ] Network failure during add shows retry option
- [ ] Session expiry prompts re-login with cart preserved
- [ ] Invalid coupon code shows specific error message

Common edge case categories:

• Empty states (no data)
• Boundary values (min, max, zero)
• Invalid input (wrong type, format)
• Concurrent access (race conditions)
• Error conditions (network, timeout)
• State transitions (in-progress, cancelled)

Reference: Atlassian - Acceptance Criteria

Use Given-When-Then Format for Acceptance Criteria

Structure acceptance criteria using Given-When-Then (Gherkin) format. This format is unambiguous, directly translatable to automated tests, and forces thinking about preconditions, actions, and outcomes.

Incorrect (vague acceptance criteria):

## User Story: Password Reset

### Acceptance Criteria
- User can reset password
- Email is sent
- Password is changed
- Errors are handled properly

Correct (Given-When-Then format):

## User Story: Password Reset

### Acceptance Criteria

**Scenario 1: Successful password reset request**

Given I am on the login page And I have a registered account with email "user@example.com" When I click "Forgot password" And I enter "user@example.com" And I click "Send reset link" Then I should see "Check your email for reset instructions" And an email should be sent to "user@example.com" within 1 minute And the email should contain a reset link valid for 24 hours

**Scenario 2: Password reset with invalid email**

Given I am on the password reset page When I enter "notregistered@example.com" And I click "Send reset link" Then I should see "Check your email for reset instructions" And no email should be sent

Note: Same message shown to prevent email enumeration

**Scenario 3: Using the reset link**

Given I received a password reset email And the reset link is less than 24 hours old When I click the reset link And I enter a new password "NewSecure123!" And I confirm the password "NewSecure123!" And I click "Reset password" Then my password should be changed And I should be redirected to the login page And I should see "Password successfully reset"

**Scenario 4: Expired reset link**

Given I received a password reset email And the reset link is more than 24 hours old When I click the reset link Then I should see "This link has expired. Please request a new one." And I should see a link to request a new reset email

Benefits:

• QA can write tests directly from criteria
• Developers know exact expected behavior
• Edge cases are explicit, not discovered later

Reference: AltexSoft - Acceptance Criteria Best Practices

Ensure All Criteria Are Testable

Every acceptance criterion must be verifiable with a true/false answer. Subjective criteria like "user-friendly" or "fast" cannot be tested objectively and lead to disputes about whether work is complete.

Incorrect (untestable criteria):

## Acceptance Criteria

- The interface should be user-friendly
- The system should perform well
- Errors should be handled gracefully
- The design should look modern
- The experience should be intuitive

Correct (objectively testable criteria):

## Acceptance Criteria

### Usability (Testable)
- [ ] All form fields have visible labels
- [ ] Error messages appear within 2px of the invalid field
- [ ] Tab order follows visual layout (left-to-right, top-to-bottom)
- [ ] All interactive elements have focus indicators
- [ ] Forms can be submitted using Enter key

### Performance (Testable)
- [ ] Page loads in < 2 seconds on 3G (WebPageTest)
- [ ] Time to first byte < 200ms
- [ ] No layout shifts after initial render (CLS < 0.1)
- [ ] Search results appear within 500ms of typing

### Error Handling (Testable)
- [ ] Network errors show retry button + message
- [ ] Form validation errors are shown before submission
- [ ] 500 errors display error ID for support
- [ ] All errors are logged with stack traces

### Visual Design (Testable)
- [ ] Matches Figma design with < 5px variance
- [ ] Uses only colors from design system palette
- [ ] Typography matches style guide (font, size, weight)
- [ ] Icons are from approved icon library

Testability checklist:

• Can a machine verify this? (automation potential)
• Can two people agree if it passes? (objectivity)
• Is there a clear pass/fail threshold? (measurability)
• Can it be verified in isolation? (independence)

Reference: ProductPlan - Acceptance Criteria Definition

Maintain a Deferred Items Log

When you say "no" to a feature or change, capture it in a deferred items log. Good ideas that don't fit the current scope shouldn't be lost. A well-maintained log prevents re-litigation and provides a roadmap for future work.

Incorrect (rejected ideas disappear):

## Meeting Notes

Discussed adding dark mode - decided not to include.
Discussed mobile app - too much scope.
Discussed SSO integration - deferred.

// 6 months later:
// "Why don't we have dark mode?"
// "We discussed this... when was that?"
// "What was the reason?"
// Result: Re-discuss from scratch, waste time

Correct (structured deferred items log):

## Deferred Items Log - User Dashboard

### Purpose
This log captures features and changes that were considered but deferred
from the current release. Items here are not rejected—they're documented
for future consideration.

### How to Use This Log
1. Add items when descoping or rejecting features
2. Review during planning for future releases
3. Reference when stakeholders raise deferred items
4. Archive items after implementation or permanent rejection

---

### Active Deferred Items

#### DI-001: Dark Mode Support

| Field | Value |
|-------|-------|
| **Requested by** | Multiple users (Feature Request #234, #256, #289) |
| **Date deferred** | 2024-02-15 |
| **Original target** | v1.0 |
| **Deferred to** | v2.0 (tentative) |
| **Decision maker** | Product Director |

**Description:**
Add dark mode theme option to reduce eye strain and support
user preferences.

**Reason for deferral:**
Requires design system updates across all components. Estimated
3-week effort conflicts with Q1 launch deadline.

**Prerequisites for implementation:**
- Design system theme architecture
- Component audit for hardcoded colors
- Accessibility review for contrast ratios

**Estimated effort:** 3 weeks (1 designer, 2 developers)

**Business case:**
- 40% of users requested in feedback survey
- Competitive parity (competitors have it)
- Accessibility benefit

---

#### DI-002: Real-time Collaboration

| Field | Value |
|-------|-------|
| **Requested by** | Enterprise Customer Advisory Board |
| **Date deferred** | 2024-03-01 |
| **Original target** | v1.0 |
| **Deferred to** | v3.0+ (requires architecture change) |
| **Decision maker** | CTO |

**Description:**
Allow multiple users to view and edit dashboard simultaneously
with real-time cursor presence and live updates.

**Reason for deferral:**
Requires WebSocket infrastructure, conflict resolution system,
and presence service. Architectural complexity incompatible with
v1 timeline.

**Prerequisites for implementation:**
- WebSocket infrastructure
- Operational Transform or CRDT implementation
- Presence service
- Conflict resolution UX design

**Estimated effort:** 8-12 weeks (full team)

**Business case:**
- Top request from enterprise segment
- $500K ARR at risk without it
- Competitive differentiator

---

#### DI-003: SSO/SAML Integration

| Field | Value |
|-------|-------|
| **Requested by** | Sales (enterprise deals) |
| **Date deferred** | 2024-02-20 |
| **Original target** | v1.0 |
| **Deferred to** | v1.5 |
| **Decision maker** | Product Director |

**Description:**
Support enterprise single sign-on via SAML 2.0 and OIDC.

**Reason for deferral:**
Security review backlog - SSO requires 4-week security audit
that wouldn't complete before launch.

**Prerequisites for implementation:**
- Security team availability
- IdP test accounts (Okta, Azure AD, OneLogin)
- Enterprise customer beta testers

**Estimated effort:** 4 weeks (2 developers + security review)

**Business case:**
- Required for 80% of enterprise deals
- $200K pipeline blocked without it
- Standard enterprise expectation

---

### Deferred Items Summary

| ID | Item | Target | Effort | Business Value |
|----|------|--------|--------|----------------|
| DI-001 | Dark mode | v2.0 | 3w | Medium |
| DI-002 | Real-time collab | v3.0+ | 12w | High |
| DI-003 | SSO/SAML | v1.5 | 4w | High |
| DI-004 | Mobile app | v3.0+ | 16w | Medium |
| DI-005 | API webhooks | v2.0 | 2w | Medium |

### Recently Implemented (Archive)

| ID | Item | Implemented | Release |
|----|------|-------------|---------|
| DI-000 | CSV export | 2024-01-15 | v0.9 |

### Permanently Rejected

| ID | Item | Rejected | Reason |
|----|------|----------|--------|
| - | Blockchain integration | 2024-01-10 | No valid use case |

Deferred log requirements:

• Capture all descoped items
• Document reason for deferral
• Note prerequisites for future implementation
• Include business case for prioritization
• Review regularly during planning

Reference: ProductPlan - Product Backlog Management

Use Formal Change Request Process

All scope changes after requirements sign-off must go through a formal process. Without a process, changes sneak in through casual conversations, and scope creeps invisibly until deadlines slip.

Incorrect (informal change acceptance):

## How Changes Happen (Informally)

Stakeholder in Slack: "Hey, can we also add export to Excel?"
Developer: "Sure, shouldn't be too hard"

// No impact assessment
// No timeline adjustment
// No formal approval
// Result: 2-week delay discovered at deadline

Correct (formal change request process):

## Change Request Process

### Change Request Form

CR-2024-042: Add Excel Export

requester: Sarah Chen (Sales) date_submitted: 2024-03-15 priority: Medium

Change Description

Add ability to export report data to Excel format (.xlsx) in addition to current CSV export.

Business Justification

Enterprise customers (representing 40% of revenue) require Excel format for their internal reporting workflows. 3 deals worth $150K are blocked without this.

Current Scope Reference

PRD v2.1, Section 4.2: "Reports can be exported as CSV"

Proposed Change

Add Excel (.xlsx) export option alongside CSV.

Acceptance Criteria

• [ ] Export button shows CSV and Excel options
• [ ] Excel file opens correctly in Excel 2016+
• [ ] Formulas preserved where applicable
• [ ] Same data as CSV export

### Impact Assessment (Completed by Team)

Impact Assessment: CR-2024-042

Effort Estimate

development: 3 days testing: 1 day documentation: 0.5 days total: 4.5 days

Resource Impact

• Requires: 1 backend developer, 0.5 QA
• Conflicts with: None
• Dependencies: xlsx library evaluation

Timeline Impact

• Current deadline: April 15
• With this change: April 19 (4-day slip)
• Alternative: Defer to v2.1 (no slip)

Risk Assessment

Cost

development_cost: $4,500 (3 dev days × $1,500) opportunity_cost: Delays feature X by 1 week

Recommendation

APPROVE with v2.1 deferral (no deadline impact)

### Approval Workflow

┌──────────────────┐ │ Change Request │ │ Submitted │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ Impact Assessment│ ← Team Lead (2 business days) │ Completed │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ ┌──────────────┐ │ Review Board │────▶│ Rejected │ │ (PM + Eng Lead) │ │ (with reason)│ └────────┬─────────┘ └──────────────┘ │ Approved ▼ ┌──────────────────┐ ┌──────────────┐ │ Timeline/Budget │────▶│ Stakeholder │ │ Impact > 10%? │ Yes │ Approval │ └────────┬─────────┘ └──────┬───────┘ │ No │ ▼ ▼ ┌──────────────────────────────────────┐ │ Change Incorporated into Plan │ │ - Update PRD version │ │ - Adjust timeline/resources │ │ - Notify all stakeholders │ └──────────────────────────────────────┘

### Decision Record

| CR ID | Description | Decision | Date | Decider | Impact |
|-------|-------------|----------|------|---------|--------|
| CR-041 | Add dark mode | Rejected | 3/10 | PM | Out of scope |
| CR-042 | Excel export | Approved (v2.1) | 3/16 | PM | Deferred |
| CR-043 | Mobile support | Approved | 3/18 | Director | +2 weeks |

Change request criteria:

• All post-signoff changes require formal request
• Impact assessment before approval
• Clear approval authority defined
• Decision and rationale documented
• Stakeholders notified of timeline changes

Reference: PMI - Integrated Change Control

Assess Full Impact Before Approving Changes

Never approve a change request without full impact assessment. Small-seeming changes often have hidden costs in dependencies, testing, and downstream effects. "Just add a button" can mean weeks of work.

Incorrect (approving without assessment):

## Change Discussion

PM: "Can we add a 'share to Twitter' button?"
Dev: "Yeah, that's just a button and API call"
PM: "Great, approved!"

// Hidden impacts discovered during implementation:
// - Need Twitter developer account approval (2 weeks)
// - Need to handle OAuth flow
// - Need rate limiting
// - Need content preview generation
// - Need compliance review for data sharing
// Actual effort: 3 weeks, not 1 day

Correct (full impact assessment):

## Impact Assessment Template

### Change: Add "Share to Twitter" Button

#### Direct Effort

| Component | Task | Effort | Confidence |
|-----------|------|--------|------------|
| Frontend | Button UI and placement | 2h | High |
| Frontend | Twitter card preview | 4h | High |
| Backend | Twitter API integration | 8h | Medium |
| Backend | OAuth flow implementation | 16h | Medium |
| Backend | Rate limiting | 4h | High |
| Testing | Integration tests | 8h | High |
| Testing | Manual QA | 4h | High |
| **Subtotal** | | **46h** | |

#### Indirect Effort

| Area | Task | Effort | Confidence |
|------|------|--------|------------|
| DevOps | Twitter API credentials setup | 2h | High |
| Security | OAuth security review | 4h | Medium |
| Legal | Data sharing compliance | 8h | Low |
| Design | Share preview mockups | 4h | High |
| Docs | User documentation update | 2h | High |
| **Subtotal** | | **20h** | |

#### External Dependencies

| Dependency | Lead Time | Risk | Mitigation |
|------------|-----------|------|------------|
| Twitter developer account | 1-2 weeks | High | Apply immediately |
| Security review slot | 3-5 days | Medium | Book in advance |
| Legal review | 1 week | Low | Standard process |

#### Timeline Analysis

Current Timeline: Week 1 ████████ Feature A Week 2 ████████ Feature B Week 3 ████████ Feature C Week 4 ████████ Testing + Launch

With This Change: Week 1 ████████ Feature A Week 2 ███░░░░░ Feature B (partial) + Twitter setup Week 3 ░░░░████ Feature B (complete) + Security review Week 4 ████████ Feature C Week 5 ████████ Twitter feature Week 6 ████████ Testing + Launch

Impact: +2 weeks to launch

#### Risk Assessment

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Twitter API approval delayed | 30% | High (+2w) | Apply before approval |
| Twitter API changes | 10% | Medium | Abstract integration |
| Rate limit issues | 20% | Low | Implement backoff |
| Preview rendering bugs | 40% | Low | Extensive testing |

#### Opportunity Cost

What gets delayed or dropped:
- Feature C pushed to v2 (affects 3 customer commitments)
- OR: Deadline slips 2 weeks (affects marketing campaign)

#### Total Cost Summary

direct_effort: 46 hours (1.15 weeks) indirect_effort: 20 hours (0.5 weeks) waiting_time: 2 weeks (Twitter approval) risk_buffer: 1 week total_timeline_impact: 2-3 weeks

development_cost: $6,600 opportunity_cost: Delayed Feature C or launch hidden_costs:

• Ongoing Twitter API maintenance
• Rate limit monitoring
• Token refresh handling

### Recommendation

**Option A (Recommended):** Defer to v2
- Ship v1 on time
- Better user feedback on core features first
- Implement Twitter sharing with proper planning

**Option B:** Slip timeline by 2 weeks
- Include Twitter sharing
- Delays marketing campaign
- Risk of further delays

**Option C:** Drop Feature C
- Include Twitter sharing
- On-time launch
- Breaks 3 customer commitments

Impact assessment must include:

• Direct and indirect effort
• External dependencies with lead times
• Timeline visualization
• Risk assessment
• Opportunity cost analysis
• Clear recommendation

Reference: Wrike - Change Impact Analysis

Implement Scope Freeze Periods

Establish scope freeze periods before major milestones. Continuous changes up until launch create instability, testing gaps, and team burnout. Freeze scope to allow stabilization.

Incorrect (changes until launch day):

## Project Timeline

Week 1-4: Development
Week 5: Testing
Week 6: Launch

// Reality:
// Week 5 (testing): "Can we also add this small thing?"
// Week 5.5: New code merged during testing
// Week 6 (launch day): "One more tiny change"
// Result: Untested code in production, launch day bugs

Correct (defined freeze periods):

## Scope Freeze Policy

### Freeze Levels

| Level | Allowed Changes | Approval Required |
|-------|-----------------|-------------------|
| **Green** (Normal) | Any approved changes | Standard process |
| **Yellow** (Soft Freeze) | Bug fixes, critical issues only | Engineering Lead |
| **Red** (Hard Freeze) | Blocking bugs only | VP Engineering |
| **Black** (Code Freeze) | Emergency hotfixes only | CTO |

### Project Timeline with Freeze Periods

Week 1 ████████████████ Development [GREEN] Week 2 ████████████████ Development [GREEN] Week 3 ████████████████ Development [GREEN] Week 4 ████████████████ Feature Complete [YELLOW starts] Week 5 ████████████████ Testing/QA [RED starts] Week 6 ██████░░░░░░░░░░ Final Testing [BLACK starts] Week 6.5 ░░░░░░██████████ Launch [BLACK] Week 7 ████████████████ Post-launch [Return to GREEN]

### Freeze Entry Criteria

**Yellow (Soft Freeze) - 2 weeks before launch:**
- [ ] All planned features code complete
- [ ] No open P1 bugs
- [ ] All integrations working
- [ ] Performance targets met

**Red (Hard Freeze) - 1 week before launch:**
- [ ] All features tested and approved
- [ ] No open P1 or P2 bugs
- [ ] Load testing passed
- [ ] Security review complete
- [ ] Documentation complete

**Black (Code Freeze) - 3 days before launch:**
- [ ] Release candidate tagged
- [ ] Staging environment matches production
- [ ] Rollback plan tested
- [ ] On-call schedule confirmed

### Change Approval During Freeze

**Yellow Freeze - Change Request:**

request_type: soft_freeze_change requestor: Developer Name change_description: | Fix timezone handling in date picker

justification: | Users in non-US timezones see wrong dates. Affects 30% of user base.

risk_assessment: | Low risk - isolated change, well-tested Rollback: Revert single commit

testing_plan: |

• Unit tests added
• Manual testing in 5 timezones
• Staging verification

approval: Engineering Lead

**Red Freeze - Blocking Bug Only:**

request_type: hard_freeze_change requestor: Developer Name bug_id: BUG-1234 severity: P1 - Blocking

bug_description: | Payment processing fails for amounts > $10,000

business_impact: |

• Enterprise customers cannot complete purchases
• $50K+ revenue at risk per day

fix_description: | Integer overflow in amount calculation One-line fix in payment_processor.py

testing_completed:

• [ ] Unit tests pass
• [ ] Integration tests pass
• [ ] Manual verification on staging
• [ ] Regression suite green

rollback_plan: | Revert commit abc123 Tested: Yes, verified rollback works

approval_chain:

• Engineering Lead: Pending
• VP Engineering: Pending

### Exceptions Process

Even during Black Freeze, some changes may be necessary:

Emergency Change Protocol

1. Identify: Is this truly blocking launch?

• Data loss risk? → Yes
• Security vulnerability? → Yes
• Feature doesn't work perfectly? → No (launch anyway)

2. Assess: What's the minimum fix?

• Fix the symptom, not root cause
• Smallest possible change
• No refactoring

3. Approve: Who needs to sign off?

• CTO for any Black Freeze change
• Security Lead for security issues
• Legal for compliance issues

4. Execute: How to deploy safely?

• Feature flag if possible
• Staged rollout (1% → 10% → 100%)
• Monitoring for 30 minutes between stages

5. Document: Post-incident review

• Why was this missed earlier?
• How to prevent in future?

### Communication

Freeze Announcement Template

to: all-engineering, stakeholders subject: "[Dashboard] Entering YELLOW FREEZE" body: | Effective: Monday, March 18

What this means:

• No new features will be added
• Only bug fixes and critical issues
• All changes require Eng Lead approval

Current status:

• Features complete: 12/12 ✓
• Open P1 bugs: 0 ✓
• Open P2 bugs: 3 (being addressed)

Next milestone: RED FREEZE on March 25

Scope freeze requirements:

• Define freeze levels with clear criteria
• Establish freeze timeline in project plan
• Document approval process for each level
• Communicate freeze transitions to all
• Post-mortem any freeze violations

Reference: Atlassian - Release Management Best Practices

Version All Specification Documents

Maintain version history for all specification documents. Without versioning, teams work from outdated specs, stakeholders reference different versions, and decisions lack audit trails.

Incorrect (unversioned documents):

## PRD: User Dashboard

Last updated: March 2024

// Problems:
// - Which "March 2024" version?
// - What changed from last version?
// - Who approved changes?
// - Designer has v1, developer has v3
// Result: Features built to wrong spec

Correct (versioned with change history):

## PRD: User Dashboard

| Version | Date | Author | Status |
|---------|------|--------|--------|
| 3.1 | 2024-03-20 | Carol Davis | **Current** |
| 3.0 | 2024-03-15 | Carol Davis | Superseded |
| 2.0 | 2024-02-28 | Carol Davis | Superseded |
| 1.0 | 2024-02-01 | Carol Davis | Superseded |

### Version History

#### v3.1 (2024-03-20) - Minor Update
**Approved by:** Engineering Lead
**Changes:**
- Clarified widget refresh behavior (CR-045)
- Fixed typo in acceptance criteria
- No scope change

#### v3.0 (2024-03-15) - Scope Change
**Approved by:** Product Director
**Changes:**
- Added: Excel export capability (CR-042)
- Removed: Real-time collaboration (deferred to v2)
- Modified: Dashboard layout (3 columns → 2 columns)

**Rationale:** Excel export required for enterprise deals. Real-time
collaboration descoped to meet deadline.

#### v2.0 (2024-02-28) - Requirements Refinement
**Approved by:** Product Director
**Changes:**
- Added: Performance requirements (p95 < 1s)
- Added: Accessibility requirements (WCAG 2.1 AA)
- Modified: Widget types expanded from 3 to 5

#### v1.0 (2024-02-01) - Initial Version
**Approved by:** Product Director
**Changes:**
- Initial PRD created from discovery research

---

### Document Control

**Canonical Location:** `https://docs.company.com/prd/user-dashboard`
**Source of Truth:** This document (not Slack, email, or verbal)

**Version Numbering:**
- Major (X.0): Scope changes
- Minor (X.Y): Clarifications, no scope impact

**Review Required For:**
- Any scope change: Product Director
- Technical changes: Engineering Lead
- Timeline changes: Project Manager

### Change Tracking Table

| Section | v2.0 | v3.0 | v3.1 |
|---------|------|------|------|
| 1. Overview | No change | No change | No change |
| 2. User Stories | Added US-5,6 | No change | No change |
| 3. Requirements | +Performance | -Real-time | No change |
| 4. Acceptance | Updated | +Excel export | Clarified |
| 5. Technical | No change | Updated | No change |

### Stakeholder Notification

When a new version is published:
1. Email sent to all stakeholders
2. Slack notification in #proj-dashboard
3. Meeting scheduled if scope changes
4. Acknowledgment required from leads

Notification Template

subject: "[Dashboard PRD] v3.1 Published" to: stakeholder-list body: | PRD v3.1 has been published.

Summary of Changes

• Clarified widget refresh behavior
• No scope or timeline impact

Action Required

• Review changes by EOD Friday
• Reply to confirm receipt

Document Link

https://docs.company.com/prd/user-dashboard

Document versioning requirements:

• Every spec document has version number
• Change history with dates and authors
• Approval recorded for each version
• Stakeholders notified of updates
• Single canonical location (no copies)

Reference: IEEE 830-1998 - Software Requirements Specifications

Keep Documentation Accessible and Searchable

Store documentation where the team can find it. Inaccessible docs are useless docs. Optimize for discoverability, not organization aesthetics.

Incorrect (documentation scattered or hidden):

## Where Documentation Lives

- PRD v1: Alice's Google Drive
- PRD v2: Shared folder (which one?)
- Technical notes: Bob's personal Notion
- API docs: README in repo (which branch?)
- Meeting notes: Various Slack threads
- Decisions: "I think we discussed this in email"

// Finding information requires asking around
// New team members can't self-serve
// Knowledge leaves when people leave

Correct (centralized and searchable):

## Documentation Accessibility Standards

### Central Hub

All project documentation accessible from one entry point:

📁 Project Dashboard - Documentation Hub │ ├── 📄 README (Start Here) │ └── Links to all key documents │ ├── 📁 Product │ ├── PRD (current version) │ ├── User Research │ └── Roadmap │ ├── 📁 Technical │ ├── Architecture Overview │ ├── API Documentation │ └── ADRs (Decision Records) │ ├── 📁 Design │ ├── Design System │ └── Figma Links │ ├── 📁 Process │ ├── Meeting Notes │ ├── Retrospectives │ └── Launch Checklists │ └── 📁 Archive └── Superseded documents

### Searchability Requirements

**Text-based formats:**
- Use Markdown, not PDFs
- Plain text over images of text
- Headings for structure (enables TOC)
- Keywords in document body

**Naming conventions:**

Good - searchable, sortable

2024-03-15-prd-user-dashboard-v3.md adr-005-database-selection.md meeting-2024-03-15-sprint-planning.md

Bad - unclear, unsearchable

doc.md final_FINAL_v2.docx notes.txt

**Tagging and metadata:**

--- title: User Dashboard PRD type: prd project: dashboard status: approved created: 2024-02-01 updated: 2024-03-15 owner: carol.davis tags:

• dashboard
• analytics
• q1-2024

---

### Access Control

| Document Type | Access Level | Reason |
|---------------|--------------|--------|
| PRD | All employees | Transparency |
| Technical Spec | Engineering + Product | Technical detail |
| Salary data | HR + Exec | Confidential |
| Security audit | Security team | Sensitive |

**Default:** Public within organization unless specifically restricted.

### Discoverability Aids

**README in every folder:**

Technical Documentation

This folder contains technical specifications for Project Dashboard.

Quick Links

• Architecture Overview - System design
• API Reference - Endpoint documentation
• ADRs - Why we made key decisions

Can't Find Something?

• Search the wiki for keywords
• Ask in #proj-dashboard Slack
• Check the Archive folder

**Glossary for project-specific terms:**

Glossary

### Maintenance

**Monthly documentation review:**
- [ ] Update broken links
- [ ] Archive obsolete docs
- [ ] Verify access permissions
- [ ] Check search indexing
- [ ] Update README quick links

**Documentation owner responsibilities:**
- Keep assigned docs current
- Respond to questions within 24h
- Mark deprecated docs clearly
- Redirect to current versions

Accessibility requirements:

• Single entry point for all docs
• Text-based searchable formats
• Consistent naming conventions
• Appropriate access controls
• Regular maintenance schedule

Reference: Write the Docs - Documentation Principles

Use Consistent Document Templates

Use standardized templates for recurring document types. Consistent structure makes documents easier to write, review, and find information in. Ad-hoc formats waste time on structure decisions.

Incorrect (ad-hoc document structure):

## PRD #1 (by Alice)
- Overview
- Features
- Timeline

## PRD #2 (by Bob)
1. Problem Statement
2. User Stories
3. Success Metrics
4. Technical Requirements
5. Risks

## PRD #3 (by Carol)
Executive Summary
Background
Proposal
Next Steps

// Every PRD is different
// Reviewers can't find information consistently
// New team members don't know what to include

Correct (standardized template):

## PRD Template v2.0

Every PRD follows this structure. Sections may be brief but cannot
be omitted. Use "N/A" with justification if truly not applicable.

---

### 1. Document Control

title: [Feature Name] PRD version: [X.Y] status: [Draft | In Review | Approved | Superseded] owner: [PM Name] created: [Date] last_updated: [Date] reviewers:

• name: [Name]

role: [Role] status: [Pending | Approved | Requested Changes]

### 2. Executive Summary
*2-3 sentences. What are we building and why?*

[Write summary here]

### 3. Problem Statement
*What problem does this solve? For whom? How do we know it's a problem?*

**Problem:** [Description]
**Affected users:** [User segments]
**Evidence:** [Data, research, customer quotes]

### 4. Goals and Success Metrics

| Goal | Metric | Baseline | Target | Timeline |
|------|--------|----------|--------|----------|
| [Goal 1] | [Metric] | [Current] | [Target] | [When] |

### 5. User Stories

As a [user type] I want to [action] So that [benefit]

Acceptance Criteria:

• [ ] [Criterion 1]
• [ ] [Criterion 2]

### 6. Scope

**In Scope:**
- [Item 1]
- [Item 2]

**Out of Scope:**
- [Item 1] - [Reason]

**Future Considerations:**
- [Item 1] - [Tentative timeline]

### 7. Requirements

#### 7.1 Functional Requirements
| ID | Requirement | Priority | Notes |
|----|-------------|----------|-------|
| FR-001 | [Requirement] | [Must/Should/Could] | [Notes] |

#### 7.2 Non-Functional Requirements
| Category | Requirement |
|----------|-------------|
| Performance | [Requirement] |
| Security | [Requirement] |
| Accessibility | [Requirement] |

### 8. Dependencies and Risks

| Dependency/Risk | Type | Impact | Mitigation |
|-----------------|------|--------|------------|
| [Item] | [Dependency/Risk] | [H/M/L] | [Action] |

### 9. Timeline

| Milestone | Date | Dependencies |
|-----------|------|--------------|
| [Milestone] | [Date] | [Dependencies] |

### 10. Appendix
*Supporting materials, research, mockups, technical details*

---

## Template Usage Notes

- **Bold sections** are required
- Provide brief answers; link to details
- Update version number on each significant change
- Get reviewer sign-off before development starts

Template Library

Template Maintenance

• Review templates quarterly
• Collect feedback from users
• Update based on common omissions
• Version templates (v1.0, v2.0)

**Template requirements:**
- Standard structure for each document type
- Required vs optional sections marked
- Examples and guidance included
- Templates versioned and maintained
- Team trained on usage

Reference: [Google Technical Writing - Document Templates](https://developers.google.com/tech-writing)

Document Key Decisions with Context

Record significant decisions with their context, options considered, and rationale. Without decision records, teams re-debate settled issues, and new members don't understand why things are done certain ways.

Incorrect (decisions without context):

## Notes

- Decided to use PostgreSQL
- Will implement caching
- Chose React for frontend

// 6 months later:
// New developer: "Why PostgreSQL instead of MongoDB?"
// Team: "I think there was a reason..."
// Result: Re-evaluate decision, waste time, or wrong assumptions

Correct (Architecture Decision Records):

## ADR-005: Database Selection for User Dashboard

### Status
**Accepted** - 2024-02-15

### Context
We need to select a database for the new User Dashboard feature. The
dashboard displays aggregated analytics data with the following
characteristics:
- Read-heavy workload (95% reads, 5% writes)
- Complex aggregation queries (time series, grouping)
- 10M+ rows expected within 1 year
- Need for ACID transactions for billing data
- Team expertise primarily in relational databases

### Decision Drivers
1. Query complexity (aggregations, joins)
2. Team expertise and hiring pool
3. Operational complexity
4. Cost at scale
5. Ecosystem and tooling

### Options Considered

#### Option A: PostgreSQL
**Pros:**
- Excellent aggregation support (window functions, CTEs)
- Strong ACID compliance
- Team has 5+ years experience
- Rich ecosystem (pgAdmin, pgBouncer, Citus for scale)
- Active community, well-documented

**Cons:**
- Scaling requires more planning than NoSQL
- Connection pooling needed at scale

#### Option B: MongoDB
**Pros:**
- Flexible schema for evolving requirements
- Built-in sharding
- Good for document-oriented data

**Cons:**
- Aggregation pipeline less intuitive than SQL
- Team would need training
- ACID only at document level
- Joins require application-level handling

#### Option C: TimescaleDB (PostgreSQL extension)
**Pros:**
- Optimized for time-series data
- Compatible with PostgreSQL
- Automatic partitioning

**Cons:**
- Additional operational complexity
- May be premature optimization
- Smaller community than vanilla PostgreSQL

### Decision
**Selected: Option A - PostgreSQL**

### Rationale
1. **Query needs:** Our analytics require complex joins and aggregations
   that PostgreSQL handles natively with excellent performance.

2. **Team expertise:** Our team has deep PostgreSQL knowledge. MongoDB
   would require 2-3 weeks of training with ongoing learning curve.

3. **ACID requirements:** Billing data requires strong consistency.
   PostgreSQL provides this across tables, not just documents.

4. **Scale path:** At our projected 10M rows, PostgreSQL performs well.
   If we grow beyond, options include read replicas, Citus extension,
   or migration to TimescaleDB (compatible).

5. **Ecosystem:** Better tooling for our use case (Metabase, Grafana
   integration, migration tools).

### Consequences

**Positive:**
- Team can start immediately without training
- Leverage existing monitoring and backup infrastructure
- Straightforward aggregation query development

**Negative:**
- Must plan connection pooling for high concurrency
- May need to revisit for time-series optimization later
- Schema migrations require more care than schemaless DB

### Related Decisions
- ADR-003: Caching Strategy (impacts read patterns)
- ADR-007: Data Retention Policy (impacts table size)

### Review Date
Re-evaluate in 12 months or when data exceeds 50M rows.

---

## ADR Template

ADR-[NUMBER]: [TITLE]

Status

[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

Context

[What is the situation? What forces are at play?]

Decision Drivers

[What criteria matter most?]

Options Considered

[List options with pros/cons]

Decision

[What was decided?]

Rationale

[Why this option over others?]

Consequences

[What are the positive and negative results?]

Related Decisions

[Links to related ADRs]

Review Date

[When to revisit this decision]

Decision record requirements:

• Record significant technical and product decisions
• Include context and constraints
• Document options considered
• Explain rationale clearly
• Note consequences and review timeline

Reference: ADR GitHub - Architecture Decision Records

Define Project Terminology in a Glossary

Create a glossary of project-specific terms. Without defined terminology, team members interpret words differently, leading to misaligned implementations and stakeholder confusion.

Incorrect (assumed shared understanding):

## Requirements

- Display user metrics on the dashboard
- Show conversion data for the funnel

// Designer thinks: "metrics" = charts and graphs
// Developer thinks: "metrics" = numbers in cards
// PM thinks: "metrics" = specific KPIs (DAU, MAU)

// Result: Three different interpretations implemented

Correct (defined glossary):

## Project Glossary - User Dashboard

### Purpose
This glossary defines terms used in the User Dashboard project.
All team members should use these definitions consistently.
When writing documentation, use terms exactly as defined here.

---

### Core Concepts

#### Dashboard
The main analytics view where users see their key metrics. Located
at `/app/dashboard`. Not to be confused with Admin Dashboard (different
feature) or Home Page (marketing site).

**Synonyms (avoid):** Home, Analytics Page, Stats
**Use instead:** Dashboard, User Dashboard

#### Widget
A single component displayed on the Dashboard showing one metric or
visualization. Widgets can be:
- **Metric Widget:** Displays a single number (e.g., "Total Users: 1,234")
- **Chart Widget:** Displays a visualization (line chart, bar chart)
- **Table Widget:** Displays tabular data

**Not to be confused with:** Card (generic UI component), Tile (deprecated term)

#### Metric
A quantifiable measurement tracked in the system. Examples:
- DAU (Daily Active Users)
- Conversion Rate
- Revenue

**Note:** "Metric" refers to the data point, not its visual representation.
The visual representation is a Widget.

---

### User Types

#### End User
A person who uses the product to accomplish their goals. Has a user
account and logs in to access features.

**Not:** Admin, Support Staff, Developer

#### Account Admin
An End User with administrative privileges. Can manage team members,
billing, and settings for their organization.

**Also called:** Admin (in user-facing UI only)
**Not to be confused with:** System Admin (internal Ops role)

#### Visitor
A person browsing the marketing site without logging in.
Has no account yet.

---

### Metrics Definitions

#### DAU (Daily Active Users)
Count of unique users who performed at least one meaningful action
in the past 24 hours.

**Meaningful action:** Login, create/edit content, or export data.
**Excludes:** Passive page views, automated API calls.

#### MAU (Monthly Active Users)
Count of unique users who performed at least one meaningful action
in the past 30 days.

**Calculation:** Rolling 30-day window, not calendar month.

#### Conversion Rate
Percentage of Visitors who become End Users.

**Formula:** (New signups / Unique visitors) × 100
**Time period:** Calculated weekly by default.

#### Churn Rate
Percentage of paying users who cancel within a period.

**Formula:** (Cancellations / Starting subscribers) × 100
**Time period:** Monthly.

---

### Technical Terms

#### API
Application Programming Interface. The programmatic interface for
integrating with our system.

**Public API:** Documented endpoints available to customers.
**Internal API:** Endpoints for internal services only.

#### Webhook
An HTTP callback triggered by system events. Customers configure
webhooks to receive real-time notifications.

---

### Deprecated Terms

| Deprecated | Use Instead | Reason |
|------------|-------------|--------|
| Tile | Widget | Standardization |
| Stats | Metrics | Precision |
| Panel | Dashboard | Clarity |
| Customer | End User / Account | Ambiguity |

---

### Adding to This Glossary

When introducing a new term:
1. Check if an existing term covers the concept
2. Add definition with clear boundaries
3. Note what it's NOT (to prevent confusion)
4. List synonyms to avoid
5. Update related documentation

**Template:**

[Term]

[Clear definition in 1-3 sentences]

Also called: [Acceptable synonyms, if any] Not to be confused with: [Similar but different terms] Avoid: [Terms that should not be used]

Glossary requirements:

• Define all project-specific terms
• Clarify what terms do NOT mean
• Include deprecated terms with alternatives
• Update when new concepts are introduced
• Reference in all project documentation

Reference: Plain Language Guidelines - Definitions

Maintain Single Source of Truth

Designate one canonical location for each document type. Multiple copies lead to version drift, conflicting information, and wasted time determining which is correct.

Incorrect (multiple sources):

## Where to Find Requirements

- PRD is in Google Docs (shared by PM)
- Technical spec is in Confluence
- User stories are in Jira
- API docs are in Notion
- Designs are in Figma (some also in Google Drive)

// Developer: "Which requirements doc is current?"
// PM: "The Google Doc, but some updates are in Jira"
// Developer: "Which Jira tickets?"
// Result: 2 hours finding correct requirements

Correct (single source per document type):

## Documentation Sources of Truth

### Document Locations

| Document Type | Canonical Location | Format | Owner |
|---------------|-------------------|--------|-------|
| PRD | Confluence: /projects/dashboard/prd | Wiki | PM |
| Technical Spec | Confluence: /projects/dashboard/tech | Wiki | Tech Lead |
| User Stories | Jira: Dashboard Epic | Jira tickets | PM |
| API Docs | Swagger: /api/dashboard | OpenAPI | Backend Lead |
| Designs | Figma: Dashboard Project | Figma | Designer |
| Meeting Notes | Confluence: /projects/dashboard/meetings | Wiki | Rotating |

### Linking Policy

All documents link to each other:

prd: links_to:

• technical_spec: "Implementation details"
• designs: "Visual specifications"
• user_stories: "Detailed requirements"

links_from:

• project_page: "Main PRD link"

technical_spec: links_to:

• api_docs: "API details"
• architecture_diagrams: "System design"

links_from:

• prd: "Technical reference"

### Prohibited Practices

**Never:**
- Email spec documents as attachments
- Copy sections into Slack messages
- Create "local copies" of shared docs
- Make decisions in documents not linked to source

**Instead:**
- Share links to canonical location
- Quote with link to source
- Edit the source document
- Update source, then discuss

### Update Protocol

Document updated │ ▼ ┌─────────────────────┐ │ Update source doc │ │ (canonical location)│ └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ Increment version │ │ Update changelog │ └─────────┬───────────┘ │ ▼ ┌─────────────────────┐ │ Notify stakeholders │ │ with link to source │ └─────────────────────┘

### Cross-Reference Template

Every document header includes:

--- Document: User Dashboard PRD Version: 3.1 Last Updated: 2024-03-20 Owner: Carol Davis (PM)

Related Documents:

• Technical Spec: [link]
• Designs: [link]
• User Stories: [Jira Epic link]
• API Docs: [Swagger link]

This is the CANONICAL source for product requirements. Other copies are not authoritative. ---

Single source requirements:

• One canonical location per document type
• All copies are references, not sources
• Links between related documents
• Clear ownership and update protocol
• Header identifies canonical status

Reference: Atlassian - Documentation Best Practices

Identify and Prioritize Dependencies

Map dependencies between features and prioritize blocking work first. A high-priority feature is useless if it depends on unfinished low-priority work. Dependencies determine actual execution order.

Incorrect (ignoring dependencies):

## Sprint Planning

Sprint 1: User Dashboard (highest priority)
Sprint 2: Analytics API
Sprint 3: Authentication System

// Problem: Dashboard needs Analytics API
// Analytics API needs Authentication
// Sprint 1 work is blocked from day 1

Correct (dependency-aware sequencing):

## Feature Dependencies

graph LR A[Authentication] --> B[Analytics API] B --> C[User Dashboard] A --> D[User Profile] D --> C

### Dependency Analysis

| Feature | Depends On | Blocks | Priority |
|---------|------------|--------|----------|
| Authentication | None | Analytics, Profile | P0 (Critical Path) |
| Analytics API | Authentication | Dashboard | P0 (Critical Path) |
| User Profile | Authentication | Dashboard | P1 |
| User Dashboard | Analytics, Profile | None | P1 |

### Revised Sprint Plan

**Sprint 1: Foundation (Unblock everything)**
- Authentication System (no dependencies)
- Begin Analytics API (parallel after auth done)

**Sprint 2: Data Layer**
- Complete Analytics API
- User Profile

**Sprint 3: UI Layer**
- User Dashboard (all dependencies satisfied)

### Critical Path
Authentication → Analytics API → Dashboard

_Any delay in critical path delays final delivery_

Dependency management tips:

• Identify dependencies during planning, not during sprint
• Prioritize work that unblocks other work
• Consider dependency cost in effort estimates
• Create interface contracts early to enable parallel work

Reference: Eleken - Product Feature Prioritization

Use Kano Model for Customer Satisfaction Prioritization

The Kano model categorizes features by how they affect customer satisfaction: Basic (expected), Performance (more is better), and Delighters (unexpected joy). This prevents over-investing in basics while missing delighters.

Incorrect (treating all features equally):

## Feature Investment

Equal effort on:
- Bug-free login (users expect this)
- Faster search (users appreciate this)
- Confetti on milestones (users love this)

// Over-engineering login adds no satisfaction
// Under-investing in search frustrates users
// Missing delighters makes product forgettable

Correct (Kano-informed prioritization):

## Feature Categorization - Kano Model

### Basic Needs (Must be present, no extra satisfaction)
_Users expect these; absence causes dissatisfaction_

| Feature | Investment Strategy |
|---------|---------------------|
| Login works reliably | Meet threshold, don't over-invest |
| Data doesn't get lost | Table stakes, not a differentiator |
| Pages load eventually | Basic functionality, not a selling point |

**Strategy:** Ensure quality, minimize excess investment

---

### Performance Needs (More is better, linear satisfaction)
_Users appreciate improvements proportionally_

| Feature | Investment Strategy |
|---------|---------------------|
| Search speed | Every 100ms improvement adds value |
| Storage space | More is always appreciated |
| Export formats | Each new format adds incremental value |

**Strategy:** Invest based on competitive positioning

---

### Delighters (Unexpected, exponential satisfaction)
_Users don't expect these; presence creates loyalty_

| Feature | Investment Strategy |
|---------|---------------------|
| Keyboard shortcuts | Power users will evangelize |
| Smart suggestions | "It read my mind!" moments |
| Celebration animations | Emotional connection |

**Strategy:** Small investment, high differentiation potential

---

### Investment Allocation
- 50% on Performance (competitive advantage)
- 30% on Basics (meet expectations)
- 20% on Delighters (create loyalty)

Kano survey technique: Ask both: "How would you feel if we had X?" and "How would you feel if we didn't have X?"

Reference: AltexSoft - Prioritization Techniques

Use MoSCoW Method for Scope Prioritization

Categorize requirements into Must have, Should have, Could have, and Won't have. This framework forces explicit prioritization decisions and creates clear expectations about what's essential versus optional.

Incorrect (flat priority list):

## Feature Requirements

1. User login
2. User registration
3. Social login
4. Two-factor authentication
5. Password reset
6. Remember me
7. Session timeout
8. Biometric login

// All items appear equal priority
// Team debates endlessly about what to build first
// Stakeholders expect everything in v1

Correct (MoSCoW prioritization):

## Feature Requirements - MoSCoW Prioritization

### Must Have (Required for launch)
- User login with email/password
- User registration
- Password reset via email
- Session timeout after 24h inactivity

_Rationale: Core authentication required for any user access_

### Should Have (Important, not critical)
- Remember me functionality
- Account lockout after failed attempts
- Login activity notifications

_Rationale: Security and convenience features expected by users_

### Could Have (Nice to have if time permits)
- Social login (Google, GitHub)
- Two-factor authentication
- Login location tracking

_Rationale: Valuable but not blocking; can be added post-launch_

### Won't Have (This release)
- Biometric login (mobile-only feature)
- Single sign-on (enterprise tier)
- Passwordless email links

_Rationale: Requires additional infrastructure; scheduled for Q3_

MoSCoW decision criteria:

• Must: System doesn't work without it
• Should: Significant value but workarounds exist
• Could: Nice to have; users won't complain if missing
• Won't: Explicitly deferred (not forgotten)

Reference: Aha! - PRD Templates

Use RICE Scoring for Data-Driven Prioritization

When you have multiple competing features, use RICE (Reach × Impact × Confidence ÷ Effort) to score them objectively. This removes gut-feel bias and creates defensible prioritization decisions.

Incorrect (opinion-based prioritization):

## Feature Backlog

| Feature | Priority |
|---------|----------|
| Dark mode | High (CEO wants it) |
| Search improvement | Medium |
| Bulk export | Low |
| Performance optimization | Medium |

// Priorities based on who asked loudest
// No data to justify decisions
// Changes with every meeting

Correct (RICE scoring):

## Feature Backlog - RICE Scoring

**Formula:** RICE = (Reach × Impact × Confidence) ÷ Effort

| Feature | Reach | Impact | Confidence | Effort | RICE Score |
|---------|-------|--------|------------|--------|------------|
| Search improvement | 5000 users/qtr | 2 (high) | 80% | 3 weeks | **2,667** |
| Performance optimization | 8000 users/qtr | 1 (medium) | 90% | 2 weeks | **3,600** |
| Bulk export | 500 users/qtr | 2 (high) | 70% | 1 week | **700** |
| Dark mode | 2000 users/qtr | 0.5 (low) | 100% | 2 weeks | **500** |

### Prioritized Roadmap
1. **Performance optimization** (RICE: 3,600) - Sprint 1
2. **Search improvement** (RICE: 2,667) - Sprint 2
3. **Bulk export** (RICE: 700) - Sprint 3
4. **Dark mode** (RICE: 500) - Backlog

### Scoring Definitions

**Reach:** Users affected per quarter
**Impact:** 3 = massive, 2 = high, 1 = medium, 0.5 = low, 0.25 = minimal
**Confidence:** Percentage certainty in estimates
**Effort:** Person-weeks required

When to use RICE:

• Multiple competing features
• Need to justify decisions to stakeholders
• Want to remove HiPPO (highest paid person's opinion) bias

Reference: Fibery - RICE Prioritization Method

Map Features by Value vs Effort

Plot features on a 2×2 matrix of value (user/business benefit) versus effort (development cost). This visualization immediately reveals quick wins (high value, low effort) and time sinks (low value, high effort).

Incorrect (linear backlog):

## Backlog

1. Redesign homepage
2. Add export to PDF
3. Fix email typo
4. Build recommendation engine
5. Update footer links
6. Implement A/B testing framework

// No visibility into which items are quick wins
// Team might work on high-effort, low-value items first

Correct (value/effort matrix):

## Feature Prioritization Matrix

                    HIGH VALUE
                        │
    ┌───────────────────┼───────────────────┐
    │                   │                   │
    │   QUICK WINS      │   BIG BETS        │
    │   Do First        │   Plan Carefully  │
    │                   │                   │
    │ • Fix email typo  │ • Recommendation  │
    │ • Update footer   │   engine          │
    │ • Add PDF export  │ • Redesign        │
    │                   │   homepage        │
LOW ├───────────────────┼───────────────────┤ HIGH
EFFORT                  │                   EFFORT
    │   FILL-INS        │   TIME SINKS      │
    │   Do If Idle      │   Avoid/Defer     │
    │                   │                   │
    │ • Minor UI tweaks │ • A/B testing     │
    │ • Doc updates     │   framework       │
    │                   │ • Legacy system   │
    │                   │   rewrite         │
    │                   │                   │
    └───────────────────┼───────────────────┘
                        │
                    LOW VALUE

## Prioritization Order
1. **Quick Wins** - Immediate, high ROI
2. **Big Bets** - Schedule with proper planning
3. **Fill-ins** - Use for sprint padding
4. **Time Sinks** - Avoid or significantly descope

Estimation guidance:

• Value: User feedback, revenue impact, strategic alignment
• Effort: T-shirt sizes (S/M/L/XL) or story points
• Re-evaluate quarterly as circumstances change

Reference: ProductLift - Product Prioritization Frameworks

State Requirements Without Prescribing Solutions

Requirements should describe what the system must do, not how to implement it. Prescribing solutions constrains developers and may result in suboptimal implementations.

Incorrect (solution prescribed):

## Requirements

- Use Redis to cache user sessions
- Implement a modal dialog for confirmations
- Store files in AWS S3 buckets
- Use websockets for real-time updates
- Add a dropdown menu for category selection

Correct (intent without solution):

## Requirements

### Session Management
- Sessions must persist across page refreshes
- Sessions must expire after 24 hours of inactivity
- Session data must be accessible from any server instance

_Implementation note: Team to decide caching solution (Redis, Memcached, database-backed)_

### Confirmation UX
- User must confirm before destructive actions (delete, cancel)
- Confirmation must clearly state the consequence
- User must be able to cancel without data loss

_Implementation note: Modal, inline confirmation, or separate page—team decides based on context_

### File Storage
- Uploaded files must be accessible for 7 days minimum
- Files must be retrievable via unique URL
- Maximum file size: 50MB

_Implementation note: Storage provider selection is a technical decision_

### Real-time Updates
- Users must see new messages within 5 seconds
- No manual refresh required for updates
- Updates must work on mobile networks

_Implementation note: Websockets, SSE, or polling—based on infrastructure constraints_

When to specify implementation:

• Regulatory/compliance requirements mandate specific technology
• Existing infrastructure constrains options
• Team has explicitly requested guidance

Reference: Jama Software - How to Write an Effective PRD

Use Consistent Terminology with a Glossary

When different documents use different terms for the same concept—"user" vs "customer" vs "account holder"—confusion spreads. Create a glossary defining key terms and use them consistently throughout all specifications.

Incorrect (inconsistent terminology):

## Requirements Document

The **user** can create an account...
The **customer** profile includes...
The **account holder** receives notifications...
A **member** can upgrade their subscription...
The **subscriber** dashboard shows...

// Are these all the same person? Different roles?
// Developers guess; QA interprets differently; bugs ensue

Correct (glossary + consistent usage):

## Glossary

| Term | Definition | NOT to be confused with |
|------|------------|------------------------|
| **User** | Any person interacting with the system | Account (the data record) |
| **Member** | User with an active paid subscription | User (may be free tier) |
| **Account** | The data record representing a user | User (the person) |
| **Workspace** | Shared environment for team collaboration | Account (individual user data) |
| **Admin** | User with elevated permissions in a workspace | Owner (billing responsibility) |
| **Owner** | User responsible for billing | Admin (may not have admin rights) |

---

## Requirements (Using Consistent Terms)

### Account Creation
- A **user** can create an **account** with email/password
- The **account** stores the **user's** profile data

### Subscription Management
- A **user** becomes a **member** by subscribing
- A **member** can access premium features
- Only the **owner** can change billing information

### Workspace Collaboration
- A **member** can create a **workspace**
- The **workspace** creator becomes the **owner**
- The **owner** can grant **admin** rights to other **members**

Glossary best practices:

• Define terms before writing requirements
• Include "not to be confused with" clarifications
• Link to glossary from all spec documents
• Update glossary when new concepts emerge

Reference: Asana - Software Requirements Document

Separate Functional and Non-Functional Requirements

Functional requirements describe what the system does. Non-functional requirements describe how well it does it (performance, security, accessibility). Both are essential; non-functional requirements are often overlooked until too late.

Incorrect (only functional requirements):

## Feature: File Upload

### Requirements
- User can upload files
- Files are stored in the system
- User can download uploaded files
- User can delete files

// No mention of: file size limits, upload speed, security,
// concurrent uploads, storage quotas, virus scanning

Correct (functional + non-functional):

## Feature: File Upload

### Functional Requirements
- User can upload single or multiple files
- User can view list of uploaded files with metadata
- User can download files individually or as ZIP
- User can delete files they own
- Admin can delete any file

### Non-Functional Requirements

#### Performance
- Upload speed: Minimum 1MB/s on broadband
- Maximum file size: 100MB per file
- Concurrent uploads: Up to 5 files simultaneously
- Storage quota: 10GB per user (configurable)

#### Security
- Files scanned for malware before storage
- Direct URL access requires authentication token
- Files encrypted at rest (AES-256)
- Audit log of all file operations

#### Availability
- File service uptime: 99.9%
- Graceful degradation if storage is unavailable
- Upload resume capability for files >10MB

#### Accessibility
- Upload progress announced to screen readers
- Keyboard-accessible file picker
- Error messages include remediation steps

Common NFR categories:

• Performance (speed, throughput, latency)
• Security (authentication, encryption, audit)
• Scalability (users, data volume, growth)
• Availability (uptime, disaster recovery)
• Accessibility (WCAG compliance level)
• Compliance (GDPR, HIPAA, SOC2)

Reference: Document360 - Technical Specification Document

Write Specific and Measurable Requirements

Requirements must be specific enough that two developers would implement them the same way. Vague requirements like "fast" or "user-friendly" lead to interpretation disputes and rework.

Incorrect (vague requirements):

## Requirements

- The page should load fast
- The search should be user-friendly
- The system should handle many users
- Error messages should be helpful
- The UI should be responsive

Correct (specific and measurable):

## Requirements

### Performance
- Page load time: < 2 seconds on 3G connection
- Search results: < 500ms for 95th percentile
- Concurrent users: Support 10,000 simultaneous sessions

### Search UX
- Auto-complete suggestions appear after 2 characters
- Results update as user types (debounced 300ms)
- "No results" state shows 3 suggested alternatives
- Recent searches displayed (last 5, persisted locally)

### Error Handling
- Network errors: Show retry button with "Check your connection"
- Validation errors: Highlight field + inline message
- Server errors: Show error ID for support reference

### Responsive Design
- Breakpoints: 320px (mobile), 768px (tablet), 1024px+ (desktop)
- Touch targets: Minimum 44x44px on mobile
- Navigation: Hamburger menu below 768px

SMART criteria for requirements:

• Specific: Clear, unambiguous language
• Measurable: Quantified where possible
• Achievable: Technically feasible
• Relevant: Tied to user or business need
• Time-bound: Clear delivery expectation

Reference: DesignRush - How To Write Clear Software Requirements

Maintain Requirements Traceability

Track each requirement from origin through implementation to testing. Traceability ensures no requirement is forgotten, enables impact analysis for changes, and proves compliance for audits.

Incorrect (disconnected artifacts):

## Somewhere in Confluence:
REQ-001: User authentication

## Somewhere in Jira:
FEAT-123: Login page
BUG-456: Password reset broken

## Somewhere in GitHub:
PR #789: Add auth middleware

// No way to verify:
// - Is REQ-001 fully implemented?
// - What tests cover REQ-001?
// - What code implements REQ-001?

Correct (traceability matrix):

## Requirements Traceability Matrix

| Req ID | Requirement | User Stories | Code | Tests | Status |
|--------|-------------|--------------|------|-------|--------|
| REQ-001 | User can log in with email/password | US-101, US-102 | auth/login.ts | login.spec.ts | ✓ Done |
| REQ-002 | User can reset password via email | US-103 | auth/reset.ts | reset.spec.ts | ✓ Done |
| REQ-003 | Session expires after 24h inactivity | US-104 | auth/session.ts | session.spec.ts | In Progress |
| REQ-004 | Failed login locks account after 5 attempts | US-105 | - | - | Not Started |

---

## Detailed Trace: REQ-001

**Requirement:** User can log in with email/password

**Business Need:** Security team mandate, Compliance SOC2

**User Stories:**
- US-101: Basic login flow
- US-102: Login error handling

**Implementation:**
- `src/auth/login.ts` - Login logic
- `src/auth/middleware.ts` - Session validation
- `src/components/LoginForm.tsx` - UI component

**Tests:**
- `login.spec.ts` - Unit tests
- `auth.e2e.ts` - E2E login flow
- `security.test.ts` - Penetration test cases

**Verification:** QA sign-off 2024-03-15

Traceability benefits:

• Impact analysis: "If REQ-003 changes, what's affected?"
• Coverage verification: "Are all requirements tested?"
• Audit compliance: "Prove REQ-001 is implemented"
• Progress tracking: "What percentage complete?"

Reference: Aha! - Requirements Management)

Use User Story Format for Feature Requirements

Express requirements as user stories that capture who needs the feature, what they need, and why. This format ensures every requirement is tied to real user value, not arbitrary technical decisions.

Incorrect (technical specification without context):

## Requirements

- Add POST /api/comments endpoint
- Store comments in comments table
- Include timestamp and user_id fields
- Return 201 on success
- Implement pagination

Correct (user story format):

## User Stories

### Story 1: Add Comment
**As a** logged-in user
**I want to** add a comment to a blog post
**So that** I can share my thoughts and engage with the author

**Acceptance Criteria:**
- Comment appears immediately after submission
- Comment shows my name, avatar, and timestamp
- Maximum 2000 characters with character counter
- Empty comments are prevented (submit disabled)

---

### Story 2: View Comments
**As a** blog reader
**I want to** see comments on a post sorted by newest first
**So that** I can read recent discussions

**Acceptance Criteria:**
- Comments load with the post (no extra click)
- Show 10 comments initially, "Load more" for rest
- Display comment count in post header
- Indicate if there are no comments yet

---

### Story 3: Delete Own Comment
**As a** comment author
**I want to** delete my own comment
**So that** I can remove something I regret posting

**Acceptance Criteria:**
- Delete button visible only on my own comments
- Confirmation dialog before deletion
- Comment removed immediately from UI
- Other users' comments are unaffected

User story components:

• Role: Who benefits from this feature
• Action: What they want to do
• Benefit: Why it matters to them
• Acceptance Criteria: How to verify it's done

Reference: Atlassian - User Stories with Examples

Define Explicit In-Scope and Out-of-Scope Boundaries

Explicitly state what the feature will and will not do. Ambiguous boundaries lead to scope creep, where stakeholders assume capabilities that were never planned, causing timeline and budget overruns.

Incorrect (implicit boundaries):

## Feature: User Authentication

### Description
Users should be able to log in to the application securely.

### Requirements
- Login form with email and password
- Session management
- Password reset functionality

Correct (explicit boundaries):

## Feature: User Authentication

### In Scope
- Email/password login form
- Session management with 24-hour expiry
- Password reset via email link
- Failed login attempt limiting (5 attempts)

### Out of Scope (Future Phases)
- Social login (Google, GitHub) - Phase 2
- Two-factor authentication - Phase 2
- Single sign-on (SSO) - Enterprise tier
- Biometric authentication - Mobile app only

### Explicitly Excluded
- Username-based login (email only)
- "Remember me" functionality (security policy)

Benefits:

• Stakeholders know exactly what to expect
• Developers can push back on creep with documented boundaries
• Future phases are acknowledged but deferred

Reference: Asana - What is Scope Creep

Define MVP Separately from Full Vision

Separate the Minimum Viable Product (MVP) from the complete feature vision. This enables faster delivery of core value while deferring nice-to-have functionality to later iterations.

Incorrect (all-or-nothing feature):

## Feature: Notification System

### Requirements
- Email notifications
- Push notifications (iOS, Android, Web)
- SMS notifications
- In-app notification center
- Notification preferences UI
- Digest/batching options
- Template management system
- Analytics and delivery tracking

### Timeline
6 sprints to deliver complete system

Correct (MVP vs full vision):

## Feature: Notification System

### MVP (Sprints 1-2)
**Goal:** Users receive critical notifications via email

- Email notifications for key events only:
  - Account creation
  - Password reset
  - Payment confirmation
- Basic unsubscribe link
- Hardcoded templates (no management UI)

**Success criteria:** 95% delivery rate, <5 min latency

---

### Phase 2 (Sprints 3-4)
- In-app notification center
- Read/unread status tracking
- Notification preferences UI

### Phase 3 (Sprints 5-6)
- Push notifications (mobile + web)
- Digest/batching options

### Future Backlog
- SMS notifications
- Template management system
- Analytics dashboard

---

### Why This Ordering
1. Email covers 80% of notification use cases
2. In-app center reduces email volume
3. Push is additive, not blocking

MVP definition checklist:

• [ ] Delivers core value to users
• [ ] Can be shipped independently
• [ ] Enables learning before over-investing
• [ ] Clear success criteria defined

Reference: Product School - PRD Template

Document Assumptions and Constraints Early

Assumptions are conditions believed to be true that haven't been validated. Constraints are fixed limitations. Documenting both early allows validation before coding starts, preventing costly mid-project discoveries.

Incorrect (undocumented assumptions):

## Feature: Payment Processing

### Requirements
- Accept credit card payments
- Process refunds
- Generate invoices

// Team assumes: existing payment provider, USD only, no taxes
// Reality discovered in sprint 3: new provider needed, multi-currency required
// Result: 3-week delay for integration rework

Correct (explicit assumptions and constraints):

## Feature: Payment Processing

### Assumptions (To Be Validated)
- [ ] Stripe account is already configured and approved
- [ ] All transactions will be in USD initially
- [ ] Sales tax calculation is handled by a separate service
- [ ] PCI compliance is managed at infrastructure level

### Constraints (Fixed Limitations)
- Must use Stripe (contractual obligation)
- Maximum transaction: $10,000 (fraud policy)
- Refund window: 30 days (business policy)
- No cryptocurrency payments (regulatory)

### Dependencies
- Tax calculation service must be deployed first
- Legal team must approve terms of service copy

### Validation Plan
1. Week 1: Confirm Stripe account status with finance
2. Week 1: Verify tax service API availability
3. Week 2: Legal review of payment terms

When to validate assumptions:

• Before sprint planning
• When assumptions affect architecture
• When cost of being wrong is high

Reference: JHK InfoTech - Software Product Specification

Obtain Stakeholder Sign-off on Scope

Require explicit stakeholder approval of scope before development begins. Verbal agreements lead to "I thought it would include X" disputes. Written sign-off creates accountability and shared understanding.

Incorrect (verbal agreement):

## Feature: Reporting Dashboard

Status: Discussed in meeting, ready to start

Meeting notes:
- Bob wants sales reports
- Sarah mentioned export functionality
- Everyone seemed aligned

// 4 weeks later:
// Bob: "Where are the predictive analytics?"
// Sarah: "I assumed PDF export, not just CSV"
// Result: Scope dispute, delayed delivery

Correct (documented sign-off):

## Feature: Reporting Dashboard

### Scope Agreement

**Version:** 1.0
**Date:** 2024-03-15

#### Included in This Release
- Sales report with date filtering
- Revenue breakdown by product category
- CSV export functionality
- Weekly email digest option

#### Explicitly Excluded
- Predictive analytics (Phase 2)
- PDF export (requires design work)
- Real-time updates (polling every 5 min instead)
- Custom report builder

#### Sign-off

| Stakeholder | Role | Date | Signature |
|-------------|------|------|-----------|
| Bob Smith | Sales Director | 2024-03-15 | ✓ Approved |
| Sarah Jones | Product Manager | 2024-03-15 | ✓ Approved |
| Dev Lead | Engineering | 2024-03-15 | ✓ Feasible |

#### Change Process
Any scope changes after sign-off require:
1. Written change request
2. Impact analysis (timeline, cost)
3. Re-approval from all signatories

Sign-off process: 1. Document scope in writing 2. Review with all stakeholders 3. Address questions and concerns 4. Obtain explicit approval (email, signature) 5. Archive approved document

Reference: Adobe - What is Scope Creep

Create Work Breakdown Structure for Complex Features

Break large features into smaller, estimable work items using a Work Breakdown Structure (WBS). Large, monolithic features hide complexity and lead to underestimation. Decomposition reveals true scope.

Incorrect (monolithic feature):

## Feature: User Dashboard

### Description
Build a dashboard showing user analytics and activity.

### Estimate
2 sprints (rough guess)

// Hidden complexity: API design, caching, charts, permissions, mobile
// Actual delivery: 5 sprints

Correct (decomposed work breakdown):

## Feature: User Dashboard

### Work Breakdown Structure

1. **Data Layer** (Sprint 1)
   - 1.1 Define dashboard data models (2 pts)
   - 1.2 Create aggregation queries (3 pts)
   - 1.3 Implement caching layer (3 pts)
   - 1.4 Build REST API endpoints (5 pts)

2. **Visualization Components** (Sprint 2)
   - 2.1 Activity timeline component (3 pts)
   - 2.2 Analytics charts (bar, line, pie) (5 pts)
   - 2.3 Summary cards with KPIs (2 pts)
   - 2.4 Date range picker (2 pts)

3. **Dashboard Assembly** (Sprint 3)
   - 3.1 Layout and grid system (3 pts)
   - 3.2 Widget drag-and-drop (5 pts)
   - 3.3 Responsive design (3 pts)
   - 3.4 Loading states and skeletons (2 pts)

4. **Integration & Polish** (Sprint 4)
   - 4.1 Permission-based widget visibility (3 pts)
   - 4.2 Export to PDF/CSV (3 pts)
   - 4.3 Performance optimization (2 pts)
   - 4.4 E2E testing (3 pts)

### Total: 49 story points across 4 sprints

WBS principles:

• Each item should be independently estimable
• Aim for items under 8 story points
• Reveal dependencies between items
• Enable parallel work streams

Reference: Planio - 7 Steps to Deal With Scope Creep

Establish Stakeholder Communication Cadence

Define how and when stakeholders will receive updates. Ad-hoc communication leads to some stakeholders being surprised while others are over-informed. A defined cadence sets expectations.

Incorrect (ad-hoc updates):

## Communication Approach

"We'll update stakeholders when there's something to share"

// Reality:
// Week 1: Lots of updates (excitement)
// Week 2-4: Radio silence (heads down)
// Week 5: Stakeholder asks "What's happening?"
// Week 6: Panic update before demo
// Result: Stakeholders feel out of the loop, trust erodes

Correct (defined communication plan):

## Stakeholder Communication Plan

### Update Channels

| Channel | Audience | Frequency | Content |
|---------|----------|-----------|---------|
| Slack #proj-payments | All stakeholders | Daily | Quick wins, blockers |
| Weekly email digest | Exec sponsors | Weekly | Progress %, risks, decisions needed |
| Sprint demo | Technical + Product | Bi-weekly | Working software |
| Steering committee | Exec + leads | Monthly | Milestones, budget, timeline |

### Communication Templates

**Daily Slack Update (async)**

🟢 Yesterday: Completed payment form validation 🔵 Today: Starting Stripe integration 🔴 Blocked: Waiting on API credentials from Finance

**Weekly Email Digest**

Subject: [Payments] Week 3 Update - On Track

Progress: 45% complete

• ✅ Completed: Payment form, validation, test suite
• 🚧 In progress: Stripe integration
• ⏳ Upcoming: Error handling, receipts

Risks

• API credentials delayed (Medium risk, mitigation in place)

Decisions Needed

• Approve receipt email template by Friday

Next Demo

Thursday 2pm - Payment flow end-to-end

### Escalation Triggers
Stakeholders will be notified immediately if:
- Timeline slips > 1 week
- Budget exceeds 10%
- Critical blocker emerges
- Scope change requested

Reference: APU - Scope Creep Project Management Tips

Resolve Stakeholder Conflicts Explicitly

When stakeholders disagree on requirements, resolve conflicts explicitly with documented decisions. Unresolved conflicts lead to passive scope creep as each party pushes their agenda during implementation.

Incorrect (avoiding conflict):

## Requirements Meeting Notes

Sales wants: Bulk discount feature
Finance wants: No bulk discounts (margin concerns)

Resolution: "We'll figure it out later"

// What actually happens:
// Sales tells developers to add bulk discounts
// Finance tells developers discounts need approval
// Developers build both, neither fully works
// Feature launches with confused logic

Correct (explicit conflict resolution):

## Conflict Resolution: Bulk Discounts

### Conflicting Positions

**Sales (represented by Sarah):**
- Wants: Automatic bulk discounts (10+ units = 10% off)
- Rationale: Competitive pressure, customer requests
- Impact if not included: Lost deals worth ~$50K/quarter

**Finance (represented by Frank):**
- Wants: No automatic discounts without approval
- Rationale: Margin protection, pricing integrity
- Impact if not included: 15% margin erosion risk

### Options Considered

| Option | Sales Impact | Finance Impact | Effort |
|--------|-------------|----------------|--------|
| A: Auto discounts | ✓ Full | ✗ High risk | Low |
| B: No discounts | ✗ Lost deals | ✓ Protected | None |
| C: Tiered approval | Partial | Partial | Medium |

### Decision

**Selected: Option C - Tiered Approval System**
- < 10%: Sales can approve directly
- 10-20%: Manager approval required
- > 20%: Finance approval required

**Decision maker:** VP of Product (tie-breaker)
**Date:** 2024-03-15
**Documented in:** PRD v2.1

### Commitment
Both parties agree to support this decision and not re-litigate during development.

| Stakeholder | Acceptance |
|-------------|------------|
| Sarah (Sales) | ✓ Accepted |
| Frank (Finance) | ✓ Accepted |

Conflict resolution escalation: 1. Direct discussion between parties 2. Facilitated meeting with PM 3. Escalation to shared manager 4. Executive tie-breaker (last resort)

Reference: Project Manager Academy - Managing Scope Creep

Gather Stakeholder Feedback Early and Often

Don't wait until the end to show stakeholders the finished product. Share work-in-progress early to catch misalignment before significant investment. Late feedback is expensive feedback.

Incorrect (big reveal at the end):

## Project Timeline

Week 1-2: Requirements gathering
Week 3-4: Design (internal only)
Week 5-8: Development (internal only)
Week 9: Stakeholder demo

// Stakeholder feedback at week 9:
// "This isn't what I expected at all"
// "Can we change the entire flow?"
// Result: 4 more weeks of rework

Correct (continuous feedback loops):

## Project Timeline with Checkpoints

### Week 1: Problem Alignment
- [ ] Share problem statement with all stakeholders
- [ ] Confirm we're solving the right problem
- [ ] Document any disagreements

### Week 2: Requirements Review
- [ ] Share draft requirements document
- [ ] 48-hour feedback window
- [ ] Resolution meeting for conflicts
- **Checkpoint: Requirements approved**

### Week 3: Design Review
- [ ] Share wireframes and user flows
- [ ] Walkthrough with key stakeholders
- [ ] Incorporate feedback before high-fidelity
- **Checkpoint: Design direction approved**

### Week 4: Design Refinement
- [ ] Share high-fidelity mockups
- [ ] Prototype key interactions
- [ ] Final design sign-off
- **Checkpoint: Design approved for development**

### Week 6: Mid-Development Check
- [ ] Demo working prototype (even if incomplete)
- [ ] Validate core assumptions
- [ ] Surface integration concerns early
- **Checkpoint: No major direction changes**

### Week 8: Pre-Launch Review
- [ ] Feature complete demo
- [ ] Stakeholder acceptance testing
- [ ] Final go/no-go decision
- **Checkpoint: Launch approved**

Feedback cadence by project size:

• Small (< 2 weeks): Beginning and end
• Medium (2-6 weeks): Weekly checkpoints
• Large (> 6 weeks): Bi-weekly checkpoints + async updates

Reference: Lean Wisdom - Manage Project Scope Creep

Identify All Stakeholders Early

Map all stakeholders before requirements gathering begins. Overlooked stakeholders surface late with new requirements, causing rework. Include those who approve, build, use, support, and are affected by the feature.

Incorrect (developer-centric stakeholder list):

## Stakeholders

- Product Manager
- Development Team
- QA

// Missing: Legal, Security, Support, Marketing, Finance
// Week 6: Legal blocks launch for compliance review
// Week 7: Support needs training materials
// Result: 3-week delay

Correct (comprehensive stakeholder map):

## Stakeholder Map - Payment Feature

### Decision Makers (Approve scope and budget)
| Role | Name | Interest | Engagement |
|------|------|----------|------------|
| Product Director | Alice Chen | Feature success | Final approval |
| Engineering Manager | Bob Smith | Technical feasibility | Architecture approval |

### Builders (Design and implement)
| Role | Name | Interest | Engagement |
|------|------|----------|------------|
| Product Manager | Carol Davis | User value | Requirements, prioritization |
| Tech Lead | Dan Wilson | Code quality | Technical design |
| UX Designer | Emma Brown | User experience | Design specs |
| QA Lead | Frank Lee | Quality | Test planning |

### Supporters (Enable and maintain)
| Role | Name | Interest | Engagement |
|------|------|----------|------------|
| DevOps | Grace Kim | Reliability | Infrastructure review |
| Support Lead | Henry Park | Supportability | Training, documentation |

### Influencers (Affect or are affected)
| Role | Name | Interest | Engagement |
|------|------|----------|------------|
| Legal | Irene Wu | Compliance | Policy review |
| Security | Jack Torres | Data protection | Security review |
| Finance | Karen Adams | Revenue impact | Pricing approval |
| Marketing | Leo Martinez | Positioning | Launch messaging |

### Users (End consumers)
- Free tier users: Basic payment flow
- Premium users: Advanced payment options
- Enterprise admins: Bulk payment management

RACI for key decisions:

• Responsible: Carol (PM)
• Accountable: Alice (Director)
• Consulted: Legal, Security, Finance
• Informed: Support, Marketing

Reference: BA Times - How to Mitigate Scope Creep

Align on Success Metrics Before Building

Define how success will be measured before development begins. Without agreed metrics, stakeholders will evaluate the feature by different criteria, leading to "success" debates after launch.

Incorrect (undefined success):

## Feature: Search Improvements

Goal: Make search better

// Post-launch:
// PM: "Search is better—users can find things faster"
// Sales: "But conversion didn't improve"
// Exec: "Was this worth the investment?"
// Everyone has different definition of "better"

Correct (defined success metrics):

## Feature: Search Improvements

### Success Metrics (Agreed by all stakeholders)

**Primary Metrics (Must achieve)**
| Metric | Baseline | Target | Measurement |
|--------|----------|--------|-------------|
| Search-to-click rate | 35% | 50% | Analytics event |
| Zero-result rate | 15% | < 5% | Search logs |
| Search latency p95 | 800ms | < 300ms | APM dashboard |

**Secondary Metrics (Monitor)**
| Metric | Baseline | Watch For |
|--------|----------|-----------|
| Conversion rate | 2.5% | Should not decrease |
| Page load time | 1.2s | Should not increase > 20% |
| Support tickets (search-related) | 50/week | Should decrease |

**Timeline for Measurement**
- Week 1-2 post-launch: Monitor for regressions
- Week 4: Initial success assessment
- Week 8: Full success evaluation

### Success Criteria Agreement

| Stakeholder | Primary Metric Focus | Sign-off |
|-------------|---------------------|----------|
| PM (Carol) | Search-to-click rate | ✓ |
| Eng (Dan) | Latency p95 | ✓ |
| Sales (Sarah) | Conversion rate | ✓ |
| Exec (Alice) | All metrics balanced | ✓ |

### Definition of Success
Feature is successful if:
- ALL primary metrics hit target
- NO secondary metric regresses significantly
- Measured 8 weeks post-launch with statistical significance

Metric selection criteria:

• Measurable with existing tools
• Attributable to this feature
• Meaningful to business outcomes
• Agreed by all stakeholders before development

Reference: Product School - Acceptance Criteria in Practice

Define API Contracts Before Implementation

Specify API contracts (request/response schemas, error codes, versioning) before coding begins. Vague APIs lead to frontend-backend mismatches, requiring costly iterations.

Incorrect (vague API description):

## API

The search endpoint accepts a query and returns results.

// Frontend developer asks:
// - What's the URL?
// - GET or POST?
// - What parameters?
// - What does the response look like?
// - What errors can occur?
// Result: Frontend builds assumptions, backend builds differently

Correct (complete API contract):

## API Contract: Product Search

### Endpoint

GET /api/v2/products/search

### Authentication
- Required: Yes
- Type: Bearer token (JWT)
- Scopes: `products:read`

### Request

**Query Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| q | string | Yes | - | Search query (2-100 chars) |
| category | string | No | all | Category filter |
| min_price | number | No | 0 | Minimum price in cents |
| max_price | number | No | null | Maximum price in cents |
| sort | enum | No | relevance | `relevance`, `price_asc`, `price_desc`, `newest` |
| page | integer | No | 1 | Page number (1-1000) |
| per_page | integer | No | 20 | Results per page (1-100) |

**Example Request:**

curl -X GET "https://api.example.com/api/v2/products/search?q=laptop&category=electronics&sort=price_asc&page=1&per_page=20" \ -H "Authorization: Bearer eyJhbGc..."

### Response

**Success (200 OK):**

{ "data": { "products": [ { "id": "prod_abc123", "name": "MacBook Pro 14\"", "description": "Apple M3 Pro chip...", "price_cents": 199900, "currency": "USD", "category": "electronics", "image_url": "https://cdn.example.com/products/abc123.jpg", "in_stock": true, "rating": 4.8, "review_count": 1247 } ], "pagination": { "current_page": 1, "per_page": 20, "total_pages": 15, "total_count": 287 }, "facets": { "categories": [{"name": "electronics", "count": 150}], "price_ranges": [{"min": 0, "max": 10000, "count": 45}] } }, "meta": { "request_id": "req_xyz789", "took_ms": 45 } }

### Error Responses

| Status | Code | Description | Resolution |
|--------|------|-------------|------------|
| 400 | INVALID_QUERY | Query too short/long | Provide 2-100 char query |
| 400 | INVALID_PARAMETER | Parameter validation failed | Check parameter constraints |
| 401 | UNAUTHORIZED | Missing/invalid token | Refresh authentication |
| 429 | RATE_LIMITED | Too many requests | Wait and retry with backoff |
| 500 | INTERNAL_ERROR | Server error | Retry or contact support |

**Error Response Format:**

{ "error": { "code": "INVALID_QUERY", "message": "Search query must be between 2 and 100 characters", "details": {"provided_length": 1, "min_length": 2} }, "meta": {"request_id": "req_xyz789"} }

### Rate Limits
- Authenticated: 100 requests/minute
- Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`

### Versioning
- Current: v2
- Deprecation: v1 sunset 2025-06-01
- Breaking changes require major version bump

API contract must include:

• Endpoint URL and method
• Authentication requirements
• All parameters with types and constraints
• Complete response schemas
• All error codes with resolution steps

Reference: Microsoft API Guidelines