sdd-design

SDD Design

In the first response of this skill, start with this line, only once: sdd-design v1.0.0 · out/2026 · versão atual: https://github.com/robertodiasduarte/sdd-starter/releases/latest

Quick start

Transform Brainstorm + DEFINE into an implementable technical DESIGN.

1. Read the Brainstorm and the DEFINE in full.
2. Read the UX Review if the user also provides it.
3. Separate authoritative requirements, original intent, prior decisions, and technical evidence.
4. Inspect code/project context when it is available.
5. Identify technical gaps that prevent concrete architecture or File Manifest.
6. Ask only what is necessary, preferably one main question per interaction.
7. Create the architecture and document significant decisions as inline ADRs.
8. Create a complete File Manifest, code standards, data flow, integrations, and testing strategy.
9. Apply the conditional rule for LLM Prompts from references/llm-prompts.md.
10. Mandatorily fill in assets/DESIGN_TEMPLATE.md.
11. Run python scripts/validate_design.py <DESIGN.md> when a filesystem and Python are available.
12. Save or deliver DESIGN_{FEATURE_NAME}.md.
13. End the document only with Execute o **SDD Build by RDD**.

Consult references/design-protocol.md throughout the entire flow. Consult references/advisor-review.md only if there is a formal external technical review before the Build.

Required data

Mandatory

• Brainstorm Markdown file, preferably BRAINSTORM_{FEATURE_NAME}.md;
• Define Markdown file, preferably DEFINE_{FEATURE_NAME}.md.

Read both before formulating questions.

Optional

• UX_REVIEW_{FEATURE_NAME}.md, when it exists;
• directory tree or relevant project files;
• technical conventions of the repository;
• documentation of APIs, schemas, queues, database, or infrastructure;
• real commands for tests, lint, typecheck, build, or smoke;
• catalog of available agents/specialists;
• user clarification responses.

Do not require internet. Do not claim to have inspected the repository, agents, infrastructure, or code when that material is not accessible.

Hierarchy of sources

For requirements and behavior:

1. most recent explicit user response;
2. UX Review, if provided and if it does not contradict core requirements;
3. DEFINE;
4. Brainstorm.

Use the Brainstorm to recover intent, explored alternatives, YAGNI, and decision context, but do not reopen requirements already closed in the DEFINE without reason.

For current technical facts:

1. project files/code that are actually accessible;
2. technical documentation provided by the user;
3. explicit user responses;
4. clearly marked inferences.

If two relevant sources conflict, ask before consolidating the decision.

Procedure

1. Read the input artifacts

Extract from the Brainstorm:

• problem and original intent;
• selected approach;
• rejected alternatives;
• key decisions;
• items removed/deferred due to YAGNI;
• dependencies and samples;
• assumptions and limitations.

Extract from DEFINE:

• Problem Statement;
• Target Users;
• Goals and priorities;
• Success Criteria;
• Acceptance Tests;
• Out of Scope;
• Constraints;
• Technical Context;
• Assumptions;
• Verify Gate;
• flag LLM Prompts.

Extract from UX Review, if any:

• UX/CX MUSTs;
• flows;
• states;
• interaction constraints;
• recommendations that affect architecture or implementation.

Do not duplicate the textual content of the artifacts in DESIGN. Convert only what affects technical decisions.

2. Check input readiness

Before designing, confirm:

• DEFINE is sufficiently closed to guide implementation;
• critical requirements have no contradictions;
• LLM Prompts is literally true or false;
• the Verify Gate exists or there is an objective signal of completion;
• Out of Scope is explicit.

If any of these points blocks architecture, ask the user. Do not silently “fix” DEFINE.

3. Inspect the available technical context

When there is an accessible project/codebase:

• identify language/framework;
• observe directory structure;
• locate similar modules;
• observe configuration conventions;
• locate existing tests;
• identify reusable integrations and abstractions;
• identify logging/observability patterns;
• identify the agent catalog, if it exists.

When there is none:

• do not invent paths, libraries, or agents;
• ask for the stack and minimal structure needed for a concrete File Manifest;
• allow a greenfield project only after the user confirms the stack/technical base.

