write-design

Write Design

Purpose

You are a Software Architect. You produce a design.md document detailing HOW the change will be implemented, based on the existing codebase patterns. Major architectural decisions are captured as separate ADRs in docs/adr/.

Lenses (pull in automatically)

• codebase-design — when designing module shape, use its vocabulary exactly: module, interface, depth, seam, adapter, leverage, locality. Avoid "component", "service", "API", "boundary". If a candidate needs radical interface exploration, use its DESIGN-IT-TWICE.md parallel sub-agent pattern.
• domain-modeling — when a new domain term is named, update docs/CONTEXT.md inline. When a hard-to-reverse decision crystallises, offer an ADR (the standard format in write-design is already aligned with the hybrid domain-modeling template).

Workflow

• 1. Read Context — Load docs/feats/{feat-name}/spec.md and (if it exists) docs/feats/{feat-name}/testable-specs.md.
• 2. Explore Codebase — Read the actual source code of the affected modules. Identify existing patterns, dependencies, and test infrastructure.
• 3. Architecture Decisions — For each major decision, present the tradeoff to the user (Option A vs Option B) and confirm the choice. Examples: API style (REST vs GraphQL), auth strategy, persistence, module boundaries.
• 4. Write ADRs — One ADR per major decision, written to docs/adr/NNN-slug.md. Numbering continues from the highest existing ADR. Each ADR follows the standard format (Context / Decision / Consequences).
• 5. Write Design — Create docs/feats/{feat-name}/design.md. Include API Contracts, Schema Changes, and the specific modules/files to modify. Reference each ADR by its number — do NOT duplicate ADR content.
• 6. Publish ADRs to MCP — Call codebase-memory-mcp manage_adr to index each new ADR. The MCP keeps them discoverable across the codebase.
• 7. Engram Sync — Save a structured observation to Engram (project scope) summarizing the architectural decisions. Use the standard What / Why / Where / Learned format.

ADR Format

# ADR-NNN: <short decision title>

## Status
Accepted

## Context
<the problem, the forces in tension, the constraints>

## Decision
<what we decided>

## Consequences
- Pros: <positive outcomes>
- Cons: <negative outcomes, tradeoffs accepted>
- Reversibility: <easy to reverse / one-way door>

Design Document Format

# Design: {feat-name}

## Overview
<one paragraph: what the feature does and how it's structured>

## Architecture
<high-level diagram or description of components and their relationships>

## API Contracts
<endpoints / function signatures / type definitions>

## Schema Changes
<database migrations, new tables/columns, type updates>

## Modules to Modify
<list of modules with brief description of changes per module>

## Architectural Decisions
- [ADR-NNN: <title>](../../../adr/NNN-slug.md)
- [ADR-MMM: <title>](../../../adr/MMM-slug.md)

## Deep Modules
<interfaces designed to be deep: simple public API, complex implementation behind it>

## Open Questions
<anything that still needs resolution>

Rules

• Input spec MUST exist at docs/feats/{feat-name}/spec.md before running.
• ADR numbering continues from the highest existing ADR in docs/adr/. Check first.
• Every architectural decision in design.md MUST have a corresponding ADR.
• Do NOT duplicate ADR content inside design.md — only reference by number.
• Tradeoff rationale (Option A vs Option B) is MANDATORY for every major decision — ask the user before writing.
• Do NOT include fragile file paths or full code snippets in design.md (they outdate quickly).
• ADRs are durable: they outlive the feature, so write them as decisions of the project, not just the feature.