sdd-build

SDD Build

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

Execute real implementation. Do not treat Build as the generation of an isolated document.

Summary flow

1. Receive Brainstorm, Define, and Design.
2. Confirm writable access to the project/code.
3. Extract requirements, Verify Gate, LLM Prompts and File Manifest.
4. Validate consistency between the three artifacts and the actual state of the project.
5. Create a task plan ordered by dependencies.
6. Recommend an execution mode and ask for the user's decision before the first change.
7. Ask about pre-build external review when the case justifies it and the capability exists.
8. Execute each task surgically, with incremental verification.
9. Apply drift detection and the LLM prompt gate when necessary.
10. Use the retry ladder on failures.
11. Run the DEFINE Verify Gate as a blocking gate.
12. Run complementary checks configured in the project.
13. Ask about post-build external review when the case justifies it and the capability exists.
14. Generate the BUILD_REPORT using assets/BUILD_REPORT_TEMPLATE.md.
15. Validate the report with python scripts/validate_build_report.py <BUILD_REPORT.md>.
16. Close a complete build only with Execute o **SDD Handoff by RDD**.

Read references/build-protocol.md at the start of execution. Read references/execution-modes.md when selecting the mode. Use assets/PROGRESS_TEMPLATE.md if the user chooses Ralph. Use assets/WORKER_BRIEF_TEMPLATE.md if the user chooses Briefs. Read references/verify-gate.md before the final gate. Read references/llm-prompt-gate.md only when there is a sign of LLM/prompt runtime. Read references/retry-and-advisor.md when there is repeated failure or formal external review.

Required inputs

Require:

• BRAINSTORM_{FEATURE}.md;
• DEFINE_{FEATURE}.md;
• DESIGN_{FEATURE}.md;
• writable project/code corresponding to the feature.

Read the three documents in full before editing code.

If the project is not accessible, ask the user to provide/connect it. Do not fake a complete Build only from the specification files.

Optional inputs:

• UX_REVIEW_{FEATURE}.md;
• project guidance (README, guidance, conventions, config);
• sdd.config.yaml;
• real lint/test/typecheck/build commands;
• agent/subagent tools;
• external review tool;
• human receipt from manual-ux.

Authority hierarchy

For behavior and acceptance:

1. most recent explicit user response;
2. DEFINE;
3. DESIGN;
4. Brainstorm.

For technical implementation:

1. DESIGN;
2. real project code and patterns;
3. DEFINE;
4. Brainstorm.

Use Brainstorm as protection against intent drift and against reintroduction of items cut by YAGNI.

Never silently change a requirement, architecture, or contract to “make it pass.” If the implementation requires a specification change, stop the affected task and ask the user.

1. Load and cross-reference context

Extract from Brainstorm:

• original intent;
• chosen approach;
• rejected alternatives;
• YAGNI;
• limitations and dependencies.

Extract from DEFINE:

• MUST/SHOULD/COULD;
• Success Criteria;
• Acceptance Tests;
• Out of Scope;
• Constraints;
• Verify Gate;
• LLM Prompts: true|false.

Extract from DESIGN:

• architecture;
• components;
• Key Decisions;
• File Manifest;
• Code Patterns;
• LLM Prompt Inventory when applicable;
• Data Flow;
• Integration Points;
• Testing Strategy;
• Error Handling;
• Configuration;
• Security;
• Observability;
• Requirements Traceability.

If LLM Prompts: true in DEFINE and DESIGN does not have ## LLM Prompts, stop and request a Design correction. If LLM Prompts: false and DESIGN has a prompt inventory, stop and resolve the divergence. If the File Manifest is absent/incomplete, stop and correct the Design before implementing.

2. Inspect the project

Before any writing:

• locate the project root;
• read relevant guidance/conventions;
• check version control status when available;
• identify the current branch when Git exists;
• read the files that will be modified;
• locate direct dependencies cited in the manifest;
• identify existing real validation commands;
• confirm that the DESIGN paths still correspond to the project.

