SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssdd-define

sdd-define

General & other

View repository

Updated 10-16 01:06

About this skill

SDD Define

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

Quick start

Transform a file BRAINSTORM_*.md into a DEFINE_{FEATURE_NAME}.md clear, testable and ready for the next gate.

  1. Receive and read the Brainstorm Markdown file.
  2. Extract only facts, decisions, preliminary requirements, boundaries and dependencies supported by the Brainstorm.
  3. Fill in a draft mandatorily using assets/DEFINE_TEMPLATE.md.
  4. Flag ambiguities instead of guessing.
  5. Calculate the initial Clarity Score.
  6. Ask the user clarification questions only for gaps that prevent clarity, measurability, testing or the Verify Gate.
  7. Write the Acceptance Tests in EARS using references/EARS.md.
  8. Run the ambiguity scan from references/CLARIFY.md.
  9. Derive a Verify Gate according to references/VERIFY_GATE.md.
  10. Only consider the DEFINE ready when the quality gates of this Skill are met.
  11. Save or deliver the final document as DEFINE_{FEATURE_NAME}.md.
  12. End the document with exactly one next step: Execute o **SDD Design by RDD**.

For the complete flow and interaction rules, consult references/define-protocol.md.

When to use / When not to use

Use when:

  • there is a Markdown file produced by the SDD Brainstorm by RDD;
  • the user wants to transform the Brainstorm into formal and verifiable requirements;
  • specific clarifications are still needed before Design;
  • success criteria, acceptance tests, scope and Verify Gate need to be formalized.

Does the app handle money, tax or personal data? After this DEFINE and before Design, run the complementary skill sdd-governanca: it recommends the missing governance requirements, and the decision on each one is yours.

Do not use when:

  • the user is still exploring the problem, audience or solution direction; in this case, run the SDD Brainstorm by RDD first;
  • the goal is to design architecture, components or detailed implementation;
  • the goal is to write code, run a build or release;
  • there is no Brainstorm nor enough information to reconstruct its function without inventing requirements.

Required data

Mandatory

  • Brainstorm Markdown file.

Preferably accept files in the standard: BRAINSTORM_{FEATURE_NAME}.md

If the file is not present or legible, ask the user to send it before drafting the DEFINE.

Optional

  • user clarification responses;
  • samples already cited in the Brainstorm;
  • documentation or technical context provided by the user;
  • real test, smoke, eval or typecheck commands of the project;
  • deployment, infrastructure, or technical domain conventions.

Do not require internet. Do not assume access to the repository, filesystem, CI, database, APIs, or project commands.

Step-by-step procedure

1. Read and classify the Brainstorm

Read the entire document before asking anything.

Extract:

  • Raw Input / initial idea;
  • problem;
  • users and beneficiaries;
  • selected approach;
  • key decisions;
  • suggested requirements;
  • success criteria;
  • YAGNI / removed or postponed items;
  • constraints;
  • dependencies;
  • samples and ground truth;
  • validations already performed;
  • TBDs, limitations, and open questions.

Treat decisions validated in the Brainstorm as pre-validated context. Do not reopen discovery questions without a concrete reason.

2. Create the draft from the asset

Use assets/DEFINE_TEMPLATE.md as the single source of structural truth for the final document.

Do not reconstruct an alternative template from memory.

Fill in only with:

  • content explicitly present in the Brainstorm;
  • answers given by the user in this phase;
  • technical inferences clearly labeled as hypotheses, when unavoidable and not yet validated.

When mandatory information cannot be determined, flag the ambiguity and ask; never invent a value to make the document appear complete.

3. Structure the requirements

Organize the content into:

  • Problem Statement;
  • Target Users;
  • Goals with MUST / SHOULD / COULD priorities;
  • measurable Success Criteria;
  • Acceptance Tests;
  • Out of Scope;
  • Constraints;
  • Technical Context;
  • Assumptions.

