PRD to Engineering Spec
Overview
Transform product requirements into engineering specifications so complete that developers can implement the entire system step-by-step without ambiguity , and the resulting system can be replicated or migrated without information loss .
Skill Workflow Context
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ prd-writing- │────►│ prd-to- │ │ reverse- │
│ guide │ │ engineering- │ │ engineering- │
│ Write PRD │ │ spec │ │ spec │
│ │ │ [THIS SKILL] │ │ Code→Spec │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼ For AI Agent products:
┌─────────────────┐
│ ai-agent-prd │────► This skill handles Agent PRD conversion too
└─────────────────┘ Input: Complete PRD (from
or
)
Output: Engineering specifications at replicability-grade detail
Core Principle: Validate PRD first, design second. Incomplete requirements → incomplete specs.
Quick Start
Validate PRD against prd-validation-checklist.md
For Agent systems, also validate with agent-system-spec.md
Generate defect report; do NOT proceed until all ❌ resolved
Run bash scripts/generate_spec_skeleton.sh
Apply the Engineering Lenses to every component
Fill specs using spec-templates.md
Validate with bash scripts/validate_spec.sh
The Engineering Lenses
Apply these seven lenses to
every component during Phases 2-3. They are the engineering equivalent of
's Seven Lenses.
┌──────────────────────────────────────────────────────────────────┐
│ The Engineering Lenses │
├──────────────────────────────────────────────────────────────────┤
│ │
│ 1. ARCHITECTURE How does it fit? Layers, modules, comms. │
│ 2. DATA How modeled, validated, stored, migrated? │
│ 3. CONTRACT Interfaces? Versioning? What breaks? │
│ 4. FAILURE How does it fail? Detect, recover, cascade? │
│ 5. SECURITY Auth, authz, encryption, audit, secrets? │
│ 6. OPERATIONS Deploy, configure, monitor, scale, rollback? │
│ 7. REPLICABILITY All configs, deps, assumptions documented? │
│ │
└──────────────────────────────────────────────────────────────────┘ For every major component (service, module, API, data store, integration):
Lens Key Question Spec Output Architecture Where does it sit? What depends on it? Module diagram, dependency graph Data What data does it own? Shape? Consistency? Entity definitions, schemas Contract What's the interface? What can't change? API specs, event schemas Failure What can go wrong? What then? Error catalog, retry policies Security Who accesses? How protected? Auth rules, encryption spec Operations How deployed and observed? Config, metrics, alerts Replicability Any implicit knowledge not captured? Env setup, all dependencies
Workflow
Phase 0: PRD Validation ──────► Defect Report ──────► PRD Complete
↓
Phase 1: Decomposition ──► User Stories, Requirements Matrix
↓
Phase 2: Technical Design (Interactive) ──► Decision Log
↓
Phase 3: Detailed Specs ──► Engineering Lenses on every component
↓
Phase 4: Test Specs ──► Unit, Integration, E2E, Acceptance
↓
Phase 5: Task Breakdown ──► Tasks, Milestones, Risks
↓
Phase 6: Assembly & Replicability Review Phase 0: PRD Validation
Goal: Ensure PRD completeness before technical work begins.
Review against prd-validation-checklist.md
Agent systems: Also validate against agent-system-spec.md §PRD ValidationMark: ✅ Present | ⚠️ Unclear | ❌ Missing
Do NOT proceed until all ❌ resolved
Defect Report Template
markdown
# PRD Validation Report
** PRD: ** [title] | ** Status: ** [PASS / NEEDS REVISION]
## Critical Gaps (Must Fix)
| --- | ---------- | ------- | -------- | ------------ |
## Warnings (Should Clarify)
## Assumptions (Document explicitly with risk-if-wrong) Phase 1: Requirements Decomposition
Goal: Break PRD into structured, implementable requirements.
User Story Format
markdown
## US-001: [Title]
** Priority: ** P0/P1/P2
As a [role], I want [action], so that [benefit].
** Acceptance Criteria: ** (Given/When/Then)
** Business Rules: ** BR-001, BR-002
** Dependencies: ** US-002 Requirements Matrix
ID Requirement Source Type Priority FR-001 [description] US-001 CRUD/Logic P0 NFR-001 API response <200ms P95 PRD §7 Performance P0
Phase 2: Technical Design (Interactive)
Goal: Make architectural decisions with explicit user confirmation.
Decision Process
For each significant decision:
Present 2-3 options with pros, cons, effort, risk, and operational cost
Recommend with rationale
Wait for user confirmation Record in Decision Log
Decision Log
ID Decision Options Chosen Rationale Trade-offs Date D-001 Database PG, Mongo PostgreSQL ACID, JSON support Higher ops complexity [date]
Tech Stack
Component Choice Version Rationale Alternatives Language Framework Database Cache Queue Infra
Phase 3: Detailed Specification
Goal: Specs detailed enough for implementation without questions. Apply Engineering Lenses to every component.
Templates: spec-templates.md , feature-spec-template.md
3.1 Data Model
Per entity: purpose, all fields (type, nullable, default, constraints, description), indexes with rationale, relationships with cascade rules, validation rules, lifecycle (create/update/delete behavior).
3.2 API Specification
Per endpoint: method + path, auth/authz, request (params, body, validation rules), response (structure, all status codes with conditions), business logic steps, side effects, rate limits, idempotency.
3.3 Business Logic
Per complex rule: interface (inputs/outputs/errors), algorithm in pseudocode, decision table for branching, concrete edge case examples, transaction boundaries, rollback behavior.
3.4 Security Architecture ⭐
See security-spec-guide.md . Specify:
Area Must Document Authentication Protocol (OAuth2/JWT/session), token lifecycle, refresh flow, MFA Authorization Permission model (RBAC/ABAC), role-permission matrix, enforcement points Data Security Classification levels, encryption (at-rest, in-transit), PII handling Input Security Validation strategy, injection prevention, file upload rules Audit Events to log, format, retention period, tamper protection Secrets Storage method, rotation policy, access control
3.5 Operations & Deployment ⭐
See operations-spec.md . Specify:
Area Must Document Environments Dev, staging, prod differences; how to provision Deployment CI/CD pipeline, container spec, rollout strategy Configuration Every env var / config param with type, default, description, allowed values Monitoring Key metrics, alert thresholds, dashboard definitions Logging Format, levels, correlation IDs, PII redaction Scaling Triggers, resource limits, auto-scale rules Recovery Backup schedule, RTO/RPO, failover procedure, data restore process
3.6 AI/Agent Components
For AI features: ai-feature-spec.md
For Agent systems: agent-system-spec.md , covering:
Agent orchestration (reasoning loop, tool dispatch, state management)
System prompt as versioned artifact (with testing strategy)
Skills/Tools registration and dispatch mechanism
Memory system (working, session, long-term storage design)
RAG pipeline (embedding → chunking → indexing → retrieval → reranking)
Evaluation infrastructure and continuous feedback loops
Cost model per interaction
3.7 Migration & Compatibility
If replacing existing system. See spec-templates.md §Migration:
Data migration strategy (ETL pipeline, validation steps, rollback)
API backward compatibility (versioning scheme, deprecation timeline)
Feature parity matrix (old → new mapping, intentional gaps)
Cutover plan (strategy, rollback trigger, coexistence period)
Phase 4: Test Specification
Goal: Tests that verify all requirements are met.
Traceability Matrix
Requirement Unit Integration E2E Acceptance Performance Security FR-001 UT-001 IT-001 E2E-001 AT-001 - - NFR-001 - - - - PERF-001 -
Test Types
Unit: Per function—happy path, validation, edge cases, error handling.
Integration: Module interactions—API contracts, DB operations, external services.
E2E: Complete user journeys—critical paths with variations.
Acceptance: Given/When/Then—maps to acceptance criteria.
Performance: Load/stress under specified conditions—verify NFRs.
Security: Auth bypass, injection, permission escalation—verify security spec.
Templates in spec-templates.md .
Phase 5: Task Breakdown
Task Template
markdown
## TASK-001: [Title]
** Implements: ** FR-001, US-001 | ** Estimate: ** 4h
** Description: ** [what to do]
** Done Criteria: ** [how to verify]
** Dependencies: ** TASK-000 | ** Blocks: ** TASK-002 Milestones
Milestone Tasks Target Deliverable Verification M1: Data 001-003 [date] Schema + migrations Runs clean M2: API 004-008 [date] Endpoints + tests Integration tests pass M3: Security 009-011 [date] Auth + audit Security review pass M4: Deploy 012-014 [date] CI/CD + monitoring Health checks green
Risk Register
Risk Prob Impact Mitigation Contingency [risk] H/M/L H/M/L [prevent] [if happens]
Phase 6: Assembly & Replicability Review ⭐
Cross-Reference Check
Replicability Verification
The bar: Could a competent team rebuild this system from the spec alone?
Environment: All dependencies listed with pinned versions. Build + run commands.Configuration: Every env var, feature flag, config param documented (type, default, range).Data: Schema definitions, seed data specs, migration scripts referenced.Infrastructure: Deploy architecture, container specs, resource requirements.Integrations: Every external dep has connection details, auth, failure handling.Business Logic: No implicit knowledge—every "obvious" rule written down.Security: Auth flow, permissions, encryption, secrets handling fully specified.Monitoring: Metrics, alerts, dashboards defined—operable from day one.No TODOs/TBDs: Every placeholder resolved.
Run:
bash scripts/validate_spec.sh <spec_root> Output Structure
engineering-spec/
├── 00_Overview/
│ ├── SUMMARY.md, REQUIREMENTS_MATRIX.md, DECISION_LOG.md, TECH_STACK.md
├── 01_Requirements/
│ ├── USER_STORIES.md, FUNCTIONAL_REQS.md, NON_FUNCTIONAL_REQS.md
├── 02_Technical_Design/
│ ├── ARCHITECTURE.md, DATA_MODEL.md, API_SPEC.md
│ ├── BUSINESS_LOGIC.md, AI_COMPONENTS.md (if applicable)
├── 03_Security/
│ ├── AUTH_DESIGN.md, DATA_SECURITY.md, AUDIT_SPEC.md
├── 04_Operations/
│ ├── DEPLOYMENT.md, CONFIGURATION.md, MONITORING.md, RUNBOOK.md
├── 05_Testing/
│ ├── TEST_PLAN.md, ACCEPTANCE_TESTS.md
├── 06_Implementation/
│ ├── TASK_BREAKDOWN.md, MILESTONES.md, RISKS.md, MIGRATION.md
└── SPEC_INDEX.md Resources
scripts/generate_spec_skeleton.sh - Validate spec completeness
references/prd-validation-checklist.md references/spec-templates.md references/feature-spec-template.md references/ai-feature-spec.md references/agent-system-spec.md references/security-spec-guide.md references/operations-spec.md references/worked-example.md End-to-end worked example (HelpBot PRD→Spec) ⭐
Critical Reminders
Validate PRD first — Incomplete requirements = incomplete specsApply Engineering Lenses — Every component through all 7 lensesConfirm decisions — Document rationale, not just choicesTrace everything — Requirement → Spec → Test → RequirementSecurity is architecture — Not a checkbox; design it explicitlyOperations from day one — Deploy/monitor/debug specs are not optionalReplicability is the bar — If it can't be rebuilt from the spec, it's incomplete