Prospec New Story

---
name: prospec-new-story
description: "New Story - Create change requests by guiding User Story and acceptance criteria definition — the SDD entry station, not a generic issue or ticket writer. Triggers: new feature, requirement, user story, 新功能, 需求, 新增需求"
---
<!-- Generated by `prospec agent sync`. Do not edit — this file is regenerated on every sync. -->

# Prospec New Story Skill

## Activation

When triggered, briefly describe:
- Operating under the Draft-First protocol (Type III) by default — automatically inferring change name, scale, and scaffolding proposal.md
- Supporting `--interactive` interviews
- A proposal.md with `## Stated Assumptions` will be created in `.prospec/changes/`

## Language Policy

Write each generated document in the language the Constitution's Language Policy rule assigns to **its path** — change artifacts and their archived summaries in the project's artifact language, the trust zone (Knowledge base, Feature Specs, index) in English. One skill run may write both. Keep code, identifiers, technical terms, and git commit messages in English.
## CLI Prerequisite (required)

> The prospec CLI is a required file for this skill — its deterministic steps call `prospec`
> commands. Probe BEFORE any other step; there is no manual fallback.

1. Run `prospec --version` (Bash).
2. **Command not found / not executable** → STOP. Ask the user to install the prospec standalone
   executable — the one-click installer script from the project README (macOS/Linux `install.sh`,
   Windows `install.ps1`) or a release binary from GitHub Releases; prospec is NOT published to
   npm. Then re-run this skill.
3. **Version older than 2.3.0** → STOP. Report the installed vs required version
   and ask the user to upgrade, then re-run this skill.

Hand-executing a CLI-owned mutation is NEVER the fallback — that re-introduces the
nondeterministic serialization this contract exists to remove.

## Startup Loading

1. [STABLE] Run `prospec constitution show --station story` (Bash)
2. [STABLE] **MANDATORY** — Read [`references/proposal-format.md`](references/proposal-format.md) for proposal.md format specification
3. [DYNAMIC] Read [`references/metadata-format.md`](references/metadata-format.md) on demand for metadata.yaml FIELD SEMANTICS only — the file itself is CLI-written (`prospec change story` / `change scale` / `change log`), never hand-serialized
4. [DYNAMIC] Read `prospec/index.md` — identify related modules by matching proposal keywords against module `keywords` field
5. [DYNAMIC] Read `prospec/specs/features/` — check existing feature specs for context

## Entry Gate

> Blocking precondition check before this skill runs. If any item FAILs, stop and tell the user what is missing — do not proceed.

- Constitution exists and is non-empty (not just placeholder text).
- First stage of the lifecycle — no prior `quality_log` to read.

## Action Space Spectrum (Draft-First Protocol)

Default to **Draft-First**:
- **Action: Draft (Default)**: Infer name/scale from intent and Knowledge, then scaffold `proposal.md` with `## Stated Assumptions`; premise readiness is checked separately.
- **Action: Question**: ONLY when critical boundary conditions or goals are severely ambiguous and cannot be derived from code/specs, ask at most **one targeted question** at a time.
- **Action: Stay Silent**: Advisory checks (Phase 6 INVEST check, Phase 7 Knowledge check) are silently recorded to `metadata.yaml` `quality_log` rather than cluttering the conversation.
- **Action: Notify / Deliver**: Deliver proposal and Output Summary for review.
- **Escape Hatch (`--interactive`)**: If the user passes `--interactive` (or explicitly requests step-by-step interview), fall back to guided interview mode.

## Core Workflow

### Phase 1: Requirements Gathering (Draft-First vs Interactive)

- **Draft-First mode (default)**: Match the prompt to index keywords and relevant Feature Specs. Draft Role, Feature and Constraints. Ground Background/Value in traceable input or actual code investigation; clear intent alone is insufficient. Record original source/evidence; verification preserves `source: ai-proposed`. If a key boundary is severely ambiguous, ask **one question at a time**.
- Reproduction evidence (steps, expected/actual behavior, conclusion) can skip deep interviewing, not the Premise structure. Missing evidence stays pending → `prospec-explore`.
- **Interactive mode (`--interactive`)**: Guide the user through 3-4 focused questions to collect Background, Role, Feature, Value, and Constraints.

> **Phase 1 Gate** — proceed when:
> - [ ] Background, Role, Feature, and Value are captured with evidence or explicitly pending hypotheses
> - [ ] Known Constraints recorded (or explicitly noted as none)

### Phase 2: Derive Change Name

Reuse a supplied name; otherwise derive a kebab-case name (verb-first, 2-4 words).
- **Draft-First mode (default)**: Adopt the supplied or derived kebab-case name. If the user prompt provided a tracker reference/URL, extract it for `--issue <ref>`.
- **Interactive mode (`--interactive`)**: Reuse supplied decisions; only for missing input: STOP. Ask the user to confirm the change name and, in the same question, which tracker item this change belongs to (**optional** — accept "none").

Pass the free-form tracker reference via `prospec change story --issue` in Phase 3. Prospec judges nothing about its shape and calls no API; whitespace and line breaks collapse to one space. Omit absent references; never invent one or derive it from the branch name.

> **Phase 2 Gate** — proceed when:
> - [ ] A kebab-case change name is derived (all lowercase, hyphen-separated, verb-first)
> - [ ] Change name confirmed (auto-adopted in Draft-First, or confirmed in `--interactive`)
> - [ ] Tracker item captured if provided, or omitted

### Phase 3: Create Scaffolding

| Scenario | Action |
|----------|--------|
| Directory doesn't exist | Run `prospec change story [name] --description "<one-liner>" [--issue <ref>]` (Bash) — the CLI scaffolds `.prospec/changes/[name]/` with `metadata.yaml` (status: story) and `proposal.md`. Pass `--issue` only when a tracker item was provided in the prompt or Phase 2; the flag exists ONLY here, so a skipped answer cannot be amended later without rebuilding the change |
| Already exists | Read and update the same proposal; preserve unrelated sections, scenarios, scale and metadata status. Do not scaffold again. On return from explore, incorporate its premise-check without relabeling the original source |

> **Phase 3 Gate** — proceed when:
> - [ ] `prospec change story` ran (or the directory pre-existed) — `.prospec/changes/[name]/` has `metadata.yaml` + `proposal.md`
> - [ ] A new scaffold has `status: story`; re-entry preserves the existing status (CLI-written — never edit it by hand)

### Phase 3.5: Complexity Assessment (Scale)

For an existing change returning from explore, retain its recorded scale. For a new change, assess the change's complexity and determine scale (`quick` / `standard` / `full`). Subsequent stations read `metadata.scale`.

**Assessment criteria:**

| Criterion | quick | standard | full |
|-----------|-------|----------|------|
| Modules touched | 1 | 1-2 | 3+ |
| Spec-covered behavior (existing REQs in `prospec/specs/features/`) | none expected | may modify | adds/reshapes requirements |
| Nature | small fix, typo, config tweak | bounded feature work | architectural / cross-cutting |

**Hard veto:** if the change is expected to affect spec-covered behavior, do NOT propose `quick` — at least `standard`. (Prediction may still be wrong; the `prospec-archive` Entry Gate re-checks against the actual diff.)

**Flow:**
1. Check relevant Feature Specs for existing REQ coverage.
2. **Draft-First mode (default)**: Autonomously select scale based on criteria table; document reasoning in `## Stated Assumptions`; write via `prospec change scale quick|standard|full` (Bash) — never edit metadata.yaml by hand.
3. **Interactive mode (`--interactive`)**: Reuse supplied decisions; only for missing input: present scale with criteria-based reasoning per [`references/human-decision.md`](references/human-decision.md). STOP. Ask user to confirm or override. Write confirmed value via `prospec change scale quick|standard|full` (Bash) — never edit metadata.yaml by hand.

> **`scale: backfill` is not a new-story-time option.** It is a *promotion-time* scale set only by
> `prospec-promote-backfill` when formalizing a reviewed `backfill-draft.md` (documenting existing
> brownfield behavior) — never proposed here for new work. New work picks `quick`/`standard`/`full`.

**Quick slim proposal:** when `quick` is selected, Phase 4/5 produce a slim proposal — a single User Story with 2-3 WHEN/THEN scenarios plus an Independent Test; skip the FR/SC enumeration (FRs exist to map delta-spec REQs, which a quick change does not produce). Edge Cases, Related Modules, and Stated Assumptions stay. `standard`/`full` keep the full format.

> **Phase 3.5 Gate** — proceed when:
> - [ ] A scale (`quick`/`standard`/`full`) is determined with reasoning against the criteria table
> - [ ] Scale written to `metadata.yaml` via `prospec change scale` (and documented in `Stated Assumptions` if in Draft-First mode)

### Phase 4: Collect INVEST User Stories & Stated Assumptions

Define one or more INVEST User Stories (slim form when `scale: quick` — see Phase 3.5):

1. **Background and Premise**: Context and problem statement with the structured source, evidence, withdrawal condition and verification record from proposal-format
2. **User Stories**: INVEST stories with Priority (P0/P1/P2), Acceptance Scenarios (WHEN/THEN), and Independent Test
3. **Stated Assumptions**: 100% list of autonomous inferences in artifact language
4. **Edge Cases**: Boundary conditions and error scenarios
5. **Functional Requirements**: Traceable numbered requirements (`FR-001...`)
6. **Success Criteria**: Measurable verification criteria (`SC-001...`)
7. **Related Modules**: Cross-referenced modules from `index.md`
8. **Open Questions**: Ambiguities marked `NEEDS CLARIFICATION`

> **Phase 4 Gate** — proceed when:
> - [ ] >= 1 INVEST User Story defined, each with >= 2 WHEN/THEN acceptance scenarios
> - [ ] `## Stated Assumptions` explicitly captures all autonomous decisions
> - [ ] Related Modules cross-referenced against `prospec/index.md`
> - [ ] Edge Cases captured (FR/SC enumerated unless `scale: quick`)

### Phase 5: Write proposal.md

Follow `references/proposal-format.md` format with all sections from Phase 4. Keep every unconfirmed inference in Stated Assumptions, including inferred problem/value claims.

Read previous abandoned reasons from `change story`; author Premise `retry_difference` with changed evidence or approach before validation, for all scales. The CLI owns linkage.

Run `prospec validate proposal [name]` after editing. Blocked → `prospec-explore`, then resume on the same proposal. Ready/legacy/exempt may advance; pending is not a completed handoff. Applicability and structural-validation limits are defined in proposal-format.

Once substantive acceptance scenarios have been authored, **freeze** the baseline:
- If no baseline exists, run `prospec change story [name] --freeze-scenarios` (Bash) to snapshot scenarios into `metadata.yaml` `acceptance` baseline (revision 1, origin: story).
- A later scenario change must use the controlled amendment path: `prospec change story [name] --amend-scenarios --reason "<text>" --expected-digest <sha256>`. Never hand-edit `metadata.yaml`.

> **Phase 5 Gate** — proceed when:
> - [ ] `proposal.md` written following `references/proposal-format.md`
> - [ ] All Phase 4 sections present (including `## Stated Assumptions`, no empty Background/Why)
> - [ ] Premise validation admits the change (ready, legacy, or exempt); blocked returns to explore
> - [ ] Substantive acceptance scenarios frozen or retained unchanged in baseline via `prospec change story [name] --freeze-scenarios`

### Phase 6: Constitution Check (site-specific: INVEST)

Run an **advisory** INVEST self-check on the Story — only this station's site-specific rule (**User Stories Follow INVEST**), NOT a generic multi-principle scan (the every-principle audit is `prospec-verify` V3/5 only). Surface any INVEST concern as a note/WARN and record it silently via `prospec change log --skill prospec-new-story --result WARN --warning "<concern>"` (Bash); **do not hard-block** the Story on it. INVEST stays a Constitution `[MUST]`.
- **PASS**: the Story satisfies INVEST
- **WARN**: partially satisfies — record suggestions to `quality_log`, proceed

> **Phase 6 Gate** — proceed when:
> - [ ] An advisory INVEST self-check was run and any concern noted to `quality_log` (advisory — never blocks)

### Phase 7: Knowledge Quality Gate

Confirm Knowledge awareness in **one line**: ≥ 1 Related Module matched from `prospec/index.md` (by module keywords), and existing Feature Specs checked for overlap. Any gap → WARN, noted in the Open Questions section and logged to `quality_log` (non-blocking). (The full per-station Quality-Gate table lives only in `prospec-verify` — the SDD stations no longer each restate it.)

> **Phase 7 Gate** — proceed when:
> - [ ] the one-line Knowledge check is recorded PASS or WARN (WARNs noted in Open Questions)

### Phase 8: Summary + Next Steps

Save proposal.md. Present the completed proposal summary to the user for single-pass review.

## Next-Step Handoff

After the Output Summary, recommend the next step in the SDD workflow order
(`story → plan → tasks → implement → review → verify → knowledge-update → archive`, then periodic `learn`) — read
`metadata.yaml` status and `prospec/ai-knowledge/_status-lifecycle.md` (review and learn own no
status transition, so follow this order, not status alone). Provide the direct, actionable Skill
identity or CLI command for the next step (e.g. `prospec-plan`), allowing smooth continuation
without blocking on a separate confirmation turn. If the stage is terminal (`archived`), the linear
flow is complete — point to periodic `prospec-learn` rather than a workflow successor. If the result
does not advance (e.g. verify grade B/C/D), say so and point to the corrective step instead of
offering the next skill.

## Output Contract

> After running, self-assess and emit a concise Output Summary. Every Success Criterion must be objectively checkable (file existence / grep / test result / count) — no subjective adjectives.

### Success Criteria
- [ ] proposal.md has >= 1 INVEST User Story
- [ ] each Story has >= 2 WHEN/THEN acceptance scenarios
- [ ] Stated Assumptions section present and enumerates all autonomous inferences
- [ ] Constitution Check section present
- [ ] Related Modules cross-referenced against prospec/index.md (>= 1 when Knowledge exists)

### Failure Conditions
- proposal.md empty or missing Background/Why
- Constitution Check skipped

### Output Summary
Emit one line: `Met N/M | Unmet: <items> | Overall: PASS|WARN|FAIL | Next: <one-line>`

### Exit Gate (Constitution)

Verify the output against this skill's **site-specific** Constitution rule (**INVEST**) — not the full Constitution; the every-principle audit is `prospec-verify` V3/5 only. When the rule carries RFC-2119 severity, grade by weight — MUST→FAIL, SHOULD→WARN, MAY→informational (the grade vocabulary stays PASS/WARN/FAIL). A free-text Constitution falls back to judgment-based grading. Record each WARN/FAIL via `prospec change log --skill <station> --result WARN|FAIL --warning "<detail>"` (the CLI owns the `quality_log` serialization). Advisory — surface issues, do not hard-block.

## NEVER

- **NEVER** create non-kebab-case change names — all lowercase, hyphen-separated, verb-first
- **NEVER** hard-block a Story on the INVEST check here — it is **advisory** at new-story: record concerns to `quality_log` and proceed.
- **NEVER** write implementation details in Acceptance Criteria — ACs focus on user-observable outcomes
- **NEVER** create a Story with fewer than 2 acceptance scenarios (WHEN/THEN)
- **NEVER** include technical architecture or code in proposal.md — that belongs in plan.md
- **NEVER** advance to plan (or tasks for quick) without freezing substantive acceptance scenarios via `prospec change story [name] --freeze-scenarios` — un-frozen stories cannot enter planning or tasks
- **NEVER** hand-edit metadata.yaml — scaffold, `scale`, baseline freeze/amend (`--freeze-scenarios` / `--amend-scenarios`), and `quality_log` writes go through `prospec change` commands (lifecycle: `prospec/ai-knowledge/_status-lifecycle.md`)
- **NEVER** ask multiple questions at once when in Question mode — ask at most **one question at a time**
- **NEVER** omit autonomous inferences from `## Stated Assumptions` — 100% of inferred decisions must be explicit
- **NEVER** use generic "user" as the role — be specific (developer, project manager, system admin)
- **NEVER** propose `quick` for a change expected to affect spec-covered behavior
- **NEVER** use passive voice for confirmation wait points in interactive mode (e.g., "confirm before proceeding") — always use an active imperative ("STOP. Ask the user...").
- **NEVER** ignore `--interactive` when requested by the developer — always provide the interactive escape hatch

## Error Handling

| Scenario | Action |
|----------|--------|
| Scaffolding creation fails | Check if .prospec.yaml exists, prompt user to confirm project root |
| Constitution FAIL | Provide adjustment suggestions, or document exception reasoning |
| Module identification unclear | Suggest returning to `prospec-explore` or continue, deepen in Plan phase |