rd-design · diff
git:20260807.e82ae86 to git:20260914.412d988
1 added, 1 removed. Audit A to A.
---
name: rd-design
description: >-
Produce an implementation-ready detailed design from approved requirements
and architecture decisions. Use when interface contracts, schemas, critical
flows, state machines, configuration contracts, trust boundaries, errors,
security, observability, concurrency, or recovery behavior must be specified
for software or infrastructure. Route requirements, option selection, review,
implementation, and operational execution to their owning workflows.
---
# rd-design
Produce **construction-ready detailed designs** based on approved requirements and technical proposals — interface definitions, data models, critical flows, error handling, security design, and concurrency control.
## Deliverables
- Detailed design document (interfaces / data models / flows / state machines)
- API contract definitions (OpenAPI / Protobuf / GraphQL Schema)
- Database schema design
- Security, error handling, and observability design sections
- Configuration, migration, verification, and rollback contracts when infrastructure or integration is in scope
## Execution Steps
### 1. Design Input Confirmation
- Confirm the approved requirements and any material technical proposal or high-level design (`rd-solution` output)
- Extract established: architectural decisions, tech stack selections, constraints
- Identify design scope boundaries: which modules/services are covered in this iteration
- Confirm traceability to PRD items or stakeholder-approved design decisions
**Completion criterion:** every in-scope design element traces to an approved requirement or decision, and each missing upstream decision is explicit before detailed contracts are written.
### 2. Interface Design
- Define inter-module interface contracts (inputs, outputs, invariants, preconditions, postconditions, error codes, ordering, and idempotency requirements)
- Distinguish and label internal vs. external interfaces
- Specify API versioning strategy
- Define backward compatibility constraints for interface changes
**Completion criterion:** every interface has ownership, inputs, outputs, invariants, failure behavior, ordering or idempotency semantics where applicable, and a compatibility boundary.
### 3. Data Model Design
- Entity-Relationship diagram (ER Diagram) with primary keys, foreign keys, and indexes annotated
- Field-level design: type, length, constraints, defaults, nullability
- Data lifecycle: creation → update → archival → deletion
- Data consistency strategy: strong consistency / eventual consistency / compensation
**Completion criterion:** every persisted or exchanged data element has type and constraint semantics, lifecycle ownership, relationship or index rationale where applicable, and a stated consistency model.
### 4. Critical Flow Design
- Sequence diagrams or flowcharts for core business processes
- Each flow annotated with: happy path, error path, timeout handling
- Concurrency control strategy: lock types, optimistic/pessimistic, retry strategy
- Idempotency design: which operations must be idempotent and how to guarantee it
**Completion criterion:** every critical flow covers success, failure, timeout, retry, concurrency, and idempotency behavior at the boundaries where they can change system state.
### 5. State Machine Design (if applicable)
- State definitions and valid transitions
- Handling strategy for invalid transitions
- Conflict resolution for concurrent state modifications
**Completion criterion:** every state and allowed transition has a trigger, guard, effect, invalid-transition behavior, and concurrent-conflict rule, or state-machine design is explicitly not applicable.
### 6. Security Design
General software security design considerations:
| Dimension | Design Content |
|-----------|----------------|
| Authentication | Authentication method selection, MFA requirements, token expiration strategy |
| Authorization | Permission model (RBAC/ABAC), principle of least privilege |
| Trust Boundaries | actors, zones, data flows, threat assumptions, and abuse cases |
| Input Validation | Validation rules, allowlist/denylist strategy, injection prevention |
| Data Protection | classification, minimization, transport/storage encryption, retention, and log sanitization |
| API Security | Rate limiting, signature verification, CORS policy |
| Secrets | credential ownership, storage, rotation, revocation, and exposure handling |
| Auditability | audit events, traceability, log retention, sensitive-field masking |
**Completion criterion:** every trust boundary and protected asset maps to the applicable authentication, authorization, validation, protection, secret, abuse-case, and audit controls, with omissions justified by risk.
### 7. Error Handling Design
- Error classification: recoverable / unrecoverable / requires human intervention
- Error code taxonomy design
- Error propagation strategy: propagate upward / handle at current layer / degrade
- Monitoring and alerting trigger conditions
**Completion criterion:** every material failure class has ownership, propagation or degradation behavior, user or caller visibility, observability, and recovery or escalation semantics.
### 8. Configuration and Change Design (if applicable)
- Define configuration ownership, source of truth, schema, defaults, validation rules, environment variance, and precedence
- Separate secrets from ordinary configuration and define provisioning, rotation, revocation, and redaction boundaries
- Define migration stages, compatibility window, rollback conditions, recovery point, and state reconciliation
- Specify expected observations and verification criteria without turning the design into an execution runbook
**Completion criterion:** configuration and change behavior has one source of truth, precedence and validation rules, secret boundaries, compatibility and rollback conditions, and observable verification criteria, or is explicitly not applicable.
### 9. Design Verification Notes
- Define how reviewers can verify the design: traceability matrix, checklist, walkthrough, prototype, or external standard check
- Mark unresolved design items with decision dependency, verification action, and owner or target date when known; otherwise mark them unassigned or unconfirmed
- Identify assumptions that must be validated before implementation starts
**Completion criterion:** reviewers can verify every material contract and traceability claim, and no unresolved item lacks an assignment state, dependency, and verification action.
## Context and Baseline Check
Pre-execution checks:
- Project design conventions and naming standards
- Existing interface design specs and API style guides
- Database design standards (naming, indexing, partitioning strategy)
- Established architectural decisions
- Security, privacy, compliance, or standards requirements that constrain design
## Tool Selection
- Inspect approved requirements, architecture decisions, schemas, and local conventions first
- Use `rd-research` when external standards or current technology facts materially constrain the design
- Use Context7 or an equivalent documentation retriever only for current framework, library, SDK, or API behavior
- Treat external repository designs as examples and verify applicability against this system's constraints
## Quality Gates
Pre-delivery checklist:
- [ ] Interface contracts complete (inputs / outputs / error codes / idempotency)
- [ ] Data model normalization or denormalization choices have documented rationale
- [ ] Critical flows cover happy / error / timeout paths
- [ ] Concurrency and idempotency requirements addressed
- [ ] Security dimensions covered (at minimum: authentication, authorization, input validation, data protection)
- [ ] Error handling strategy is explicit
- [ ] Configuration, migration, recovery, and rollback contracts are explicit when applicable
- [ ] Design is traceable to requirements (each module maps to a requirement item)
- [ ] Unresolved design decisions have assignment state, dependency, verification action, and owner or target date when known
- [ ] The document gives reviewers enough detail to assess feasibility and consistency
## Out of Scope
- - Do not proceed when missing upstream decisions would make the design speculative; approved requirements may be sufficient when no material architecture choice remains open
+ - Pause only when a missing upstream decision would make a key design contract speculative. When no material architecture choice remains open, approved requirements are sufficient; record non-blocking unknowns with an owner and verification action and continue the independently decidable work
- Do not leave items as "TBD" without a verification action and an explicit assignment state
- Do not design abstraction layers that will never be used
- Do not write implementation code, tests, deployment commands, or operational runbooks