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 prd-writing-guide or ai-agent-prd ) 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 prd-writing-guide '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 Validation

• Mark: ✅ Present | ⚠️ Unclear | ❌ Missing

• Do NOT proceed until all ❌ resolved

Defect Report Template

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

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

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

• Every user story → functional requirement(s)

• Every requirement → technical spec section(s)

• Every spec → test case(s)

• Every test → traces back to requirement

• All external dependencies documented with versions

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

• Create output structure

• scripts/validate_spec.sh

• Validate spec completeness

• references/prd-validation-checklist.md

• PRD validation checklist

• references/spec-templates.md

• Specification templates

• references/feature-spec-template.md

• Feature spec template

• references/ai-feature-spec.md

• AI feature specification

• references/agent-system-spec.md

• Agent system engineering spec ⭐

• references/security-spec-guide.md

• Security architecture spec ⭐

• references/operations-spec.md

• Operations & deployment spec ⭐

• references/worked-example.md

• End-to-end worked example (HelpBot PRD→Spec) ⭐

Critical Reminders

• Validate PRD first — Incomplete requirements = incomplete specs

• Apply Engineering Lenses — Every component through all 7 lenses

• Confirm decisions — Document rationale, not just choices

• Trace everything — Requirement → Spec → Test → Requirement

• Security is architecture — Not a checkbox; design it explicitly

• Operations from day one — Deploy/monitor/debug specs are not optional

• Replicability is the bar — If it can't be rebuilt from the spec, it's incomplete