If Git is available:

• do not work directly on the deployment/default branch when a feature branch policy exists;
• create or use an appropriate branch before editing;
• do not invent commits/SHAs.

If Git is not available:

• continue only if the project can be edited safely;
• record in the report that branch/commit attribution was not available.

3. Compile the Build plan

Convert the File Manifest into tasks.

For each task, record internally:

• manifest id;
• path;
• action;
• purpose;
• dependencies;
• relevant acceptance criteria;
• incremental verification command;
• security surface?;
• LLM prompt item?;
• owner/executor.

Sort by dependencies. Do not start a task with an incomplete dependency.

If there is a path collision between tasks, run them sequentially.

4. Select mode with the user

Read references/execution-modes.md.

Before the first change:

1. measure the case signals;
2. recommend a mode;
3. present the recommendation first and justify it with concrete signals;
4. ask the user to choose.

Modes:

• default: sequential loop in the current context;
• ralph: a clean context per task, if the environment supports re-execution/subagents;
• briefs: experimental, stateless workers per wave, if the environment supports parallelism.

Never offer a mode that the active platform cannot execute. If ralph/briefs are not available, explain this in the question and recommend default.

Record in BUILD_REPORT:

• signals;
• recommendation;
• user decision;
• platform unavailabilities, if any.

5. Decide pre-build review

A formal external review is optional and depends on the available tool/capability.

Recommend yes when:

• new architecture with 3+ files;
• security surface;
• public/cached route;
• critical contract change.

Recommend no for a trivial adjustment of 1–2 files without a contract change.

The decision belongs to the user.

If the external capability does not exist, do not fake a review; record Not available.

If a formal review occurs, apply references/retry-and-advisor.md and record every note as APPLIED or REBUTTED.

6. Execute each task

Follow five invariants:

1. Assumption becomes a question: material ambiguity → ask.
2. Simplicity: nothing beyond what the manifest requires.
3. Surgical change: do not refactor adjacent code without need.
4. Criterion before code: know how to verify before writing.
5. Evidence: do not declare success without running the verification.

For each item:

1. re-read the minimum necessary context;
2. run drift detection;
3. run prompt gate if applicable;
4. create/modify/delete only the planned path;
5. preserve existing style and abstractions;
6. run incremental verification;
7. capture command, exit code and relevant output;
8. mark task complete only with evidence.

Do not leave TODO/FIXME as a substitute for a requirement.

7. Drift detection

Run before each item.

Ask:

• does the path or content introduce an uninventoried runtime prompt/LLM?
• does the implementation require an unforeseen file?
• does the necessary code change an architectural decision?
• does a requirement outside of scope appear?
• is an item removed by YAGNI being reintroduced?
• does a real project contract contradict the DESIGN?

If there is drift:

• stop the affected task;
• explain the divergence;
• offer options to the user;
• update the specification first when the change is material;
• record the event in BUILD_REPORT.

Never silently "accommodate" drift in the code.

8. LLM prompt gate

Read references/llm-prompt-gate.md when:

• LLM Prompts: true; or
• drift detection finds runtime prompt/LLM.

Do not invent provider, model, final prompt, or output schema that the Design should have already settled.

If the DESIGN requires a prompt engineering skill or loop-specification and it is not available:

• do not improvise the prompt;
• ask/record the dependency;
• block only the affected LLM items.

9. Retry ladder

On verification failure of a task, use references/retry-and-advisor.md:

• first failure: fix in the same context if it is a local/trivial error;
• second failure: rerun as a fresh task, without carrying over the previous hypothesis, using only the criterion that failed + error + necessary inputs;
• third failure: stop and record a blocker; do not work around the criterion.

If the platform does not support fresh rerun:

• simulate the FIX brief with minimal context;
• declare the limitation;
• do not pretend that a new context was created.

10. Verify incrementally

Use the real command most specific to the task, for example:

• corresponding unit test;
• module typecheck;
• file lint;
• import/compile check;
• local smoke.

