generate-domain-tech-design

Instruction file imported from gargislalom/so-ai-training-101-pnw-team2 (.github/instructions/intake/workflows/generate-domain-tech-design.instructions.md). Copyright stays with the author.

Generate a Technical Design Document (TDD) for a loan servicing domain. The Confluence domain backlog page (and its child feature pages) serves as the authoritative source for what needs to be built; this command focuses exclusively on the technical design that enables delivery. Validates all prerequisites before generating anything.

CRITICAL: Never fabricate content. If information is ambiguous or missing, ask the user. Batch clarifying questions (up to 3 at a time) rather than asking one at a time.

CRITICAL: Never generate work estimates (story points, days, weeks, sprints). Estimation is a human decision.

Pre-Requisites

Read the domain-tech-design skill at .cursor/skills/domain-tech-design/SKILL.md for the full workflow, template, and sync protocol.

Phase 0: Input Validation

The user must provide a Confluence domain page URL. Examples:

• https://<JIRA_INSTANCE>/wiki/spaces/<CONFLUENCE_SPACE>/pages/820969473/Escrow+DomainID+2
• A page ID if they already have it

The user may also provide additional Confluence links to related pages (feature PRDs, cross-domain pages) that should inform the technical design.

If no URL is provided, ask: "Which domain should I generate a TDD for? Provide the Confluence domain page URL."

Extract pageId from the URL path (the numeric segment after /pages/).

Phase 1: Preflight Checks

Run all checks before creating any files. Report results as a checklist. If any critical check fails, stop and tell the user what's needed.

1a. Confluence Access

Verify Atlassian MCP connectivity and fetch the domain page:

1. Call getAccessibleAtlassianResources to confirm cloud ID b2337559-d66e-4f18-9f0f-be409d56ac32 is accessible
2. Call getConfluencePage(cloudId, pageId, contentFormat="markdown") to fetch the domain page
3. Validate the response contains: title, body, id
4. Extract from the page body:
   • Domain name (from the title or body header)
   • Domain prefix (e.g., ESC, BK, FC - from feature IDs in the body)
   • Feature list (feature IDs and names from the Feature/Epic overview table - used for architecture mapping, not reproduced as counts)
   • Cross-domain links (if cross-domain table exists)
   • Page version number and date (from the Confluence page metadata - used to pin the TDD to a specific backlog version)
5. Call getConfluencePageDescendants(cloudId, pageId, depth=2) to list child feature pages
6. For each child page, call getConfluencePage(cloudId, childId, contentFormat="markdown") to verify it's accessible

Report:

Confluence Access:
- [x] MCP connection: OK
- [x] Domain page "{title}" (ID: {pageId}): fetched
- [x] Domain: {name} ({PREFIX})
- [x] Page version: {version.number} ({version.createdAt})
- [x] Child feature pages: {N} accessible
- [x] Cross-domain links: {N} dependencies identified

If Confluence fetch fails, check whether the Atlassian MCP needs authentication. Report the error and stop.

1b. Knowledge Base Access

Verify AWS Bedrock KB is reachable with a lightweight test query:

aws bedrock-agent-runtime retrieve \
  --knowledge-base-id JOVETQBNBE \
  --retrieval-query text="{domain name} loan servicing overview" \
  --retrieval-configuration 'vectorSearchConfiguration={numberOfResults=2}' \
  --query 'retrievalResults[].content.text' \
  --output text

Use required_permissions: ["all"] for network access.

If you get a token expiration error, run aws sso login (with required_permissions: ["all"]) and retry.

Report:

Knowledge Base Access:
- [x] AWS Bedrock KB (JOVETQBNBE): reachable
- [x] Test query returned {N} results

If KB is unreachable, warn the user but allow proceeding - the TDD will have more [TBD] gaps without KB enrichment.

1c. Workshop and Discussion Context

Scan for domain-relevant workshop and ODR content:

1. Read docs/xd-playground/workshops/prototype/src/data/workshops.json
2. Search for workshops where domain matches the target domain name (case-insensitive)
3. Search across all workshops for discussions where:
   • relatedDomains[] includes the target domain
   • keyTopics[] contains domain-related terms
   • systemsMentioned[].systemId references domain services
4. Scan docs/discussions/{Domain}/ for direct domain discussions
5. Scan docs/discussions/{Domain}/odr/ for ODR session summaries
6. Scan docs/discussions/Workshop/ for cross-workshop mentions

Report:

Workshop & Discussion Context:
- [x] workshops.json: {N} workshops with direct domain match
- [x] Cross-domain discussion references: {N} discussions
- [x] docs/discussions/{Domain}/: {N} session folders found
- [x] ODR sessions: {N} summaries available
- [x] Tech sessions: {N} (these are highest priority for TDD)
- [ ] No workshop data found (TDD will rely more on Confluence + KB)

1d. Architecture Context

Check for existing architecture artifacts:

1. Check docs/architecture/{Domain Name}.md (or variations with spaces/hyphens)
2. Check docs/architecture/database/service-{domain}-table-design.md
3. Check docs/architecture/state-machines/{domain}-state-machines.md
4. Read docs/architecture/Domain Events.md and check for events in the domain's namespace
5. Read docs/architecture/microservices.md for domain service definitions
6. Check requirements/features/{domain}-management/ for existing PRDs and epics

Report:

Architecture Context:
- [x] Architecture doc: found at docs/architecture/{file}
- [ ] Architecture doc: not found (TDD becomes the first architecture artifact)
- [x] Database design: found / not found
- [x] State machines: found / not found
- [x] Domain events: {N} events in {domain}.* namespace
- [x] Microservice definitions: {services found}
- [x] Existing PRDs: {N} in requirements/features/
- [x] Existing epics: {N} in requirements/features/

1e. Target Directory

Check whether this domain already has a TDD:

1. Check if docs/domains/{domain-slug}/ exists
2. If exists, check for tech-design.md
3. If a TDD exists, ask: "A TDD already exists for {domain}. Do you want to regenerate it (overwrite), update it with fresh Confluence data, or cancel?"

Report:

Target Directory:
- [ ] docs/domains/{domain-slug}/: does not exist (will create)
- [x] docs/domains/{domain-slug}/: exists with tech-design.md

Phase 2: Preflight Summary and Approval Gate

Present a consolidated summary of all preflight results:

============================================
  Domain TDD Preflight: {Domain Name} ({PREFIX})
============================================

Source Material:
  Confluence:   page v{version} ({date}), {N} child pages
  Workshops:    {N} direct + {N} cross-domain discussions
  ODR Sessions: {N} summaries ({N} tech sessions)
  KB:           accessible / degraded (proceeding without)

Architecture Baseline:
  Architecture doc:  found / will be created by TDD
  Database design:   found / not found
  State machines:    found / not found
  Domain events:     {N} in namespace
  Existing PRDs:     {N}

Output:
  Tech Design: docs/domains/{domain-slug}/tech-design.md
  Confluence:  "Tech Design: {Domain}" (after approval)

============================================
Proceed with TDD generation? (yes/no)
============================================

Wait for explicit user approval before proceeding.

Phase 3: Generate Technical Design Document

On approval, follow the domain-tech-design skill workflow (Phases 1-5 in SKILL.md).

The Confluence domain page and its child feature pages are the backlog - we read them as input but do not replicate them locally. The sole output is the TDD.

Confluence is the source of truth for the backlog. The TDD must not duplicate information that belongs in Confluence:

• Do NOT include feature/epic/story counts in the Document Information table or anywhere else. These change frequently and create sync confusion.
• Do NOT include an In Scope / Out of Scope table. Scope is owned by the Confluence backlog and PRD.
• The Feature Map table in Section 1 should list feature IDs, names, and owning services for architecture mapping purposes, but omit epic counts per feature.
• PIN the TDD to a specific Confluence page version and date in the Document Information table so readers know which backlog snapshot informed the design.
• The TDD adds technical design value (service boundaries, data models, event flows, state machines, API surface, build order) - it does not restate the product backlog.

Create docs/domains/{domain-slug}/tech-design.md using the template at .cursor/skills/domain-tech-design/tdd-template.md.

For each TDD section, gather content from the prioritized sources:

Do not add a dedicated Non-Functional Requirements section; platform SLOs and operational targets belong in platform docs or PRDs, not domain TDDs.

Delivery evolution preface: Sections that contain low-level technical detail must include a brief blockquote at the top acknowledging that the content is an initial projection and will evolve during delivery. Apply this to:

• Section 4 (Domain Events): Event names, payloads, and consumer relationships will be refined as services are built.
• Section 5 (Data Model): Table schemas, access patterns, and entity relationships are expected to evolve.
• Section 6 (Service Flows): Interaction patterns, error handling, and retry semantics will be finalized during implementation.
• Section 7 (State Management): State machines may gain intermediate states or transition rules.
• Section 8 (API Surface): Paths, schemas, and error codes will be defined in implementing epics.

Each preface should be a single sentence in a > blockquote, specific to the section's content. Do not use generic disclaimers.

KB enrichment: For each section where source material is thin or ambiguous, run a targeted KB query. Log every query in the KB Enrichment Log section. Use contextual phrases combining the domain name with the specific gap (see .cursor/skills/domain-tech-design/reference.md for query examples).

Entity relationship diagrams and service boundaries: When a domain spans multiple microservices, the ER diagrams MUST be scoped per service - one diagram per owning service's table. Do NOT draw a single monolithic ER diagram with relationship lines crossing service boundaries, as this implies foreign key relationships and direct table access that do not exist in a microservice architecture. Instead:

• Generate one ER diagram per service showing only entities within that service's table
• Mark identifiers shared across services (e.g., loanId, payeeId) as plain attributes, not foreign keys
• Add a separate "Cross-Service Data Integration" diagram showing how services exchange data through domain events and shared identifiers
• Use dotted lines for shared identifiers and solid labeled arrows for domain events

Integration pattern rule: Domain-to-domain communication is always event-driven. Adapters are the only components that use synchronous API calls, and they communicate exclusively with external systems. Do not show synchronous API calls between domain services in sequence diagrams or integration tables.

Mermaid diagrams: Generate at minimum:

• C4 container diagram (Section 3)
• Domain event flow diagram (Section 4)
• Per-service ER diagrams + cross-service integration diagram (Section 5)
• 3-5 sequence diagrams for critical workflows (Section 6)
• State diagram for primary entity lifecycle (Section 7)
• Build order dependency graph (Section 12)

3b. Update docs/domains/README.md

Add the new domain to the table in docs/domains/README.md.

Phase 4: Post-Generation Validation

Run through the validation checklist from the skill:

• All Confluence features represented in the Feature Map and Feature-Architecture Map (by ID, not by count)
• No feature/epic/story counts duplicated from Confluence
• Every mermaid diagram renders (no syntax errors in code blocks)
• C4 container diagram covers all owning services from the backlog
• Domain events section lists published and consumed events with owning service
• Cross-domain dependencies match the Confluence cross-domain links table
• KB Enrichment Log present with all queries logged
• Workshop/ODR source citations present for architecture decisions
• DynamoDB table design follows single-table conventions
• All acronyms defined in glossary
• TDD Document Information table links back to the source Confluence domain page

Report validation results and flag any items that need manual attention.

Phase 5: Next Steps

After generation, tell the user:

1. Review the TDD at docs/domains/{domain-slug}/tech-design.md
2. Check open questions in Section 13 - these need stakeholder input
3. Review KB gaps in the KB Enrichment Log - unresolved items need follow-up
4. When approved, run /sync-domain-tdd-confluence or say: "Sync the {Domain} TDD to Confluence" to create or update the "Tech Design: {Domain}" page as a child of the domain backlog page (see .cursor/commands/sync-domain-tdd-confluence.md)
5. Workshop registration: If the domain has workshop prototype content, the glossary acronyms can be added to the prototype hover system