SDD TechSpec
Create or revise the sole human technical contract at tasks/prd-<slug>/techspec.md from the
approved PRD, applicability-resolved stories, and current mapped codebase evidence, with stable
architecture (DEC-NNN, RISK-NNN) and test (TU/TI/E2E-NNN) traceability, stopping at an
explicit human gate.
Upstream gates
- The PRD must have
human_approval: APPROVED, lifecycle.status: APPROVED, and a matching
human event in verified; required stories must satisfy the same conditions, or carry an
approved NOT_APPLICABLE disposition with a non-empty justification and its human event.
- Stop if upstream state is missing, pending, rejected, stale, contradictory, or lacks the human
event. Artifact existence never implies approval.
- Consume only the mapped context relevant to the change (
project.md, stack.md,
codebase.json) as observed evidence, never as prior architecture decisions; missing or stale
context blocks unsupported design claims.
- The configured OKF actor identifier and an ISO 8601 timestamp with explicit UTC offset.
Procedure
- Run
scripts/sdd_language.py <repo-root> and use the persisted language for every human-facing
sentence; on not_initialized, stop and return next_action: run_init (rules: references/language.md).
- Resolve the bundle and validate every upstream field and human event before designing. Read
an existing TechSpec before revising it and preserve identifiers and human-authored content.
- Inventory affected components and define producer/consumer boundaries, interfaces, failures,
recovery, and compatibility, reusing evidenced repository conventions unless a recorded
decision justifies a departure.
- Record decisions as stable
DEC-NNN and risks as stable RISK-NNN entries, linked to
applicable RF, US, and SC identifiers without changing upstream product scope.
- Fill the data section only when persistence changes and the API section only when an API
changes; otherwise record
NOT_APPLICABLE with a concrete justification.
- Define stable
TU-NNN, TI-NNN, and E2E-NNN cases linked to approved CA-NNN; consider
every test level and justify NOT_APPLICABLE levels instead of omitting them.
- Read
templates/techspec.md and render it as an OKF v0.2 TECHSPEC: keep its frontmatter keys
and section headings exactly (translate prose only), list only consumed sources; a new or
revised artifact starts at DRAFT with human_approval: PENDING and no invented event. Never
write a TechSpec from memory without the template.
- Write only
tasks/prd-<slug>/techspec.md; never alter the PRD, stories, acceptance criteria,
mapped context, or product scope. A needed product change goes back to its upstream gate.
- Present the exact draft reference, unresolved decisions, risks, and trace summary for human
review. Approval of this exact document sets
APPROVED on both fields and appends the human
event; rejection sets both to REJECTED with its event. Upstream staleness blocks task
generation.
Read when
references/specification.md — writing a new TechSpec, filling the conditional data or API
sections, or an architecture or traceability question is not answered above.
references/workflow.md ("Human-contract lifecycle vocabulary") — recording a decision.
references/okf.md — a frontmatter question the template does not answer.
Output
Return the path, slug, consumed sources, generated actor and timestamp, lifecycle status, human
approval value, exact draft reference, trace summary, unresolved decisions, risks, and the next
permitted stage; do not duplicate the TechSpec body. When the gate is not approved, state that
task generation remains blocked.
Safety: Do not commit, push, or publish. Do not read or expose .env, credentials, tokens, private keys, certificates, or fleet environment files. Full contract: references/safety.md.
1---2name: sdd-techspec3description: >4 Create or revise the SDD Composy technical specification5 (tasks/prd-SLUG/techspec.md) from the approved PRD, resolved stories, and mapped6 codebase, with DEC/RISK and TU/TI/E2E traceability and a human gate. Use when the7 product contracts are approved and architecture is needed — 'criar a spec8 técnica', 'techspec do prd-SLUG', 'design the solution for…'. Do NOT use to9 change product scope, before PRD and stories approval, or for design notes outside10 SDD.11metadata:12 source: https://skillmd.com/skills/pwdev-solucoes/sdd-techspec13 version: 0.1.014---1516# SDD TechSpec1718Create or revise the sole human technical contract at `tasks/prd-<slug>/techspec.md` from the19approved PRD, applicability-resolved stories, and current mapped codebase evidence, with stable20architecture (`DEC-NNN`, `RISK-NNN`) and test (`TU/TI/E2E-NNN`) traceability, stopping at an21explicit human gate.2223## Upstream gates2425- The PRD must have `human_approval: APPROVED`, `lifecycle.status: APPROVED`, and a matching26 human event in `verified`; required stories must satisfy the same conditions, or carry an27 approved `NOT_APPLICABLE` disposition with a non-empty justification and its human event.28- Stop if upstream state is missing, pending, rejected, stale, contradictory, or lacks the human29 event. Artifact existence never implies approval.30- Consume only the mapped context relevant to the change (`project.md`, `stack.md`,31 `codebase.json`) as observed evidence, never as prior architecture decisions; missing or stale32 context blocks unsupported design claims.33- The configured OKF actor identifier and an ISO 8601 timestamp with explicit UTC offset.3435## Procedure36371. Run `scripts/sdd_language.py <repo-root>` and use the persisted language for every human-facing38 sentence; on `not_initialized`, stop and return `next_action: run_init` (rules: `references/language.md`).392. Resolve the bundle and validate every upstream field and human event before designing. Read40 an existing TechSpec before revising it and preserve identifiers and human-authored content.413. Inventory affected components and define producer/consumer boundaries, interfaces, failures,42 recovery, and compatibility, reusing evidenced repository conventions unless a recorded43 decision justifies a departure.444. Record decisions as stable `DEC-NNN` and risks as stable `RISK-NNN` entries, linked to45 applicable `RF`, `US`, and `SC` identifiers without changing upstream product scope.465. Fill the data section only when persistence changes and the API section only when an API47 changes; otherwise record `NOT_APPLICABLE` with a concrete justification.486. Define stable `TU-NNN`, `TI-NNN`, and `E2E-NNN` cases linked to approved `CA-NNN`; consider49 every test level and justify `NOT_APPLICABLE` levels instead of omitting them.507. Read `templates/techspec.md` and render it as an OKF v0.2 `TECHSPEC`: keep its frontmatter keys51 and section headings exactly (translate prose only), list only consumed sources; a new or52 revised artifact starts at `DRAFT` with `human_approval: PENDING` and no invented event. Never53 write a TechSpec from memory without the template.548. Write only `tasks/prd-<slug>/techspec.md`; never alter the PRD, stories, acceptance criteria,55 mapped context, or product scope. A needed product change goes back to its upstream gate.569. Present the exact draft reference, unresolved decisions, risks, and trace summary for human57 review. Approval of this exact document sets `APPROVED` on both fields and appends the human58 event; rejection sets both to `REJECTED` with its event. Upstream staleness blocks task59 generation.6061## Read when6263- `references/specification.md` — writing a new TechSpec, filling the conditional data or API64 sections, or an architecture or traceability question is not answered above.65- `references/workflow.md` ("Human-contract lifecycle vocabulary") — recording a decision.66- `references/okf.md` — a frontmatter question the template does not answer.6768## Output6970Return the path, slug, consumed sources, generated actor and timestamp, lifecycle status, human71approval value, exact draft reference, trace summary, unresolved decisions, risks, and the next72permitted stage; do not duplicate the TechSpec body. When the gate is not approved, state that73task generation remains blocked.7475Safety: Do not commit, push, or publish. Do not read or expose `.env`, credentials, tokens, private keys, certificates, or fleet environment files. Full contract: `references/safety.md`.