4. Detect blocking technical decisions

Internally list the decisions needed for:

• component boundaries;
• persistence and data model;
• integration contracts;
• synchronous/asynchronous execution;
• idempotency and retries;
• authentication/authorization;
• configuration;
• observability;
• testing strategy;
• files to create/modify;
• LLM runtime, when applicable.

Do not ask about choices that are already resolved by the sources or by the project's existing standards.

Prefer one main question per message. When alternatives are clear, present 2–4 options, recommend one with justification, and allow an open alternative.

5. Create Architecture Overview

Produce a readable ASCII diagram representing:

• inputs;
• components;
• storage;
• external integrations;
• outputs;
• main flow direction.

The diagram must be consistent with Components and Data Flow.

Do not add a component without a defined function.

6. Define Components

For each component, record:

• name;
• responsibility;
• technology/standard;
• inputs;
• outputs;
• dependencies.

Favor cohesive components and simple boundaries.

Avoid a new abstraction when an existing structure meets the requirement.

7. Document Key Decisions as inline ADRs

For each significant decision, record:

• Status;
• Date;
• Context;
• Choice;
• Rationale;
• Alternatives Rejected;
• Consequences.

Record decisions that change architecture, maintenance cost, contracts, data, deployment, security, or testability.

Do not create an ADR for trivial detail.

When the choice comes directly from DEFINE, preserve the decision and explain only its technical impact; do not pretend that alternatives were re-evaluated at this phase.

8. Create File Manifest

List all files that the Build must create, modify, or delete.

Each line must contain:

• number;
• path;
• action;
• purpose;
• owner/agent;
• dependencies.

Rules:

• use real project paths when available;
• do not invent paths pretending they were observed;
• in greenfield, use paths consistent with the confirmed stack;
• include test files;
• include configurations, migrations, schemas, and prompts when they are part of the implementation;
• avoid circular dependency;
• number dependencies by the manifest index.

If specialized agents are not known, use (general) and record Agent Discovery: Not available.

9. Define Code Patterns

Provide short, copy-paste ready snippets only for key patterns that reduce ambiguity in the Build.

Prioritize:

• central signature/interface;
• relevant schema/model;
• error pattern;
• configuration;
• integration contract.

Use the real language of the confirmed stack.

Do not write the entire implementation in DESIGN.

10. Apply LLM Prompts rule

Consult references/llm-prompts.md.

If LLM Prompts: false:

• perform defensive re-check on Brainstorm + DEFINE + UX Review + Design scope;
• if there are no signals, do not create section ## LLM Prompts;
• if there are conflicting signals, ask before continuing.

If LLM Prompts: true:

• create ## LLM Prompts between Code Patterns and Data Flow;
• inventory every planned LLM prompt/runtime;
• classify each item as one-shot or loop;
• define contract per prompt;
• cross-reference the inventory with the File Manifest and services that call LLM;
• do not generate the final prompt in this phase.

11. Describe Data Flow

Represent the end-to-end operational sequence.

For each relevant step, make clear:

• input;
• transformation;
• persistence;
• external call;
• state/failure;
• output.

Also cover the main error path when it affects architecture.

12. Define Integration Points

For each external integration, record:

• system;
• type;
• authentication;
• direction;
• relevant timeout/retry;
• failure behavior.

Do not invent credentials, endpoints, or limits.

If there are no integrations, use None.

13. Plan Testing Strategy

Map requirements and risks to tests:

• unit;
• integration;
• E2E;
• smoke/eval/typecheck when derived from DEFINE.

Do not invent a tool if the project does not use it or the user has not confirmed it.

Preserve alignment with the DEFINE's Acceptance Tests and Verify Gate.

14. Define Error Handling

Cover at least:

• invalid input;
• external dependency unavailable;
• timeout;
• persistence failure when applicable;
• conflict/idempotency when applicable;
• LLM error when applicable.

Record retry only when safe and compatible with idempotency.

15. Define Configuration, Security, and Observability

Configuration:

• externalize tunables;
• avoid secrets in code;
• mark the origin of sensitive values.

Security:

• authentication/authorization;
• input validation;
• secrets;
• PII/sensitive data;
• least privilege;
• feature-specific risks.

Observability:

• logs;
• metrics;
• tracing when applicable;
• signals tied to Success Criteria and Verify Gate when possible.

16. Validate cross-consistency

Confirm:

• all components appear in the diagram or have justification;
• File Manifest implements all relevant components;
• manifest dependencies are acyclic;
• tests cover risks and Acceptance Tests;
• integrations have error handling;
• cited configurations exist in the manifest when they require a file;
• security and observability do not contradict constraints;
• LLM Prompt Inventory is complete when true;
• Out of Scope does not appear accidentally in the plan.

17. Fill in the canonical asset

Use assets/DESIGN_TEMPLATE.md as the sole structural source of the final document.

Preserve the headings and the order of the mandatory sections.

Add ## LLM Prompts only under the defined condition.

Remove placeholders. Do not leave TBD, {placeholder} or [NEEDS CLARIFICATION] in a DESIGN marked Ready for Build.

18. Run deterministic lint

When there is a filesystem and Python:

python scripts/validate_design.py <caminho-do-DESIGN.md>

Fix all structural failures before delivering the final version.

The script validates structure and basic consistency; it does not replace architectural review.

19. Save and deliver

Default name: DESIGN_{FEATURE_NAME}.md

Where to save. Write to sdd/ at the project root — a visible folder, the same in any agent. If the project already has .claude/sdd/, continue in it. The documents for the five phases sit side by side, without subfolders.

If there is a project filesystem:

• save as sdd/DESIGN_{FEATURE_NAME}.md (or .claude/sdd/DESIGN_{FEATURE_NAME}.md when that folder already exists);
• do not silently overwrite an existing file.

If there is none:

• deliver the .md for download when the platform allows it.

20. End with the standard handoff

The last section must be exactly:

## Next Step

Execute o **SDD Build by RDD**.

Do not add a slash command, path, upload, GPT/Skill, or parallel action after this text.

Quality gate

Before marking Ready for Build:

• Brainstorm read in full.
• DEFINE read in full.
• UX Review incorporated when provided.
• Authoritative requirements preserved.
• Technical context observed or explicitly confirmed.
• Architecture Overview clear.
• Components consistent with the diagram.
• Significant decisions documented with rationale.
• Alternatives Rejected and Consequences recorded in the relevant decisions.
• File Manifest complete, with tests/configuration when applicable.
• Paths were not falsely presented as observed.
• File Manifest dependencies are not circular.
• Code Patterns are copy-paste ready and compatible with the stack.
• LLM Prompts follows the conditional rule.
• Data Flow is consistent with the architecture.
• Integration Points have failure behavior.
• Testing Strategy covers requirements and risks.
• Error Handling covers relevant failures.
• Configuration does not contain hardcoded secrets.
• Security Considerations are specific.
• Observability defines useful signals.
• There is no Out of Scope item planned for implementation.
• There is no placeholder, TBD, or blocking clarification.
• scripts/validate_design.py passes when executable.
• Final document is named DESIGN_{FEATURE_NAME}.md.
• Next Step contains only Execute o **SDD Build by RDD**.

Exception handling

• Missing Brainstorm: ask for the file; do not silently reconstruct.
• Missing DEFINE: ask for the file; do not produce the final Design from the Brainstorm alone.
• DEFINE contradicts Brainstorm: follow DEFINE for requirements and record the divergence only if it affects a technical decision.
• UX Review contradicts DEFINE: ask which direction prevails when the conflict is material.
• LLM Prompts missing/ambiguous: ask; do not choose on your own.
• No code context: ask for the required stack/structure; do not pretend to inspect.
• File Manifest cannot be made concrete: keep draft status and clarify.
• Library/service not confirmed: present alternatives and ask if the choice is blocking.
• User wants to finish with a blocking pending item: deliver Draft/Needs Clarification, without stating Ready for Build.
• Formal external review: apply references/advisor-review.md and record each note as APPLIED or REBUTTED.

---

Part of the Open by RDD SDD — https://github.com/robertodiasduarte/sdd-open