sdd-propose git:20260617.5b2fd9aA

Immutable. This exact content is served forever at /api/v1/blob/ea5c1ab7a45a5df0.

---
name: sdd-propose
description: |-
  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:

1. **What are we building?**
   — feature, bugfix, refactor, migration?
2. **Change name** — kebab-case identifier (e.g., `user-auth-refresh`, `payment-retry`)
3. **Which capabilities does it touch?**
   — which existing specs are affected?
4. **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:

1. Generate current schema snapshots and store in `.specs/changes/<name>/schemas/before/`.
2. 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.
3. 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)
- `.specs/changes/<name>/design.md`
- `.specs/changes/<name>/tasks.md`

Summary: change name, capabilities affected, task count.

## Common Mistakes

- 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

## References

- `references/sdd-spec-formats.md` — baseline spec, delta spec, scenario formats
- `references/sdd-change-formats.md` — proposal, design, tasks formats
- `references/sdd-schema.md` — schema artifacts and lifecycle policy