Technical Blueprint Skill: Feature Design Document (TDD)

​

Blueprint vs spec vs architecture document

​

Best for

​

What it produces

• Problem statement with evidence — error rates, support tickets, business impact; not just a feature description
• Goals and non-goals — specific, measurable outcomes and explicit out-of-scope items to prevent scope creep
• Background and context — what a reviewer needs to know about the current state to evaluate the design
• Proposed design — high-level approach, detailed component interaction (sequence diagram with error paths), key algorithms in pseudocode, data model changes (SQL DDL + migration strategy), API contract changes (request/response schemas + error codes)
• Alternatives considered — at least two alternatives with specific, evidence-based rejection reasons
• Security considerations — STRIDE threat analysis for new attack surface introduced
• Performance and scalability estimation — latency delta, query count, memory impact, load test plan
• Observability specification — structured log events, metrics (counters, histograms), alerting conditions
• Feature flag strategy — flag name, type, default state, rollout phases, cleanup plan
• Data migration plan — migration type, steps, backward compatibility checklist, rollback SQL
• Rollout plan — deployment strategy, phases, success criteria, proceed triggers
• Rollback plan — explicit trigger conditions and numbered steps an on-call engineer can follow
• Test plan — unit, integration, E2E, load, and security tests with pass criteria and edge cases
• Documentation requirements — OpenAPI spec updates, runbook, user guide, ADR if needed
• Dependencies and blockers — upstream dependencies, downstream dependents, decision dependencies
• Open questions and milestones — unresolved questions with owners and resolution deadlines

​

How to invoke it

claude "Write a technical design document for adding TOTP-based two-factor authentication to the admin login flow. We use PHP 8.3, PDO/MySQL, and Twig templates. The TOTP secret must be stored encrypted. Recovery codes must be supported."

gemini "Write a technical design document for implementing a token-based webhook signing system"

technical-blueprint [feature or component name]

​

Example scenarios

• “Write a technical design document for implementing a token-based webhook signing system”
• “Design how we will add two-factor authentication (TOTP) to our admin portal”
• “Create a TDD for migrating our synchronous payment processing to an async queue-based system”

​

Key concepts

​

Design doc philosophy (Google/Stripe standard)

• Short as possible, long as necessary. If it takes more than 45 minutes to read, it is too long.
• Trade-off focused. The Alternatives Considered section is mandatory. It proves you evaluated options, not just implemented the first idea.
• A conversation starter, not a contract. Share early and revise often. The process of writing it surfaces gaps before they become production bugs.
• Living. Update it as implementation evolves. A stale design doc is worse than no design doc.

​

The three mandatory sections

​

Error path coverage

• What happens when the call times out
• What happens when the call returns a 5xx error
• Retry behavior (count, backoff strategy, circuit breaker)
• Fallback behavior when the dependency is unavailable (cached response, degraded mode, queue for later)
• What the user sees for each error scenario

​

Observability by design

Log events:   [feature].request_started    → INFO  (request_id, user_id, operation)
              [feature].request_completed  → INFO  (request_id, duration_ms, status)
              [feature].request_failed     → ERROR (request_id, error_code, message)

Metrics:      [feature]_requests_total          Counter  (status, operation)
              [feature]_request_duration_seconds Histogram (operation)
              [feature]_errors_total             Counter  (error_code)

Alerts:       High error rate   → P2 if > X% 5xx for 5 min
              High latency      → P2 if p99 > Xms for 5 min

​

Feature flag strategy

​

Data migration strategy

• Migration type: Additive only (new tables/columns) vs destructive (renames, type changes requiring downtime)
• Backward compatibility: Can old code run against new schema? Can new code run against old schema during rollback window?
• Data backfill: Is existing data migrated? Via background job, on-read migration, or one-time script?
• Rollback SQL: Every migration must have a corresponding rollback script

​

Performance estimation

​

Anti-patterns (what this prevents)

• Jumping to implementation without a problem statement. Agents that skip the “why” and go straight to code design solve the wrong problem thoroughly.
• Alternatives Considered as an afterthought. Vague rejections like “too complex” without evidence undermine the document’s credibility.
• No rollback plan. Every design touching production needs a rollback plan with trigger conditions and steps.
• Designing in isolation. A blueprint is a conversation starter — listing open questions and assumptions is how you get the feedback that prevents costly bugs.
• Ignoring security for “non-security” features. Reporting dashboards, notification systems, and admin UI features all introduce IDOR, data exposure, and authorization bypass risks.

​

Interview process

​

Output structure

​

Handoff

• 4-technical-specification.md — functional and non-functional requirements
• 7-system-architecture.md — architectural patterns and technology decisions
• 8-database-design-document.md — existing data model and table definitions
• 9-api-design-document.md — existing API contracts and endpoint specifications
• 11-admin-access-control-specification.md — permission requirements
• 12-security-threat-model.md — threat mitigations to incorporate

• 15-implementation-plan.md — feature designs sequenced into build phases
• architecture-decision-record — decisions made during design that warrant a permanent ADR

​

Quality gate

• The problem statement includes concrete evidence (metrics, tickets, benchmarks) justifying why this needs to be built now
• At least two alternatives are documented with specific, evidence-based rejection reasoning — not “too complex” without supporting evidence
• A rollback plan exists with explicit trigger conditions and numbered steps an on-call engineer can follow without asking anyone
• Security considerations address new attack surface introduced by this design (STRIDE analysis completed)
• The test plan covers unit, integration, and at least one end-to-end scenario with defined pass criteria