fattain-naime/engineering-docs/technical-blueprint

Purpose

Produce a Technical Design Document (TDD) that captures the engineering design of a specific feature or component with enough detail that any qualified engineer on the team can implement it correctly. This document is a thinking tool first, an artifact second - the process of writing it surfaces gaps before they become production bugs.

Unlike an architecture document (what the system is), a blueprint specifies how a specific piece will be built.

Input

Works best with: The name of the feature, component, or change to be designed. Also valuable: The technical specification or requirements document, existing codebase context, known constraints (performance targets, security requirements, API contracts that must be maintained).

Example invocation: 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.

Key Concepts

Design Doc Philosophy (Google/Stripe Standard)

A design doc is:

• 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.
• A conversation starter. Share early and revise often. A design doc is not a contract.
• Living. Update it as the implementation evolves. Stale design docs are worse than no design docs.

The Mandatory Sections

These three sections separate a senior engineer's design doc from a junior one:

1. Alternatives Considered - What else was evaluated and why it was rejected
2. Security Considerations / Threat Model - What can be attacked or abused
3. Rollback Plan - What happens if this change needs to be reverted

Observability

Every new feature must be observable in production. Document in the blueprint:

• Logging: What structured log events does this feature emit? Include correlation IDs, operation type, duration, and outcome. Define log levels (ERROR for failures, WARN for degraded state, INFO for business events).
• Metrics: What metrics does this feature expose? (e.g., request count, error rate, latency histogram, queue depth, custom business metrics like "payments_processed_total").
• Tracing: How does this feature participate in distributed tracing? What spans are created? What context is propagated?
• Alerting: What conditions should trigger alerts? Define thresholds, severity levels (P1-P4), and escalation paths.

Feature Flag Strategy

When a feature is rolled out incrementally or may need to be disabled quickly:

• Flag name: Descriptive, namespaced (e.g., feature_totp_2fa, feature_webhook_v2).
• Flag type: Boolean toggle, percentage rollout, user allowlist, or environment-based.
• Default state: Off (safe default) or On (for must-have features).
• Rollout phases: Internal testing -> staging -> canary (5%) -> full rollout.
• Cleanup plan: When and how the flag is removed after full rollout. Flags that live indefinitely become tech debt.

Data Migration Strategy

When the feature requires schema changes or data migration:

• Migration type: Additive only (new tables/columns) vs destructive (column renames, type changes).
• Backward compatibility: Can the old code run against the new schema? Can the new code run against the old schema?
• Data backfill: Is existing data migrated? How? (Background job, on-read migration, one-time script.)
• Rollback: Can the migration be reversed? What data is lost if rolled back?

Backward Compatibility Testing

When the feature changes existing behavior or contracts:

• API compatibility: Do existing API consumers break? Run contract tests against the old OpenAPI spec.
• Data compatibility: Can old data be read by new code? Can new data be read by old code during rollback?
• Configuration compatibility: Do old config files still work? Are new config values optional with sensible defaults?

Documentation Requirements

Every feature blueprint must specify what documentation is needed:

• API documentation: OpenAPI spec updates, changelog entry.
• Runbook: Operations guide for on-call engineers (how to monitor, troubleshoot, and recover from failures).
• User documentation: End-user guides, admin guides, migration guides.
• ADR: If the design made a significant architectural decision, create an Architecture Decision Record.

Monitoring and Alerting Setup

Before the feature ships, the following must be in place:

• Dashboards: What operational dashboard panels are needed? What do they display?
• Alerts: What thresholds trigger alerts? What is the severity? Who is paged?
• SLOs: Does this feature affect existing SLOs? Are new SLIs defined?
• Runbook link: Every alert must link to a runbook with diagnosis and remediation steps.

Error Path Handling

Sequence diagrams must show error paths, not just the happy path. For every critical flow:

• Document what happens when each external call fails (timeout, 5xx, network error).
• Document retry behavior (count, backoff, circuit breaker).
• Document fallback behavior when a dependency is unavailable (cached response, degraded mode, queue for later).
• Document what the user sees for each error scenario.

Performance Estimation

Before implementation, estimate the performance impact:

• Added latency: How many milliseconds does this feature add to existing request paths?
• Added queries: How many additional database queries per request?
• Memory impact: Does this feature add memory pressure (large caches, in-memory state)?
• CPU impact: Does this feature add CPU-intensive operations (crypto, serialization, image processing)?
• Load test plan: What load test validates the performance estimate?

Dependency and Blocker Tracking

Document what this feature depends on and what blocks it:

• Upstream dependencies: What must be completed before this feature can start? (Other features, infrastructure, third-party integrations.)
• Downstream dependents: What features or teams depend on this being completed?
• External blockers: Vendor approvals, security reviews, compliance audits.
• Decision dependencies: What decisions must be made before implementation can proceed?

Anti-Patterns

• Jumping to implementation details without stating the problem.
• Designing in isolation and presenting as a fait accompli.
• Skipping alternatives considered ("we just knew this was right").
• No measurable success criteria.
• No rollback plan ("it's fine, we'll figure it out").
• Sequence diagrams that only show the happy path.
• No observability plan ("we'll add logging later").

Document Length

Target length: 5-10 pages per feature (excluding appendices).

Shorter is better than longer. If the document exceeds the target, check for:

• Redundant content that can be cut
• Overly verbose explanations
• Content that belongs in a separate reference document
• Material the agent already knows (don't explain what HTTP is)

If the document is significantly shorter than the target, check for:

• Missing sections
• Insufficient detail in critical areas
• Unaddressed edge cases

Conflict Resolution

When your analysis conflicts with the user's stated preference:

1. Present both positions — show your analysis and their preference side by side
2. Explain the trade-off — what are the consequences of each choice?
3. Recommend with reasoning — state your recommendation and why
4. Respect the user's decision — they own the final call
5. Document the decision — record it as an [owner-specified] override with reasoning

Application

Phase 1: Socratic Clarification & Brainstorming (Mandatory Interview)

Interview Mechanism: Use tool calls (e.g., AskUserQuestion) to present questions — do NOT ask inline in the conversation. The user selects from options rather than typing responses. One question per tool call, multiple-choice options preferred, with "I don't know, you decide" as an escape hatch.

Context Loading: Before asking ANY questions, read ALL prior documents in .engineering-docs/ to extract already-known information. Look for:

• Team size, budget, timeline (from business-plan)
• Tech stack, hosting (from system-architecture)
• Target users, JTBD (from user-personas)
• Constraints, regulatory requirements (from business-plan)
• Scope, features (from technical-specification)

If information exists in a prior document, USE IT — do not re-ask.

Maximum 2-3 questions per skill. Only ask about:

• Skill-specific details not covered in prior documents
• Technical decisions that affect this specific document
• Clarifications on ambiguous requirements

Ask questions to resolve:

1. Error handling expectations: What are the critical error recovery paths for this feature (e.g., what happens when external calls fail)?
2. Observability requirements: What specific logging, metrics, or alerting is needed for this feature?

Wait for the user's response to these questions before drafting the final blueprint.

Phase 2: Problem and Context (40-60 min)

State the problem, motivation, and goals precisely. Define explicit non-goals.

Phase 3: Proposed Design (2-3 hrs)

Describe the solution at the right level of detail: high-level approach, key algorithms or patterns, data model changes, API contract changes.

Phase 4: Alternatives Considered (40-60 min)

Document at least two alternatives and why they were rejected with specific reasoning.

Phase 5: Security and Risk (40-60 min)

Apply basic STRIDE thinking to the proposed design. What new attack surface does this introduce?

Phase 6: Test Plan and Rollback (40-60 min)

Define how correctness is verified and what the rollback procedure is if this fails in production.

Phase 7: Revision (After User Review)

If the user requests changes after reviewing the blueprint:

1. Read the user's feedback carefully — understand what they want changed
2. Check for conflicts — does the requested change contradict the database schema, API contracts, or security requirements from upstream documents?
3. Apply changes — update the document, cascading changes through the design, alternatives, security analysis, and test plan
4. Re-run consistency check — verify the design still references valid data model entities, API endpoints, and security controls
5. Update metadata — set last_updated to today's date
6. Confirm with user — show the changes and get approval

Gotchas