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

1. 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).
2. 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.
3. Inventory affected components and define producer/consumer boundaries, interfaces, failures, recovery, and compatibility, reusing evidenced repository conventions unless a recorded decision justifies a departure.
4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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.