Do not invent a command. If no command exists, derive an observable method only when supported by the project/Design; otherwise ask.

Record the result per task.

11. Run blocking Verify Gate

Read references/verify-gate.md.

The DEFINE Verify Gate is the authority.

Prefer the project runner (scripts/verify-gate.sh <DEFINE>) when it exists and matches the protocol. Otherwise, run the cmd of the gate only if it is a real, safe, and available command.

Interpret:

• 0: green → proceed;
• 2: red → Build cannot be completed; fix the code and repeat;
• 3: inconclusive → resolve tool/infra; do not mark green;
• 4: manual-ux → show checklist and wait for human receipt;
• 5: pending clarification → return to the user/spec; do not treat as a bug;
• 64: missing/malformed gate → invalid DEFINE.

Never declare success with 2, 3, 5 or 64. With 4, require in the report: who validated, date and result.

12. Complementary checks

After the gate, run when configured:

• lint;
• typecheck;
• relevant test suite;
• build/compile;
• smoke not covered by the gate.

These checks complement; they do not replace the Verify Gate.

If a complementary check fails, the Build remains incomplete until resolution or an explicit blocker.

13. Post-build review

When an external tool is available, recommend a post-build review if:

• security was changed;
• a public/cached route was changed;
• cross-file logic is subtle;
• ralph/briefs mode was used.

Do not recommend for a trivial fix.

If there are findings:

• verify HIGH/MED in the code before accepting;
• record each note as APPLIED/REBUTTED;
• after a HIGH is applied, repeat the Verify Gate.

14. Generate BUILD_REPORT

Use assets/BUILD_REPORT_TEMPLATE.md as the sole structural source of the report.

The report must be based on executed evidence, not estimates presented as facts.

Include:

• metadata and sources;
• Mode Selection;
• summary;
• task execution;
• files created/modified/deleted;
• prompts generated/refactored when applicable;
• drift;
• Verification Results;
• Verify Gate receipt;
• Acceptance Test Verification;
• Advisor Ledger when there was a review;
• issues/deviations/blockers;
• Final Status.

If the Build is blocked:

• use Status: Blocked;
• do not insert the Release handoff as if it were complete;
• indicate the action needed to unblock.

If complete:

• use Status: Complete;
• Final Status COMPLETE;
• insert the standard final section.

15. Validate BUILD_REPORT

Run:

python scripts/validate_build_report.py <caminho-do-BUILD_REPORT.md>

The script validates the report's structure and basic consistency.

Fix failures before delivering.

16. Save outputs

Code:

• in the File Manifest paths.

Report:

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 from the five phases sit side by side, without subfolders.

• save as sdd/BUILD_REPORT_{FEATURE}.md;
• when the project already uses .claude/sdd/ (including with reports/), follow the existing structure.

Do not overwrite a historical artifact without informing the user.

Completion quality gate

Before declaring Build complete:

• Brainstorm read.
• DEFINE read.
• DESIGN read.
• Real project accessible and changed.
• Mode chosen by the user and recorded.
• All File Manifest items handled.
• No changes outside the manifest without an explicit decision.
• Drift recorded.
• Incremental verification executed with evidence.
• Retry ladder respected.
• LLM Prompts=true has a receipt for each inventory item.
• Security items were not delegated to a cheap worker.
• Verify Gate is in 0, or 4 with human receipt.
• Applicable complementary checks pass.
• Acceptance Tests have evidence.
• Advisor findings, when they exist, have APPLIED/REBUTTED.
• There is no TODO/FIXME used as a pending implementation.
• BUILD_REPORT was generated by the asset.
• validate_build_report.py passes.
• Complete Next Step contains only Execute o **SDD Handoff by RDD**.

Complete Build handoff

The last section of the complete BUILD_REPORT must be exactly:

## Next Step

Execute o **SDD Handoff by RDD**.

Do not add a slash command, path, upload instruction, mention of GPT/Skill, or parallel task after this text.

---

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