Use when creating a new change with all SDD artifacts — proposal, delta specs, design, and tasks. Triggers: "propose a change", "create a change for X", "I want to implement feature Y", "start a new change", "let's build X".
التثبيت
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Use when creating a new change with all SDD artifacts — proposal, delta specs, design, and tasks. Triggers: "propose a change", "create a change for X", "I want to implement feature Y", "start a new change", "let's build X".
SDD Propose
Create a change directory with all SDD artifacts.
Generates artifacts in dependency order: proposal → delta specs → design → tasks.
SPECS_ROOT is resolved by the sdd router before this skill runs.
Replace .specs/ with your project's actual specs root in all paths below.
Invocation Notice
Inform the user when this skill is being invoked by name: sdd-propose.
When to Use
Starting a new feature or behavioral change
User knows what they want to build and is ready to create a full change
No active change exists for this work
When Not to Use
Existing specs to convert from another tool — use sdd-translate
Deriving specs from code analysis — use sdd-derive
A change already exists and needs implementation — use sdd-apply
Need to think before speccing — use sdd-explore first
Process
Phase 1: Understand the Change
Ask the user:
What are we building?
— feature, bugfix, refactor, migration?
Change name — kebab-case identifier (e.g., user-auth-refresh, payment-retry)
Which capabilities does it touch?
— which existing specs are affected?
What user value does this deliver?
— capture as one or more user stories (As a {role}, I want {goal}, so that {value}); see references/sdd-change-formats.md § 1.1.
Check .specs/NORTH-STAR.md.
If it is missing, offer to draft a candidate product north star (a 2–4 sentence elevator pitch) from the README and existing specs for the user to ratify — the change's user stories ladder up to it.
Do not invent or finalize it silently; the north star is a product decision the user owns.
Read .specs/specs/ to understand existing baseline specs before generating deltas.
If .specs/specs/ is empty or does not exist, generate delta specs using only ADDED sections — all behavior is new.
If the user isn't sure about scope, offer sdd-explore first.
Phase 2: Generate proposal.md
Create .specs/changes/<name>/proposal.md.
See references/sdd-change-formats.md for the proposal format.
Write with the user's input:
Intent: the why — problem being solved
User Stories: the cross-cutting product value this change delivers, each laddering to NORTH-STAR.md (see references/sdd-change-formats.md § 1.1)
Scope: concrete in/out lists
Approach: high-level direction
Open Questions: unresolved decisions (if any)
Present to user and confirm before continuing.
Phase 3: Schema Baseline (if schemas configured)
If .specs/.sdd/schema-config.yaml exists:
Generate current schema snapshots and store in .specs/changes/<name>/schemas/before/.
Add a ## Schema Impact section to proposal.md describing expected schema changes — new endpoints, new or modified models, removed operations.
See references/sdd-schema.md § 2 for the format.
Create .specs/changes/<name>/schemas/expected.md with a prose description of the expected schema diff. sdd-verify uses this to cross-check actual changes at verify time.
If no schema config exists but .specs/schemas/ contains files, emit a visible warning:
WARNING: Found schema artifacts in .specs/schemas/ but no .specs/.sdd/schema-config.yaml. Schema snapshots will not be captured for this change. Run sdd-derive or create the config manually to enable schema tracking.
If no schema config exists and .specs/schemas/ is empty or absent, skip silently.
Phase 4: Generate Delta Specs
Create .specs/changes/<name>/specs/<capability>/spec.md for each affected capability.
Order capabilities by build dependency — contract-defining and foundation capabilities before consumers — and use the same order in proposal.md's Scope list, in design.md's Decisions and Architecture, and in tasks.md's task groups.
See references/sdd-change-formats.md § 4 for the principle and worked example.
Read references/sdd-spec-formats.md § 1 before writing any requirement.
It defines what a requirement is (contract shapes, authoring primitive, artifact separation) and is the primary guidance for this phase.
For each affected capability, ask: what new contract are we adding, changing, or removing?
State each requirement as a contract statement (guarantee, invariant, prohibition, precondition-consequence, or observable-state relationship — see § 1.1).
Lean toward universal claims where they apply.
For each universal SHALL claim, apply the partition heuristic in references/sdd-spec-formats.md § 1.6: ask whether the claim's input space splits along semantic lines the spec already names (lifecycle states, identity/equivalence, multi-source composition, derived-pair invariants).
If yes, write one scenario per partition; if no, a single scenario is fine.
Use spec vocabulary only — never partition along code paths or write-sites.
Mechanism thinking is expected here — algorithms, thresholds, strategies, data structures.
Park those thoughts in the proposal's ## Approach section as they surface; they formalize in Phase 5 (design.md).
Do not put mechanism into the spec itself.
Delta-format rules:
Read the existing baseline spec before writing the delta
Only include capabilities that actually change
Use only ADDED/MODIFIED/REMOVED/RENAMED sections that apply — omit empty sections
MODIFIED: copy the full baseline requirement (text + every still-applicable scenario), then edit in place — the block must be the complete post-change requirement, because sdd-sync replaces it wholesale (references/sdd-spec-formats.md § 4).
Note prior behavior in a > Previously: … line.
Add a Serves: {story-slug} backlink to each requirement, naming the proposal user stories it advances (M:N; references/sdd-change-formats.md § 1.1).
The backlink is delta-only and stripped at sync.
A requirement that serves no story is a signal of over-engineering — drop it, or add the story that justifies it.
Present specs to user and confirm before continuing.
Phase 5: Generate design.md
Create .specs/changes/<name>/design.md.
See references/sdd-change-formats.md for the design format.
Include:
Context: architectural constraints or existing decisions that affect this change
Decisions: each non-obvious choice with rationale and alternatives considered
Architecture: ASCII diagrams of component relationships, data flows
Risks: what could go wrong and mitigation
Verification Waivers (optional): any SHALL requirement that genuinely cannot have automated execution evidence — include the requirement name, the reason automation is infeasible, a manual evidence reference, and a Recorded date or commit SHA.
sdd-verify will otherwise flag any SHALL without runnable evidence as CRITICAL, and uses Recorded for provenance checking.
See references/sdd-change-formats.md § 2 for the format.
Only include sections with content — omit empty sections.
Present to user and confirm before continuing.
Phase 6: Generate tasks.md
Create .specs/changes/<name>/tasks.md.
See references/sdd-change-formats.md for the tasks format.
Rules:
Tasks are atomic — each can be done and tested independently
Order tasks and groups by build dependency per references/sdd-change-formats.md § 4 — each task must depend only on capabilities built by earlier tasks; never order alphabetically or by order of discussion
Group by component or phase, sequencing foundation groups before consumer groups
Every task is a concrete action, not an outcome
Every SHALL requirement must be paired with at least one task that produces runnable evidence — a named test (unit, integration, or e2e), a schema check, or a captured-output step.
If automated evidence is genuinely infeasible, the requirement must appear in design.md § Verification Waivers with a manual evidence reference.
sdd-verify enforces this rule.
For each SHALL, enumerate the foreseeable write-sites the design implies — every code path the design names that produces or modifies the contract-asserted value: canonical path plus any alternative paths in design.md (deduplication shortcuts, cache fast-paths, retry/fallback branches, idempotency early-returns, merge or composition steps).
Each foreseeable write-site needs its own paired evidence-producing test task — one test on the canonical path is not evidence for the shortcut, retry, or merge.
Write-sites that emerge later during implementation are handled by sdd-apply's write-site emergence rule and sdd-verify's write-site enumeration; covering the foreseeable ones here keeps verify from flagging them.
Phase 7: Validate
Change directory exists: .specs/changes/<name>/
proposal.md has Intent, User Stories, Scope (in/out), Approach
Each user story uses As a/I want/so that (value clause kept) and ladders to NORTH-STAR.md
Delta specs use only ADDED/MODIFIED/REMOVED/RENAMED sections (no baseline format)
Each requirement is a contract statement — a property about observable state that stands on its own without its scenarios (see references/sdd-spec-formats.md § 1)
Universal SHALL claims have partition coverage per the heuristic in references/sdd-spec-formats.md § 1.6 — when a positive signal fires, scenarios cover each partition
Mechanism (algorithms, thresholds, strategies, retry policies) appears in design.md or the proposal's Approach, not in spec text
Each delta requirement carries a Serves: backlink to a proposal story, or is deliberately left unserved and surfaced as such
design.md has at least one Decision with rationale
tasks.md has atomic tasks, and tasks/groups are ordered by build dependency per references/sdd-change-formats.md § 4 — no task depends on a capability not yet built by an earlier task
Affected capabilities appear in the same build-dependency order across proposal.md Scope, design.md, and tasks.md groups
Every SHALL requirement maps to at least one evidence-producing task (test, schema check, or captured output) OR appears in design.md § Verification Waivers with a manual evidence reference
Every foreseeable write-site implied by design.md (canonical path plus any alternative paths the design names — shortcuts, retries, merges) is paired with its own evidence-producing test task
No delta markers in .specs/specs/ (baseline specs untouched)
Output
.specs/changes/<name>/proposal.md
.specs/changes/<name>/specs/<capability>/spec.md per affected capability (delta format)
Not reading existing baseline specs before writing deltas
Writing baseline format in change specs (missing ADDED/MODIFIED/REMOVED markers)
Writing scenarios that carry the contract instead of illustrating it — if deleting the scenarios leaves the requirement untestable, the requirement text is under-specified (see references/sdd-spec-formats.md § 1.5)
Writing one scenario for a universal claim whose input space partitions along signals from references/sdd-spec-formats.md § 1.6 (lifecycle, identity, multi-source composition, derived-pair) — verify will flag this as partition-incomplete coverage
Partitioning along code paths or write-sites in scenarios — that is mechanism; partitions must use spec vocabulary only
Generating only canonical-path test tasks when design.md names alternative paths (shortcuts, retries, merges) — each foreseeable write-site needs its own paired test task, not just the canonical one
Creating tasks that are too coarse (one task = "implement auth" instead of atomic steps)
Ordering capabilities or task groups alphabetically or by order of discussion — ordering must follow build dependency per references/sdd-change-formats.md § 4 so the implementer never builds in anticipation of a missing capability
Generating all artifacts without pausing for user confirmation between phases
Using non-kebab-case change names
Dropping the "so that {value}" clause from a user story — the value clause is the scope ceiling that bounds implementation effort, not decoration
Writing a requirement that serves no user story (gold-plating) — every requirement should advance a story or be cut
