Skip to main content

PRD/TDD Feature Development Workflow

Overview​

This playbook documents the Product Requirements Document (PRD) to Technical Design Document (TDD) workflow for planning and documenting new features. This approach enables iterative refinement, clear separation of concerns, and comprehensive documentation before implementation begins.

When to Use This Workflow​

✅ Use PRD/TDD Workflow For:​

  • Complex Features requiring multiple components or services
  • Cross-Cutting Changes affecting frontend, backend, and infrastructure
  • New APIs or Integrations (e.g., Google Maps, external services)
  • Features with Business Impact requiring stakeholder buy-in
  • Multi-Phase Projects with incremental delivery
  • Features Requiring Cost Analysis (API costs, infrastructure)
  • Security-Sensitive Features needing thorough review

❌ Skip This Workflow For:​

  • Simple bug fixes
  • Minor UI tweaks
  • Documentation-only updates
  • Urgent hotfixes
  • Single-file changes with no architectural impact

The Five-Phase Workflow​

Phase 1: Initial Proposal & Context Gathering​

Goal: Define the feature at a high level and gather context from existing work.

Steps:

  1. Start with a Proposal: Write a brief description of what you want to build

    Example: "I want to add Google Maps integration for project addresses:
    1. Address autocomplete when typing
    2. Map widget showing project location"

  2. Reference Prior Work: Build on existing context

    • Review related issues (e.g., Issue #227 - Project Metadata Management)
    • Review related documentation (e.g., existing address fields)
    • Identify dependencies and integration points

  3. Ask Clarifying Questions: Refine the scope interactively

    • "Should we keep Chrome autocomplete too?"
    • "Where should the map widget appear?"
    • "What about future enhancements like 3D views?"

Deliverable: Shared understanding of the feature scope

Example from Issue #236:

Initial proposal: "Add Google Maps integration - autocomplete and map widget"
↓
Context: Built on Issue #227 (Project Metadata with address fields)
↓
Refinement: Keep Chrome autocomplete, add 3D flyover to future phases

Phase 2: Create Product Requirements Document (PRD)​

Goal: Document WHAT to build and WHY it matters, from a product perspective.

File Location: docs/04-prd/<feature-name>.md

PRD Structure:

# PRD: Feature Name

## Overview
- Brief description
- Reference to parent/related issues

## Problem Statement
- Current state (what exists)
- User pain points (what's missing)
- User impact (why it matters)

## Goals
- Primary goals
- Secondary goals
- Non-goals (what we're explicitly NOT doing)

## User Stories
- Story 1: As a [role], I want [action], so that [benefit]
  - Acceptance criteria with checkboxes
- Story 2: ...
- Story 3: ...

## Technical Design (High-Level)
- APIs or services required
- Proto schema changes (interface contracts)
- Component architecture (names and responsibilities only)
- Environment configuration (structure, not code)
- Cost analysis and pricing
- Security and privacy considerations

## Testing Strategy (Scope Only)
- What will be tested
- Testing categories
- Manual testing checklist

## Success Metrics
- User engagement metrics
- System performance targets
- Business KPIs

## Future Enhancements
- Phase 2, 3, 4 roadmap
- Prioritized list of enhancements

## References
- Links to related PRDs, TDDs, issues

What to Include in PRD:

  • ✅ Proto schema changes (interface contracts)
  • ✅ Component names and responsibilities
  • ✅ API selection and pricing
  • ✅ GCP setup overview
  • ✅ Security approach
  • ✅ Success metrics

What to Exclude from PRD:

  • ❌ Complete implementation code
  • ❌ Detailed TypeScript/Java classes
  • ❌ HTML templates and CSS
  • ❌ Line-by-line code explanations
  • ❌ Detailed test code

Key Principle: PRD answers "WHAT" and "WHY", not "HOW"

Example: Issue #236 - Google Maps Integration

  • PRD: 494 lines (product-focused)
  • Removed ~335 lines of code during deduplication
  • Kept proto schema, pricing, security, architecture

Phase 3: Create Technical Design Document (TDD)​

Goal: Document HOW to implement the feature, with complete code examples.

File Location: docs/05-tdd/<feature-name>.md

TDD Structure:

# TDD: Feature Name

> Related PRD: [Link to PRD](../04-prd/feature-name.md)

## Overview
- Technical summary
- Architecture diagrams

## Proto Message Definitions
- Complete proto schemas with all fields
- Message relationships
- Enum definitions with annotations

## Component Architecture
- Detailed component structure
- Data flow diagrams
- Service dependencies

## Implementation Details

### Backend Implementation
- Complete Java class code
- Service layer implementation
- Database/storage access patterns
- Error handling

### Frontend Implementation
- Complete TypeScript/Angular code
- Component templates (HTML)
- Styles (SCSS)
- Service integration

### Infrastructure
- Environment configuration (complete files)
- GCP resource setup (step-by-step gcloud commands)
- Secret management
- Deployment scripts

## Testing Strategy
- Unit test code examples
- Integration test scripts
- E2E test specifications
- Mock strategies

## Performance Optimizations
- Caching strategies
- Lazy loading
- API call optimization

## Security Implementation
- Input validation code
- API key restrictions (exact commands)
- Error handling patterns

## Deployment Guide
- Step-by-step deployment instructions
- Verification commands
- Troubleshooting section
- Rollback procedures

## References
- Links to APIs, libraries, related docs

What to Include in TDD:

  • ✅ Complete implementation code (TypeScript, Java, HTML, CSS)
  • ✅ Step-by-step gcloud commands
  • ✅ Full component implementations
  • ✅ Unit and integration test code
  • ✅ Deployment procedures
  • ✅ Troubleshooting guides

Key Principle: TDD answers "HOW" with executable detail

Example: Issue #236 - Google Maps Integration

  • TDD: 1,934 lines (implementation-complete)
  • 14-step deployment guide
  • Complete code for 3 components
  • Test examples, troubleshooting, performance tips

Phase 4: Create Automation Scripts​

Goal: Automate repetitive deployment and setup tasks.

File Location: cli/sdlc/<category>/<script-name>.sh

Script Structure:

#!/bin/bash

################################################################################
# Script Purpose
#
# Description of what this script does
#
# Usage:
#   cli/sdlc/category/script-name.sh <args>
#
# Examples:
#   cli/sdlc/category/script-name.sh demo
#
# Prerequisites:
#   - List prerequisites
#
# What it does:
#   1. Step 1
#   2. Step 2
#   ...
################################################################################

set -e  # Exit on any error

# Color codes for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color

# Helper functions
log_info() { echo -e "${BLUE}ℹ️  $1${NC}"; }
log_success() { echo -e "${GREEN}✅ $1${NC}"; }
log_warning() { echo -e "${YELLOW}⚠️  $1${NC}"; }
log_error() { echo -e "${RED}❌ $1${NC}"; }
log_section() {
    echo ""
    echo -e "${BLUE}================================================${NC}"
    echo -e "${BLUE}$1${NC}"
    echo -e "${BLUE}================================================${NC}"
    echo ""
}

# Validate arguments
# Find workspace root
# Load environment variables
# Execute automated steps
# Display manual steps with URLs
# Provide verification commands
# Show summary and next steps

Script Best Practices:

  • ✅ Color-coded output for readability
  • ✅ Validation and error handling
  • ✅ Clear section headers
  • ✅ Verification commands after each step
  • ✅ Summary with next steps
  • ✅ Executable permissions (chmod +x)

Document Scripts: Add to docs/03-devops/env-provisioning/02-new-env-scripts.md

Example: Issue #236

  • Created: setup-google-maps-api.sh (442 lines)
  • Automates: API enablement, key creation, restrictions, Secret Manager
  • Pattern: Matches existing provisioning scripts

Phase 5: Create GitHub Issue​

Goal: Create trackable work item with all context and checklists.

File Location: docs/04-prd/<feature-name>-github-issue.md (template)

Issue Structure:

## Feature Title

### Overview
- Brief description
- Parent issue reference

### Problem Statement
- Current state
- User pain points

### Goals
- Numbered list of objectives

### User Stories
- Story 1 with acceptance criteria checkboxes
- Story 2 with acceptance criteria checkboxes
- ...

### Technical Implementation
- New files to create
- Files to modify
- Proto schema changes
- APIs/services required
- Cost estimates

### Setup Requirements
- GCP configuration
- API keys
- Environment variables

### Testing Plan
- Unit tests
- Integration tests
- Manual testing checklist

### Success Metrics
- Engagement, performance, cost metrics

### Security Considerations
- Key security requirements

### Future Enhancements
- Phase 2, 3, 4 roadmap

### Documentation
- List all docs created (with checkboxes)

### Deployment Checklist
- Automated setup steps
- Manual configuration steps
- Testing & validation steps

### Implementation Tasks
- Phase 1: Core Infrastructure (checkboxes)
- Phase 2: Feature A (checkboxes)
- Phase 3: Feature B (checkboxes)
- ...

### Dependencies
- Parent issues
- External dependencies

### Estimated Effort
- Development days
- Testing days
- Total

### Priority
- High/Medium/Low with justification

### Labels
- List of GitHub labels

Create Issue:

# Use GitHub MCP or web interface
# Copy content from -github-issue.md file
# Apply appropriate labels

Example: Issue #236

Compounding Effect: Building on Prior Context​

A key advantage of this workflow is the compounding effect - each new feature builds on and references prior work, creating a web of interconnected context.

Anchoring on Prior Issues​

Example from Issue #236:

Issue #227: Project Metadata Management (Phase 1)
  ├── Implemented: Editable project name, description, address
  ├── Created: ProjectAddress proto message
  └── Delivered: Project settings UI with inline editing
       ↓
Issue #236: Google Maps Integration (Phase 1.5)
  ├── Builds on: Existing address fields from #227
  ├── Enhances: Address entry with autocomplete
  ├── Adds: Visual confirmation with map widget
  └── References: Same ProjectAddress proto (extended)

Documentation Layering​

Layer 1: Core Infrastructure

  • Issue #227: Basic metadata editing
  • Docs: PRD and TDD for metadata management

Layer 2: Enhancements (Build on Layer 1)

  • Issue #236: Google Maps integration
  • Docs: PRD and TDD reference Issue #227 extensively
  • Proto: Extends existing ProjectAddress message

Layer 3: Future Enhancements (Build on Layer 2)

  • Future: 3D flyover, Street View, jurisdiction lookup
  • Docs: Already captured in Phase 2/3 of Issue #236
  • Proto: No changes needed, already extensible

Benefits of Compounding Context​

  1. Reduced Scope Creep: Each phase has clear boundaries
  2. Faster Planning: Can reference previous decisions
  3. Consistent Patterns: New features follow established patterns
  4. Easier Review: Reviewers can reference prior discussions
  5. Knowledge Preservation: Context doesn't get lost
  6. Incremental Value: Each phase delivers working features

Cross-Referencing Best Practices​

In PRDs/TDDs:

> **📋 Parent Issue**: [Issue #227 - Project Metadata Management](link)

## Related Issues
- **Issue #167**: File Structure Reorganization (complementary)
- **Issue #227**: Project Metadata Management (parent)

## References
- [Developer Playbook](../02-developer-playbooks/02-playbook.md)
- [Project Metadata PRD](./project-metadata-management.md)

In Code Comments:

/**
 * Google Maps integration for project address.
 * 
 * Related:
 * - Issue #227: Project Metadata Management (base functionality)
 * - Issue #236: Google Maps Integration (this feature)
 * 
 * See: docs/05-tdd/google-maps-integration.md
 */
export class GoogleMapsService { ... }

Clear Separation: PRD vs. TDD​

PRD Audience: Product Managers, Stakeholders, Business​

PRD Answers:

  • WHAT are we building?
  • WHY does it matter?
  • WHO is it for?
  • WHEN will we ship it?
  • HOW MUCH will it cost?

PRD Focus:

  • User stories and acceptance criteria
  • Business value and metrics
  • Cost analysis and ROI
  • High-level technical approach
  • Security and compliance requirements

PRD Size: Typically 300-600 lines

TDD Audience: Developers, DevOps, QA​

TDD Answers:

  • HOW do we build it?
  • WHERE does the code go?
  • WHAT are the exact steps?
  • HOW do we test it?
  • HOW do we deploy it?

TDD Focus:

  • Complete implementation code
  • Step-by-step deployment instructions
  • Testing strategies with code examples
  • Performance optimizations
  • Troubleshooting guides

TDD Size: Typically 1,000-2,500 lines

Deduplication Checklist​

After creating both PRD and TDD, remove duplicate code from PRD:

Remove from PRD:

  • ❌ Complete TypeScript/Java class implementations
  • ❌ HTML templates and SCSS styles
  • ❌ Detailed method implementations
  • ❌ Line-by-line code walkthroughs
  • ❌ Complete test code

Keep in PRD:

  • ✅ Proto message definitions (interface contracts)
  • ✅ Component names and responsibilities
  • ✅ Architecture diagrams
  • ✅ API selection and cost analysis
  • ✅ Environment variable structure
  • ✅ High-level testing scope

Add Clear References:

> **📘 Implementation Details**: For complete code examples, see the 
> [Technical Design Document](../05-tdd/feature-name.md).

Example Workflow: Issue #236 (Google Maps Integration)​

Step-by-Step Execution​

1. Initial Proposal (Conversational)​

User: "I want to add Google Maps integration:
1. Address autocomplete when typing
2. Map widget showing project location
Can you propose a PRD/TDD?"

2. Context Gathering​

  • Reviewed Issue #227 (Project Metadata Management)
  • Identified existing ProjectAddress message
  • Checked current UI component structure
  • Understood existing address editing flow

3. Create PRD (Product Focus)​

File: docs/04-prd/google-maps-integration.md

Content:

  • Problem statement: No smart suggestions, no visual confirmation
  • User stories: Autocomplete, Map Widget, Geocoding
  • Proto schema: Extended ProjectAddress with lat/lng
  • Cost analysis: ~$40/month (covered by free tier)
  • Security: API key restrictions, Secret Manager
  • Future phases: 3D flyover, Street View

Size: 494 lines (product-focused)

4. Create TDD (Implementation Focus)​

File: docs/05-tdd/google-maps-integration.md

Content:

  • Complete GoogleMapsService TypeScript code
  • Complete ProjectLocationMapComponent implementation
  • Enhanced ProjectSettingsComponent with autocomplete
  • HTML templates and SCSS styles
  • 14-step deployment guide with gcloud commands
  • Unit and integration test examples
  • Troubleshooting section

Size: 1,934 lines (implementation-complete)

5. Deduplication Pass​

  • Removed ~335 lines of code from PRD
  • Added references to TDD for implementation details
  • PRD reduced from 946 → 494 lines (48% reduction)

6. Create Automation Script​

File: cli/sdlc/new-environment-provisioning/setup-google-maps-api.sh

Features:

  • Automated API enablement
  • Restricted API key creation
  • Secret Manager storage
  • Service account permissions
  • Verification testing

Size: 442 lines (executable)

7. Update Provisioning Guides​

  • Added Step 5.5 to docs/03-devops/env-provisioning/01-imperative-provisioning.md
  • Documented script in docs/03-devops/env-provisioning/02-new-env-scripts.md

8. Create GitHub Issue​

File: docs/04-prd/google-maps-integration-github-issue.md (template)

Issue Created: #236 with:

  • Complete user stories with checkboxes
  • Implementation tasks breakdown
  • Deployment checklist
  • Testing plan
  • Labels: enhancement, frontend, google-maps, phase-1.5

Timeline​

  • Phase 1-3: 30 minutes (proposal → PRD → TDD)
  • Phase 4: 15 minutes (automation script)
  • Phase 5: 10 minutes (provisioning docs + GitHub issue)
  • Total: ~1 hour for complete planning

Iterative Refinement Pattern​

The workflow supports iterative refinement through conversation:

1. Initial Proposal
   ↓ (clarifying questions)
2. Refined Scope
   ↓ (create draft PRD)
3. PRD v1
   ↓ (feedback: "add 3D flyover to future phases")
4. PRD v2
   ↓ (create TDD)
5. TDD v1
   ↓ (feedback: "too much code in PRD, deduplicate")
6. PRD v3 (deduplicated) + TDD v2 (enhanced)
   ↓ (feedback: "add deployment automation")
7. Final: PRD + TDD + Scripts + Issue

Benefits:

  • Catch scope issues early (before coding)
  • Refine requirements through discussion
  • Build consensus before implementation
  • Adjust based on feedback quickly

Integration with GitHub Issues​

From PRD/TDD to GitHub Issue​

Workflow:

  1. Create PRD and TDD documents
  2. Create <feature>-github-issue.md template file
  3. Copy content into new GitHub issue
  4. Apply labels and milestone
  5. Link PRD/TDD in issue description
  6. Use issue for progress tracking

Issue as Single Source of Truth for Progress:

  • GitHub issue tracks implementation progress (checkboxes)
  • PRD/TDD remain stable reference documentation
  • Code comments reference both issue # and doc links

Linking Strategy​

In GitHub Issue:

### Documentation
- [PRD](./docs/04-prd/feature-name.md)
- [TDD](./docs/05-tdd/feature-name.md)

In PRD/TDD:

> **📋 Implementation Issue**: [Issue #236 - Feature Name](github-url)

In Code:

/**
 * Feature implementation.
 * 
 * Issue: #236
 * Docs: docs/05-tdd/google-maps-integration.md
 */

File Naming Conventions​

Documentation Files​

PRDs: docs/04-prd/<feature-name>.md

  • Use kebab-case
  • Be descriptive but concise
  • Match TDD name
  • Examples:
    • google-maps-integration.md
    • project-metadata-management.md
    • file-structure-reorganization.md

TDDs: docs/05-tdd/<feature-name>.md

  • Must match PRD name exactly
  • Same file name in different folders
  • Examples:
    • google-maps-integration.md
    • project-metadata-management.md

GitHub Issue Templates: docs/04-prd/<feature-name>-github-issue.md

  • PRD name + -github-issue suffix
  • Temporary file for issue creation reference
  • Can be deleted after issue is created (or kept for templates)

Automation Scripts​

Location: cli/sdlc/<category>/<script-name>.sh

Categories:

  • new-environment-provisioning/ - Environment setup scripts
  • utils/ - Utility scripts
  • cloud-run-job/ - Cloud Run Job deployment
  • testing/ - Testing utilities

Naming: Descriptive, kebab-case, .sh extension

  • setup-google-maps-api.sh
  • copy-project-between-envs.sh
  • update-placeholder-vars.sh

Directory Structure​

docs/
├── 04-prd/                          # Product Requirements Documents
│   ├── feature-name.md              # Main PRD
│   └── feature-name-github-issue.md # Issue template (optional)
│
├── 05-tdd/                          # Technical Design Documents
│   └── feature-name.md              # Implementation details
│
├── 03-devops/
│   └── env-provisioning/
│       ├── 01-imperative-provisioning.md           # Main provisioning guide
│       └── 02-new-env-scripts.md    # Script documentation
│
└── 02-developer-playbooks/
    └── 07-prd-tdd-workflow.md       # This document

cli/sdlc/
├── new-environment-provisioning/
│   └── script-name.sh               # Automation scripts
├── utils/
│   └── utility-script.sh
└── cloud-run-job/
    └── deploy.sh

Template Files​

Quick Start Templates​

To start a new feature, copy these templates:

# Copy PRD template
cp docs/04-prd/_template.md docs/04-prd/my-feature.md

# Copy TDD template  
cp docs/05-tdd/_template.md docs/05-tdd/my-feature.md

# Copy script template
cp cli/sdlc/_template.sh cli/sdlc/category/my-script.sh
chmod +x cli/sdlc/category/my-script.sh

Note: Templates should be created to standardize this workflow.

Benefits of This Workflow​

1. Clear Separation of Concerns​

  • Product managers read PRDs without code clutter
  • Developers reference TDDs for implementation
  • DevOps use automation scripts for deployment

2. Early Validation​

  • Catch scope issues before coding
  • Get stakeholder buy-in early
  • Identify technical risks upfront

3. Better Collaboration​

  • PRDs facilitate product discussions
  • TDDs enable code reviews before implementation
  • Issues track progress transparently

4. Knowledge Preservation​

  • Documentation survives team changes
  • Future developers understand decisions
  • Context doesn't get lost in Slack/email

5. Faster Implementation​

  • Developers have clear requirements
  • No mid-implementation scope changes
  • Automation scripts reduce manual work

6. Compounding Value​

  • Each feature builds on previous work
  • Patterns emerge and get reused
  • Documentation network grows richer

Anti-Patterns to Avoid​

❌ Don't:​

  1. Write Code Before PRD/TDD: Leads to scope creep and rework
  2. Duplicate Code in PRD and TDD: Causes maintenance burden
  3. Skip Automation Scripts: Manual steps get forgotten
  4. Create PRD Without User Stories: Loses user perspective
  5. Create TDD Without Code Examples: Too abstract to implement
  6. Forget to Update Provisioning Guides: Scripts become orphaned
  7. Create Issues Without Documentation Links: Context gets lost

✅ Do:​

  1. Start with Proposal: Refine scope through discussion
  2. Reference Prior Work: Build on existing context
  3. Deduplicate After Writing: Keep PRD product-focused
  4. Automate Repetitive Tasks: Scripts for deployment
  5. Link Everything: PRD ↔ TDD ↔ Issue ↔ Code
  6. Include Future Phases: Capture roadmap early
  7. Test Instructions: Verify commands work

Success Criteria​

You've successfully completed the PRD/TDD workflow when:

  • ✅ PRD clearly explains WHAT and WHY (no verbose code)
  • ✅ TDD provides complete HOW (executable detail)
  • ✅ Automation script handles 80%+ of deployment
  • ✅ GitHub issue tracks all tasks with checkboxes
  • ✅ Provisioning guides updated with new steps
  • ✅ All docs cross-reference each other
  • ✅ Future phases documented for roadmap visibility
  • ✅ Cost, security, and metrics clearly defined

Real-World Example: Issue #236 Metrics​

Planning Time: ~1 hour for complete documentation Documents Created: 6 files (3,200+ lines) Code Removed (Deduplication): 335 lines from PRD Automation Coverage: 90% of API setup automated Dependencies Identified: 1 parent issue (#227) Future Phases Captured: 3 phases with 13 enhancements Cost Analysis: $0/month (within free tier) Security Measures: 6 key restrictions documented

Result: Feature is implementation-ready with:

  • Clear requirements (PRD)
  • Complete technical guide (TDD)
  • Automated deployment (script)
  • Trackable work item (Issue #236)

References​

Examples in This Codebase​

Completed Examples: