# Spec Driven Propose

> Propose a new spec-driven change. Scaffolds proposal.md, specs/ delta files, design.md, tasks.md, and questions.md for a named change, populated with project context.

- Skill: `kw12121212/spec-driven-propose` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kw12121212/spec-driven-propose`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kw12121212/spec-driven-propose/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kw12121212 (https://skillmd.com/u/kw12121212)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kw12121212/spec-driven-propose

---


You are helping the user create a new spec-driven change proposal.

Do not ask follow-up questions or require confirmation during the proposal stage.
Derive the strongest proposal you can from the user request, project context, and
existing specs. Record any remaining ambiguity in `questions.md` for
`/spec-driven-apply` to surface before implementation begins.

## This Skill's Commands

If you cannot remember the exact command used by this skill, look it up here
before running anything. Do not guess.

```yaml
propose: node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
verify: node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
```

## Prerequisites

The `.spec-driven/` directory must exist at the **project root**. Before proceeding, verify:
```
ls .spec-driven/
```
If this fails, the project is not initialized. Run `/spec-driven-init` first.

## Steps

1. **Determine the change name** — use the user-provided kebab-case name when one is already available. Otherwise, derive a short kebab-case name from the request and the proposal scope yourself instead of stopping to ask for one.

2. **Read project context and existing specs** — read the following before generating anything:
   - `.spec-driven/config.yaml` — use `context` to inform content; treat `rules` as binding constraints; note any `fileMatch` entries that apply to files this change will touch
   - `.spec-driven/specs/INDEX.md` — identifies all existing spec files and their scope
   - Every spec file referenced in INDEX.md that this change is likely to touch — read the full content to understand existing requirements before writing MODIFIED or ADDED entries

3. **Scaffold the change** — run:
   ```
   node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
   ```
   This creates `.spec-driven/changes/<name>/` with seeded artifact templates.

4. **Fill proposal.md** — write a clear, concise proposal covering:
   - **What**: What the change does (observable behavior, not implementation)
   - **Why**: Motivation and context
   - **Scope**: What is in scope, what is explicitly out of scope
   - **Unchanged Behavior**: List existing behaviors that must not break — things adjacent to or potentially affected by this change. Leave blank if truly nothing is at risk.

5. **Fill design.md** — write the technical approach:
   - **Approach**: How you'll implement it at a high level
   - **Key Decisions**: Significant choices and their rationale
   - **Alternatives Considered**: What was ruled out and why

6. **Populate specs/ delta files** — look at the project's `.spec-driven/specs/` directory structure. For each spec file that this change touches, create a corresponding file under `.spec-driven/changes/<name>/specs/` mirroring the same relative path (e.g. `specs/auth/login.md` → `changes/<name>/specs/auth/login.md`). If the change introduces a new spec area, create the new relative path that should exist under `.spec-driven/specs/` after archive.

   Mirror the main spec path exactly. For example,
   `.spec-driven/specs/skills/planning.md` maps to
   `.spec-driven/changes/<name>/specs/skills/planning.md`.

   Use this canonical sample as the format target:

   ```markdown
   ---
   mapping:
     implementation:
       - path/to/implementation.ts
     tests:
       - test/path/to/test.ts
   ---

   ## ADDED Requirements

   ### Requirement: new-capability
   The system MUST provide <observable behavior>.

   #### Scenario: success
   - GIVEN <precondition>
   - WHEN <action>
   - THEN <result>

   ## MODIFIED Requirements

   ### Requirement: existing-capability
   Previously: The system MUST <old behavior>.
   The system MUST <new behavior>.

   ## REMOVED Requirements

   ### Requirement: old-capability
   Reason: This behavior is removed because <reason>.
   ```

   Each delta file uses ADDED/MODIFIED/REMOVED sections with the standard format:
   - YAML frontmatter with `mapping.implementation` and `mapping.tests` when
     related files are knowable from repository context
   - `### Requirement: <name>` headings and RFC 2119 keywords (MUST/SHOULD/MAY)
   - `#### Scenario:` blocks (GIVEN/WHEN/THEN) where helpful
   - **ADDED**: new requirements; **MODIFIED**: changed requirements (include `Previously:` note); **REMOVED**: removed requirements (include reason)
   - Omit sections that don't apply — do not leave empty sections
   - If this change has no observable spec impact, leave `changes/<name>/specs/` empty — do not create a prose-only delta file that breaks the delta spec format
   - Do not invent mapping paths when the related implementation or test files
      are not clear; leave mapping completion to `/spec-driven-apply`

7. **Fill tasks.md** — write a concrete implementation checklist using this canonical structure:

   ```markdown
   # Tasks: <change-name>

   ## Implementation
   - [ ] Describe the first atomic implementation task
   - [ ] Describe the second atomic implementation task

   ## Testing

   - [ ] Run `npm run lint` — lint or validation task
   - [ ] Run `npm test` — unit test task

   ## Verification
   - [ ] Verify implementation matches proposal scope
   ```

   Each task uses `- [ ]` checkboxes. Tasks should be independently completable.

   The `## Testing` section MUST satisfy these verification keyword requirements:
   - At least one task MUST contain a lint/validation keyword: `lint`, `validate`,
     `validation`, `typecheck`, `type-check`, or `build`
   - At least one task MUST contain a unit test keyword: `unit test` or `unit tests`
   - Both tasks MUST name an explicit runnable command in backticks or use a known
     runner (npm, pnpm, yarn, bun, node, bash, sh, pytest, jest, vitest, go, cargo,
     make, uv, poetry)
   - Paraphrasing these keywords (e.g. "run tests" instead of "run unit tests") will
     cause `verify` to fail

   If the relevant command cannot be determined confidently from repository context,
   add an open question to `questions.md` instead of guessing. Do NOT add an
   "Update specs" task — the specs/ directory contains the spec artifacts.

8. **Fill questions.md** — document any open questions or ambiguities:
   - For every unclear point (motivation, scope boundaries, technical approach, etc.), add an entry under `## Open`:
     ```
     - [ ] Q: <specific question>
       Context: <why this matters / what depends on the answer>
     ```
   - If everything is clear, leave `## Open` empty with a note: `<!-- No open questions -->`
   - Do NOT use `[NEEDS CLARIFICATION]` inline markers in any artifact — questions.md is the single place for all open questions

9. **Validate artifact format** — run:
   ```
   node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
   ```
   Treat this as a final structure and format check before presenting the proposal.
   - If it reports missing artifacts, malformed delta spec sections/headings, or unfilled placeholders you can safely fix, fix them immediately and rerun `verify`
   - If `verify` still reports a format or structure problem you cannot confidently repair, stop and report the issue to the user
   - If the only remaining error is open questions in `questions.md`, treat that as expected at proposal time and surface those questions clearly to the user

10. **Hand off** — show the user the five files and summarize the scope, key decisions, and any open questions. Do not require a confirmation checkpoint after writing the proposal. If `questions.md` has open questions, make clear that `/spec-driven-apply` will surface them as an implementation blocker and require explicit user resolution before coding starts, and mention `/spec-driven-modify` only as an optional revision path.

## Rules
- Do not implement anything — this is planning only
- Keep tasks atomic and verifiable
- Do not ask follow-up questions or require a proposal-stage confirmation checkpoint
- proposal.md describes *what and why*; design.md describes *how*; tasks.md is the checklist; questions.md is for open questions
- Document ambiguities in questions.md — never guess at unclear requirements, and never use `[NEEDS CLARIFICATION]` inline markers
- Do not add a post-proposal confirmation gate once the artifacts are written
- Open questions are allowed at proposal handoff time; leave them in `questions.md` for `/spec-driven-apply` to surface and block on
- Before finishing, rerun `verify` until all repairable format issues are fixed; if any non-question error remains, report it to the user
- Keep spec-code mappings in frontmatter, not in requirement prose