Avoid duplication. When the Brainstorm and a later answer conflict, the most recent user answer prevails and the change must be recorded in Clarifications.

4. Write measurable Success Criteria

Every success criterion representing quality, volume, time, cost, availability, accuracy, or rate must contain an observable target.

Do not use vague adjectives such as:

  • fast;
  • scalable;
  • reliable;
  • easy;
  • high volume;
  • high accuracy.

Convert into a metric only when the number is supported by the Brainstorm or confirmed by the user.

If the number is missing, ask. Do not invent.

5. Write Acceptance Tests in EARS

Read references/EARS.md.

Each acceptance test:

  • must express an observable behavior;
  • must use a recognized EARS pattern;
  • must keep the EARS anchor words in English: When, While, If, then, Where, shall;
  • must have a single primary behavior.

When there is a plausible unwanted trigger, include at least one test If ... then ... shall ....

For a bugfix, include at least one non-regression requirement with shall continue to.

Do not finalize while there is a vague or untestable acceptance test.

6. Calculate the Clarity Score

Score from 0 to 3:

  • Problem;
  • Users;
  • Goals;
  • Success;
  • Scope.

Scale:

  • 0 = missing;
  • 1 = vague or incomplete;
  • 2 = clear, but details are missing;
  • 3 = crystal clear and actionable.

Sum to a maximum of 15.

The minimum to mark the DEFINE as ready is 12/15.

Do not inflate the score to pass the gate.

7. Clarify without guessing

Read references/CLARIFY.md.

Scan the nine categories:

  1. Scope;
  2. Data model;
  3. UX flow;
  4. NFRs;
  5. Integrations;
  6. Edge cases;
  7. Constraints;
  8. Terminology;
  9. Done signal.

Classify each category as Clear, Partial or Missing.

For Partial and Missing that affect the DEFINE, create an objective question internally.

Prefer one main question per interaction. If the context requires grouping, never exceed 5 questions in the same round.

When there are clear alternatives:

  • use multiple choice;
  • present 2–4 options;
  • put the recommended one first;
  • allow an open-ended answer when necessary.

After each answer:

  • replace the ambiguity in the body of the DEFINE;
  • record the decision in ## Clarifications;
  • recalculate the affected parts of the Clarity Score.

8. Detect LLM Prompts usage

Set LLM Prompts as true or false.

Mark true when there is a strong signal of runtime prompts or a sufficient combination of weak signals, such as:

  • explicit LLM provider/model;
  • system prompt, user prompt, RAG, embeddings, classifier, synthesizer;
  • chatbot, agent, automatic response, or report generator with LLM;
  • paths or components dedicated to prompts.

Mark false when there is no relevant signal.

If there is only an isolated weak signal and the intention is ambiguous, ask the user.

Record the rationale in Notes.

9. Define the Verify Gate

Read references/VERIFY_GATE.md.

The DEFINE must contain exactly one verify_gate block with:

  • kind;
  • cmd;
  • pass_when;
  • threshold;
  • manual_fallback.

Accepted Kinds:

  • test;
  • smoke;
  • eval;
  • typecheck;
  • manual-ux.

Derive the type from the nature of the Acceptance Tests.

Do not invent a project command.

If the real command cannot be safely inferred from the provided material:

  • ask which command checks the behavior; or
  • ask the user to choose among plausible gate options;
  • use manual-ux only when acceptance is genuinely human/visual, not as a shortcut for the absence of a command.

Without a valid Verify Gate, the DEFINE is not ready.

10. Resolve Open Questions

## Open Questions must not hide blocking ambiguity.

Before concluding:

  • resolve everything that affects scope, behavior, success criterion, acceptance tests, or Verify Gate;
  • allow only questions that are truly non-blocking for Design;
  • if there are none, use None - ready for Design.

11. Validate the document

Run, when a filesystem and Python are available:

