--- name: "td-workflow" description: "Generate a Technical Design document from an approved Solution Design. Use when the user requests a TD, or when triage identifies TD as the next artifact in the design chain." license: "MIT" metadata: author: "Srinivas K, Mahesvaran S, Srikanth Y, Thirukumaran V, Vignesh V R" version: "1.0.0" --- # Technical Design (TD) Workflow ## Overview Generate a Technical Design document — a low-level architecture document containing API specifications, physical data model, tech architecture diagrams, and implementation details. ## Prerequisites Checklist - [ ] Input: Approved Solution Design (SD) document — **MANDATORY** - [ ] Confluence MCP server available - [ ] Jira MCP server available **CRITICAL RULE:** A TD cannot be created without an approved SD (which in turn requires an approved DD). If no applicable SD exists: 1. Inform the user that a Solution Design must be completed first 2. If no DD exists either, route to `dd-workflow` skill first 3. If DD exists but no SD, route to `sd-workflow` skill 4. Only return to the TD workflow after the SD is approved ## Step-by-Step Guide ### Step 1: Input Identification See [Discovery Pattern](references/discovery-pattern.md) for the full search methodology. #### Accept Input Accept the SD reference from: Confluence page, chat attachment, pasted content, or direct reference. #### Search for Context Search Confluence and Jira for: - The referenced Solution Design (full content) - The parent Design Direction - Related Technical Designs in the same domain - Existing API specifications or contracts - Database schemas or data dictionaries - Infrastructure documentation - Related Jira technical tasks or implementation stories #### Present Findings ``` Solution Design: [SD title and link] Parent Design Direction: [DD title and link] Related artifacts found: - [list with Confluence/Jira links] I will create a Technical Design based on [SD reference]. Proceed? ``` Wait for user confirmation before continuing. --- ### Step 2: Input Validation See [TD Validation Rules](references/td-validation.md) for complete validation criteria. Validate that all required inputs for a TD are present. If any are missing, request them from the user before proceeding. **Do NOT proceed to Step 3 until all required inputs are validated.** --- ### Step 3: Brainstorming (Iterative) #### Load Context Reference these during brainstorming: - [Architecture](references/architecture.md) — Approved patterns, AWS services - [Cloud Reference Architecture](references/cloud-reference-architecture.md) — AWS reference patterns - [Principles](references/principles.md) — Enterprise architecture principles - [Cyber Security TD](references/cyber-security-td-v1.md) — Cybersecurity rules for TD - [Physical Data Model](references/physical-data-model.md) — Physical data model guidance - [Data Standards](references/data-standards.md) — Data and privacy principles #### Instructions - Propose the technical implementation approach based on the SD - This step is a LOOP — continue refining until the user explicitly accepts - Only proceed to Step 4 when user confirms #### TD-Specific Brainstorming Scope Discuss and refine: - **API specifications** — Endpoints, methods, request/response schemas, error codes - **Physical data model** — Tables, columns, types, indexes, constraints, partitioning - **Technology stack** — Specific AWS services, frameworks, libraries, versions - **Infrastructure** — Compute, storage, networking, scaling configuration - **Deployment** — CI/CD pipeline, deployment strategy (blue/green, canary, etc.) - **Security implementation** — Authentication, authorisation, encryption, secrets management - **Observability** — Logging, metrics, tracing, alerting - **Error handling** — Retry strategies, circuit breakers, dead letter queues - **Performance** — Caching strategy, connection pooling, query optimisation - **Migration plan** — Data migration, feature flags, rollback strategy #### Output — MANDATORY Save Save to: `{workspace}/output/td-{artifact-name}-brainstorm.md` The brainstorm file MUST contain ALL structured sections (API Specifications, Physical Data Model, Technology Stack, Infrastructure, Deployment Strategy, Security Implementation, Observability, Error Handling, Migration Plan, New Risks, Governance Tier, Assumptions, Open Questions). **CRITICAL:** Present brainstorm in chat and get explicit user approval before proceeding. --- ### Step 4: Document Generation #### Load Context (additional) - [Risk Assessment Framework](references/risk-assessment-framework.md) #### Load Template Fetch the TD template from Confluence Template `3630792726` (space ID1) using `getConfluenceTemplate`. New TD pages has to be created using this template. **CRITICAL:** The TD template structure is DIFFERENT from DD and SD templates. Key differences: - Design Endorsement references "Technology Owner" not "Enterprise Architect" - Design Approval includes "Business Owner" and "Technology Owner" - Consulted includes "Business Analyst" and "QA" - No "Architecture Principles Alignment" section - Has unique sections: Physical Data Model, API Contracts, AWS Tagging, Technical Debt Commentary - Template MUST be fetched and followed exactly **API CONTRACTS:** Generate as a separate OpenAPI 3.0.3 YAML file saved to `{workspace}/output/{artifact-name}-openapi.yaml`. Reference the file in the TD page as an attachment. #### Generate 1. **Read the brainstorm file** — authoritative source for all design content 2. Read the template structure 3. Generate the TD document as Markdown following the template 4. Map brainstorm content to template sections 5. Align to architecture principles 6. Apply principles enforcement checklist 7. Score risks using the risk assessment matrix 8. Align to cybersecurity and data/privacy standards 9. Ensure traceability back to the SD 10. API specs detailed enough for implementation (OpenAPI-style) 11. Data model detailed enough for DDL generation 12. **Verify completeness:** Every API, table, infrastructure component, and risk MUST appear 13. If deviating, mark with "⚠️ DEVIATION" callout #### Output Save generated document to: `{workspace}/output/td-{artifact-name}.md` --- ### Step 5: Diagram Create an **AWS Technical Architecture Diagram** using the `diagram-workflow` skill and following [Diagramming Standards](references/diagramming-standards.md): - Show AWS services (Lambda, DynamoDB, S3, SQS, SNS, EventBridge, Step Functions, API Gateway, etc.) - Include VPC and subnet layout where applicable - Include data flows between services and security boundaries - Follow colour conventions for lifecycle stage, design impact, and interaction type --- ### Step 6: Review & Publish **HARD RULE:** The publish step MUST NOT proceed unless the template has been fetched in the SAME session. Present the generated document for human review. **If user approves and requests Confluence publish:** Use the `confluence-publish` skill. ## Troubleshooting ### Issue: No approved SD exists **Solution:** Route to `sd-workflow` skill first. The chain is strictly DD → SD → TD. ### Issue: TD scope unclear (full solution vs single component) **Solution:** Ask the user which SD components this TD should cover. ### Issue: Template cannot be fetched **Solution:** STOP and inform the user. Never generate without the template. ## Best Practices - The TD focuses on HOW at implementation level - Must maintain traceability to the SD's component design - API specifications should follow organisational API standards - Physical data model should include indexing and partitioning strategy - Infrastructure choices should reference approved technology radar - Include cost estimates where possible (AWS pricing)