Sdlc Build

sdlc-build — Build Incrementally

Overview

One task. One commit. One question. This skill reads docs/sdlc/tasks.md, implements the next uncompleted task using TDD, commits atomically, then stops and asks the developer whether to continue.

Core principle: Never implement more than one task without explicit confirmation. Velocity is not the goal — correctness is.

Input: docs/sdlc/tasks.md (preferred) or a task described directly by the user. Output: Working code + passing tests + an atomic commit + a marked task.

---

Pre-condition: Project Documentation

Before doing anything else, check whether docs/project.md exists in the project root.

If `docs/project.md` does NOT exist:

STOP. Do not proceed with this skill.

Inform the developer:

"No project documentation found (docs/project.md is missing).

Run /init-docs first to generate the technical documentation for this project.

All SDLC skills require this file to operate with the correct project context."

If `docs/project.md` exists: Read it (and any linked docs referenced in its index) before proceeding. Use the project context to make all decisions in this skill relevant to the actual stack, patterns, and conventions of this project.

---

Context7 — Library Documentation

Before writing any code, check if the task involves a specific library or framework. Detect this from docs/project.md (Tech Stack section) or from the task description itself.

If a library is involved — do this before Step 1:

1. Use resolve-library-id with the library name (official name, e.g. "Angular" not "angular") and the task goal as the query 2. Use query-docs with the resolved ID and the specific behavior to implement 3. Use the fetched docs to confirm:

• The API signatures you will call in tests and implementation are current (not deprecated)
• The test framework idioms are correct for this library version
• No breaking changes affect the current task

This step is not optional when a library is detected. Stale API usage is a build failure waiting to happen. Fetch first, code second.

Skip only if: the task is pure business logic with no library-specific API calls, or uses only plain Node.js / browser built-ins.

---

Process (Rigid — do not skip steps)

Step 1 — Identify the Task

Check if docs/sdlc/tasks.md exists.

• If it exists: Find the first task marked [ ] (not [x]). Read its File, What, and Verify fields.
• If it does not exist: Ask the user to describe the task. Do not invent requirements.
• If the task has `[DECISION]`: Stop immediately. Present the decision to the developer and wait for an explicit choice before proceeding. Do not implement anything until the decision is made.

Polymorphic Family Check

After identifying the task, check: does the target class implement an interface or extend an abstract base class that already has other concrete implementations?

If yes — before writing any test or code:

1. Read the interface or abstract base — this is the contract that must be honoured without exception 2. Read all existing sibling implementations — identify:

• Constructor signature and dependency injection patterns used across the family
• Error handling conventions (exception types, result objects, error codes)
• Naming conventions for methods, parameters, and return types

3. The new implementation must be consistent with its siblings in contract and conventions, even when its internal logic is completely different

Why this is mandatory: An implementation that silently deviates from the family's conventions breaks substitutability. A PagamentoPix that throws InvalidOperationException where every other sibling throws DomainException is a bug waiting to be discovered in production.

Tasks that implement a member of a polymorphic family should carry a [POLYMORPHIC: IFoo] marker in tasks.md to make this check explicit and traceable.

---

Step 2 — Write the Test First (RED)

Before writing any implementation code:

1. Create or open the test file corresponding to the task's target file. 2. Write a test that describes the expected behavior from the task's Verify field. 3. Run the test — it must fail at this point. If it passes before implementation, the test is wrong or the behavior already exists. Investigate before continuing.

Do not write implementation code before seeing the test fail.

Polymorphic Implementation Test Rule

When the task implements a member of a polymorphic family, the test must:

1. Declare the subject using the interface type, not the concrete class:

   // Correct — tests via contract
   IFoo subject = new FooImpl(deps);

   // Wrong — bypasses the interface contract
   FooImpl subject = new FooImpl(deps);

2. Call only interface methods in the Act step — never call concrete-only public methods in the test body (those belong in unit tests specific to the concrete class, not in the contract test)

3. Assert two things in the same test:

• Contract assertion: the result satisfies the shape/type guaranteed by the interface
• Specific assertion: the result contains the behavior exclusive to this implementation

   // Example: PagamentoPix implementing IPagamento
   IPagamento subject = new PagamentoPix(pixGateway);

   var resultado = subject.Processar(pedido);           // called via interface

   Assert.Equal(StatusPagamento.Aprovado, resultado.Status);  // contract — every impl must return this
   Assert.NotNull(resultado.QrCode);                          // specific — only Pix returns a QR code

This structure proves both that the implementation honours the shared contract AND delivers its specific behaviour — in a single failing test before any code is written.

---

Step 3 — Implement the Minimum (GREEN)

Write the minimum code required to make the test pass:

• No speculative code
• No extra abstractions
• No features not covered by the current task

Run the tests again — all tests must pass before continuing.

---

Step 4 — Mark the Task Complete

In docs/sdlc/tasks.md, change the task's checkbox from [ ] to [x]:

- [x] T001: <title>

Do not modify any other task.

---

Step 5 — Atomic Commit

Create exactly one commit for this task using the format:

feat: <task title>

The commit must include:

• The implementation file(s)
• The test file(s)
• The updated docs/sdlc/tasks.md

Do not bundle multiple tasks into one commit.

---

Step 6 — Stop and Ask

After the commit, stop. Present a summary of what was done and ask:

"Task complete: <task title>. Continue to next task? (yes/no)"

Wait for an explicit answer. Do not proceed until the developer confirms.

---

Checklist (one per task)

The agent must complete every item before moving on:

• [ ] Checked if task involves a library — fetched docs via Context7 if so
• [ ] Checked for polymorphic family — read interface + all siblings if detected
• [ ] Read the task from docs/sdlc/tasks.md (or accepted from user)
• [ ] Checked for [DECISION] marker — stopped and resolved if present
• [ ] Wrote the test before any implementation (TDD)
• [ ] Confirmed the test fails before implementation (RED)
• [ ] Implemented the minimum code to pass the test
• [ ] Confirmed all tests pass (GREEN)
• [ ] Marked the task as [x] in docs/sdlc/tasks.md
• [ ] Created atomic commit: feat: <task title>
• [ ] Stopped and asked the developer whether to continue

---

Stop Rules (Critical)

Never chain tasks without confirmation. One task → one stop → one question.

---

Relationship to /test

This skill applies TDD per task (one test per behavior being implemented). For formal, exhaustive proof of a complete feature's behavior — including edge cases, failure modes, and acceptance criteria — use /test (sdlc-test) after the build is complete.

---

Common Mistakes

<!-- AGENT NOTES (ignored by agents): OpenCode: use Write/Edit tools for file changes; use Bash for git commit Claude Code: use Write/Edit tools; Bash(git add -A && git commit -m "feat: ...") Kiro: use file system tools for writes; terminal for git Cursor: save via editor; use integrated terminal for git commit -->