Design creation

Design Creation

Description

Use when creating a DESIGN.md technical design document for a spec that has been approved. Not for specs with Status != APPROVED — STOP and inform the user if SPEC.md is not yet approved. Not for task breakdown — use the task-creation skill.

Instructions

You are creating a technical design document. Follow these rules strictly.

Required Inputs

Before creating a DESIGN.md, you must have:

• Approved SPEC.md (load specs/XXX/SPEC.md)
• Access to ../../CONSTITUTION.md for project standards

If SPEC.md is not approved (Status != APPROVED), STOP and inform the user.

Template

Always use the template structure from ../../.framework/templates/DESIGN.template.md

Field Rules

Metadata

• ID: Must match the SPEC.md ID exactly
• Name: Must match the SPEC.md Name exactly
• Status is always DRAFT until Tech Lead approves
• Author: developer name + "/ AI-assisted"
• Reviewer: leave blank (Tech Lead fills this)
• Date: today's date

Overview

• Explain the technical approach at a high level
• Must address HOW to build what SPEC.md describes
• Reference CONSTITUTION.md patterns and standards

Architecture

• List all components that will be created or modified
• Use the table format: Component | Change Type | Description
• Change Type must be one of: New / Modify / Use existing
• Include a simple diagram (Mermaid) if interactions are complex

Conditional Sections

Data Model, API/Interfaces, Dependencies, Security Considerations, and Risks & Tradeoffs are included ONLY when relevant. Do NOT include a section just to write "No X required" — omit it entirely.

• Data Model: Include if this design creates or modifies data structures. Follow CONSTITUTION.md naming conventions.
• API / Interfaces: Include if this design exposes or consumes APIs. Follow CONSTITUTION.md API conventions.
• Dependencies: Include if new external libraries, services, or systems are required.
• Security Considerations: Include if there are authentication, authorization, validation, or data protection implications.
• Risks & Tradeoffs: Include if there are key technical risks, rejected alternatives, or significant tradeoffs.

Omit the section. Do not write "No X required" or "Standard X per CONSTITUTION.md" — if CONSTITUTION.md already covers it, silence is the correct output.

Acceptance Criteria Traceability

• Map every SPEC.md acceptance criterion to the component or mechanism that addresses it
• Format as table: Acceptance Criterion | Addressed By
• Every AC must have at least one entry — if an AC cannot be addressed, add an Open Question
• This section is critical for downstream: Tasks uses it for AC coverage validation, Implementation uses it for per-task compliance gates, Review uses it to trace ACs to code

Open Questions

• Unresolved technical decisions that need answers
• Format as checklist: - [ ] Question here?
• These must be resolved before moving to TASKS.md

Constraints

• Every design decision must align with CONSTITUTION.md
• Do NOT include task breakdown (belongs in TASKS.md)
• Do NOT include code implementation (belongs in actual code)
• Do NOT include timeline or estimates (project management concern)
• Do NOT contradict or expand scope beyond SPEC.md
• All bracket placeholders from template must be removed from output; if info is missing, add an Open Question instead

Output

Save the file to: specs/XXX-{slug}/DESIGN.md

Must be in the same folder as the corresponding SPEC.md.

Verification

• All acceptance criteria from SPEC.md are technically addressable
• Acceptance Criteria Traceability table maps every AC to a component
• Architecture follows CONSTITUTION.md patterns
• No scope creep beyond SPEC.md boundaries
• All applicable sections filled; inapplicable conditional sections omitted entirely
• Status set to DRAFT