ahgraber/sdd-propose

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?

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
• 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.

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, Scope (in/out), Approach
• [ ] 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
• [ ] 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

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