prd-to-engineering-spec
Transform PRD (Product Requirements Document) into actionable engineering specifications. Creates detailed technical specs that developers can implement step-by-step without ambiguity. Covers data modeling, API design, business logic, security architecture, deployment, and agent system design. Use when: converting product requirements to technical specs, validating PRD completeness, planning technical implementation, creating task breakdowns, or defining test specifications. Triggers: 'PRD to spec', 'convert requirements', 'technical spec from PRD', 'engineering doc from requirements', 'validate PRD'.
How do I install this agent skill?
npx skills add https://github.com/okwinds/miscellany --skill prd-to-engineering-specIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a framework and Bash utility scripts for transforming Product Requirements Documents (PRDs) into engineering specifications. It includes templates and validation logic to ensure technical designs are complete and free of common issues like hardcoded keys. No malicious patterns were identified.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerfail
13/16 files flagged
What does this agent skill do?
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)
| # | Category | Issue | Impact | Resolution |
|---|----------|-------|--------|------------|
## 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 structurescripts/validate_spec.sh- Validate spec completenessreferences/prd-validation-checklist.md- PRD validation checklistreferences/spec-templates.md- Specification templatesreferences/feature-spec-template.md- Feature spec templatereferences/ai-feature-spec.md- AI feature specificationreferences/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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/okwinds/miscellany/prd-to-engineering-spec">View prd-to-engineering-spec on skillZs</a>