Sdd Design

<!-- MEMORY-CONTRACT v1 -->

Memory contract. This command persists across sessions through engram

(registered as an MCP server in this tool). Use this tool's own engram memory

tools to honor the rules below — do not assume any other persistence layer.

>

- Recall before acting: on a continuation keyword ("listo", "dale",

"ready", "where did we leave off"), first search engram for prior work on

this change before starting fresh; summarize what you found, then continue.

- Validate after saving: after any save, search engram back for the key or

a unique phrase — a "saved" tool response is NOT proof. Retry once; if it

still fails, tell the user the save failed. Never report "saved" on the tool

response alone.

- Summarize at close: before ending, write a session summary (goal, work

done, decisions, next steps, files). Recovery is never automatic.

- If engram is unreachable (not installed / not on PATH): emit a visible

warning that engram was not found and that this work will NOT persist. DO NOT

report memory as saved; DO NOT proceed silently as if it had persisted.

Purpose

The design defines HOW to implement what the specs say the system MUST do. It is the bridge between requirements and code. It documents technical decisions and their justification.

Process

Step 0 — Load project context + Spec context preload

Load the project's context and conventions if present, then load the change's spec scenarios if present. Both are non-blocking.

Step 1 — Read prior artifacts

Read:

• The proposal artifact:
• Read docs/sdd/{change-name}/proposal.md for full content.
• If the disk file is absent (legacy change): fall back to searching prior work for sdd/{change-name}/proposal and retrieve it.
• If neither exists and prior-work storage is not reachable: proposal content is passed inline from the caller.
• The spec artifact:
• Read docs/sdd/{change-name}/spec.md for full content.
• If the disk file is absent (legacy change): fall back to searching prior work for sdd/{change-name}/spec and retrieve it.
• If neither exists and prior-work storage is not reachable: spec content is passed inline from the caller.
• ai-context/architecture.md if it exists
• ai-context/conventions.md if it exists

Then read real code:

• Relevant entry points
• Files that will be affected according to the proposal
• Existing patterns to follow (not reinvent)
• Existing tests (they reveal current contracts)

Step 2 — Design the technical solution

Evaluate the solution considering:

• Patterns already used in the project (prefer consistency)
• Minimal impact on existing code
• Testability
• Reversibility (rollback plan from the proposal)

Skills Registry cross-reference

When recommending a skill, library, or technology pattern in the design, check the project Skills Registry extracted in Step 0 and follow these rules:

• Registered skill: reference it by its exact registered name (e.g., typescript, react-19).
• Available in the project's technology guidance but not registered in the project: mark it as optional with a note, e.g. [optional — not registered in project; add via /skill-create <name>].
• Not available in the project's technology guidance: state it as a new dependency and flag it for review.

This check applies to the Technical Decisions table, the Testing Strategy table, and any inline recommendations in the design narrative. It ensures design output stays aligned with the project's declared toolset.

Step 3 — Create design.md

Persist the design artifact (disk-primary, two steps, disk FIRST):

First write the full design markdown to docs/sdd/{change-name}/design.md, then persist a pointer + summary keyed sdd/{change-name}/design (type architecture) with content = "path: docs/sdd/{change-name}/design.md\n\n{1-3 sentence summary}".

If prior-work storage is not reachable: still write the disk artifact (the source of truth); skip the pointer only.

Content format:

# Technical Design: [change-name]

Date: [YYYY-MM-DD]
Proposal: sdd/[name]/proposal

## General Approach

[High-level description of the technical solution in 3-5 lines]

## Technical Decisions

| Decision   | Choice           | Discarded Alternatives         | Justification     |
| ---------- | ---------------- | ------------------------------ | ----------------- |
| [decision] | [what is chosen] | [alternative A, alternative B] | [why this choice] |

## Data Flow

[ASCII diagram or description of the flow]

Example:

Request → Middleware → Controller → Service → Repository → DB ↓ Validator (Zod) ↓ Response DTO

````

File Change Matrix

Interfaces and Contracts

[Type definitions, interfaces, DTOs, schemas to be created]

// Example
interface RefreshTokenRequest {
  refreshToken: string;
}

interface RefreshTokenResponse {
  accessToken: string;
  expiresIn: number;
}

Testing Strategy

Migration Plan

[If there are changes to DB, schema, or existing data:]

• Step 1: [migration script]
• Step 2: [gradual rollout if applicable]
• Step 3: [post-cleanup]

[If no migration: "No data migration required."]

Open Questions

[Aspects that need clarification before implementing]

• [question]: [impact if not resolved]

[If none: "None."]

````

Step 4 — ADR Detection and Generation

This step is non-blocking: any failure produces a warning in the output, never status: blocked or status: failed.

1. Scan for significant decisions: read the Technical Decisions table in the newly created design.md. For each row, check whether the text (across all columns) contains any of the following keywords (case-insensitive): pattern, convention, cross-cutting, replaces, introduces, architecture, global, system-wide, breaking

2. No match → skip silently: if no row matches any keyword, do nothing and produce no output for this step.

3. Match found → generate ADR: a. Prerequisite check: if docs/templates/adr-template.md does not exist OR docs/adr/README.md does not exist, log the warning "ADR infrastructure not found (docs/templates/adr-template.md or docs/adr/README.md missing) — skipping ADR generation" and stop this step. b. Determine next ADR number: count existing files matching docs/adr/[0-9][0-9][0-9]-*.md. The next number is count + 1, zero-padded to 3 digits (e.g., 001, 012, 100). c. Derive slug: <NNN>-<change-name>[-<first-matched-keyword>], all lowercase, spaces replaced with hyphens, non-alphanumeric characters (except hyphens) removed, truncated to 50 characters. d. Copy template: copy docs/templates/adr-template.md to docs/adr/<slug>.md. e. Pre-fill content in the new ADR file:

• Title (H1): derived from the slug (replace hyphens with spaces, title-case)
• Status: Proposed
• Context section: content from the Justification column of the first matched row
• Decision section: content from the Choice column of the first matched row

f. Update index: append a new row to the ADR index table in docs/adr/README.md: | [NNN] | [Title] | Proposed | [YYYY-MM-DD] | [brief one-line context] | g. Artifacts: add docs/adr/<slug>.md to the artifacts list.

---

Examples of well-documented decisions

Well documented

| Input validation | Zod at controller layer | Class-validator, manual |
The project already uses Zod for DB schemas (Drizzle).
Maintaining consistency avoids two validation systems. |

Poorly documented

| Validation | Zod | others | It's better |

---

Useful ASCII diagrams

# Authentication flow
Client → POST /auth/login
            ↓
        AuthController
            ↓
        AuthService.validateCredentials()
            ↓
        UserRepository.findByEmail()
            ↓
        bcrypt.compare(password, hash)
            ↓ (success)
        JwtService.sign(payload)
            ↓
        Response { token, refreshToken }

# Module structure
auth/
├── auth.module.ts
├── auth.controller.ts
├── auth.service.ts
├── strategies/
│   ├── jwt.strategy.ts
│   └── local.strategy.ts
└── dto/
    ├── login.dto.ts
    └── refresh.dto.ts

Step 5 — Summary to caller

Return a clear executive summary to the caller with all artifacts produced (design.md and any ADR file created in Step 4).

Output Contract

Return this result shape:

{
  "status": "ok|warning|blocked",
  "summary": "Design for [change-name]: [N] affected files, approach [brief description], risk [level].",
  "artifacts": ["docs/sdd/{change-name}/design.md"],
  "next_recommended": ["sdd-tasks (requires spec + design completed)"],
  "risks": ["[technical risk if found]"]
}

Rules

• ALWAYS read real code before designing — never assume the structure
• Every decision MUST have justification (the "why", not just the "what")
• Follow existing project patterns unless the change explicitly corrects them
• The file matrix must be concrete (real paths, not "some auth file")
• ASCII diagrams are preferable to long descriptions
• If I detect that the proposal is incompatible with the current architecture, I report it as a blocker
• I do NOT write implementation code — that is sdd-apply