python scripts/validate_define.py <caminho-do-DEFINE.md>

Consume the script output as a structural lint. The script does not replace semantic judgment.

Fix failures before declaring the document ready.

12. Generate and save the DEFINE

Preferred name: DEFINE_{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 of the five phases sit side by side, without subfolders.

If there is a writable filesystem, save as sdd/DEFINE_{FEATURE_NAME}.md (or .claude/sdd/DEFINE_{FEATURE_NAME}.md when that folder already exists).

If there is no filesystem, deliver the complete Markdown as a .md file for download when the platform allows it.

Do not declare Ready for Design if:

  • Clarity Score < 12/15;
  • there is blocking ambiguity;
  • Acceptance Tests fail the EARS rules;
  • relevant Success Criteria are not measurable;
  • Verify Gate is missing or incomplete.

13. End with the standard handoff

The final section of the document must be exactly:

## Next Step

Execute o **SDD Design by RDD**.

Do not add slash commands, paths, upload instructions, references to GPT/Skill, or parallel actions after this text.

Validations and quality checklist

Before considering the DEFINE complete:

  • The Brainstorm was read in full.
  • Pre-validated decisions from the Brainstorm were preserved.
  • The document uses assets/DEFINE_TEMPLATE.md.
  • Problem Statement is specific.
  • There is at least one Target User with a pain point.
  • Goals are prioritized.
  • Relevant Success Criteria are measurable.
  • Acceptance Tests use EARS.
  • There is an If/Then test for a plausible unwanted trigger.
  • Bugfix, when applicable, contains shall continue to.
  • The nine clarification categories were swept.
  • There are no unresolved blocking ambiguities.
  • Clarity Score is >= 12/15.
  • Out of Scope is explicit.
  • Constraints are separated from assumptions.
  • Technical Context includes LLM Prompts: true or false with justification.
  • There is exactly one valid Verify Gate.
  • The Verify Gate does not contain an invented command.
  • Open Questions does not contain a blocking question.
  • The lint scripts/validate_define.py, when executable, passes.
  • The final file is called DEFINE_{FEATURE_NAME}.md.
  • Next Step contains only Execute o **SDD Design by RDD**.

Exception handling

  • Missing Brainstorm: request the Markdown file; do not silently reconstruct a Brainstorm.
  • Incomplete Brainstorm: extract what exists and clarify only the necessary gaps.
  • Contradictory Brainstorm: ask which decision prevails before formalizing the requirement.
  • User changes a Brainstorm decision: accept the most recent decision, update the dependent sections, and record it in Clarifications.
  • Clarity Score < 12: continue clarification; do not mark as ready.
  • Metric without a number: ask for the target; do not fabricate a number.
  • Unknown Verify Gate command: ask; do not invent project commands.
  • No access to the code/repository: do not claim that paths, tests, or infrastructure were inspected.
  • User wants to finish with blocking pending items: generate only a draft with status Needs Clarification, without the final completion handoff.
  • Feature without interface: UX flow may be N/A when this is supported by the scope; do not create UI artificially.
  • Purely UX feature: manual-ux is allowed, with an objective human checklist.

Examples

Expected input

File: BRAINSTORM_CONCILIACAO_BANCARIA.md

The Skill must:

  1. extract the problem, users, selected approach, YAGNI, and suggested requirements;
  2. assemble the DEFINE draft;
  3. identify gaps such as metrics, handling of divergences, supported formats, and a verifiable gate;
  4. ask only what is necessary;
  5. generate DEFINE_CONCILIACAO_BANCARIA.md.

Clarification question

If the Brainstorm says only "processing must be fast", do not convert that into an arbitrary number.

Ask, for example: Qual tempo máximo deve ser aceito para processar um par extrato + razão: (a) até 30s [recomendado], (b) até 60s, (c) até 2 min, (d) outro?

Final handoff

## Next Step

Execute o **SDD Design by RDD**.

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