Prospec New Story

---
name: prospec-new-story
description: "New Story - Create change requests by guiding User Story and acceptance criteria definition. 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` mode for guided step-by-step interview and confirmation
- 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.0.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] Read `prospec/CONSTITUTION.md` — prepare Constitution check
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)

To protect developer focus and maintain flow, this skill defaults to the **Draft-First** protocol:
- **Action: Draft (Default)**: When developer intent is clear or knowledge base (`prospec/index.md`, `specs/features/`) provides sufficient context, infer change name & scale, scaffold the change directory, and draft `proposal.md` with explicit `## Stated Assumptions`.
- **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 the completed `proposal.md` and concise Output Summary for single-pass human review.
- **Escape Hatch (`--interactive`)**: If the user passes `--interactive` (or explicitly requests step-by-step interview), fall back to guided interview mode.

## Core Workflow

> Note: Phase 3.5 (Complexity Assessment) is an intentional semantic insertion between Phase 3 and Phase 4, not a numbering bug.

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

- **Draft-First mode (default)**: Parse user prompt, match terms against `prospec/index.md` keywords, and examine existing feature specs under `prospec/specs/features/`. Infer Background (why), Role (who), Feature (what), Value (why it matters), and Constraints without interactive friction. If a key boundary is severely ambiguous, ask **one question at a time**.
- **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 (inferred in Draft-First, or collected via interview)
> - [ ] Known Constraints recorded (or explicitly noted as none)

### Phase 2: Derive Change Name

Derive a kebab-case name from requirements (verb-first, 2-4 words).
- **Draft-First mode (default)**: Automatically adopt the derived kebab-case name. If the user prompt provided a tracker reference/URL, extract it for `--issue <ref>`.
- **Interactive mode (`--interactive`)**: STOP. Ask the user to confirm the change name and, in the same question, which tracker item this change belongs to (**optional** — accept "none").

The tracker answer is free-form (a reference, a URL, another tracker's id) and is written by `prospec change story --issue` in Phase 3 — prospec judges nothing about its shape and calls no API (runs of whitespace, line breaks included, collapse to one space). No answer means the field is simply absent; never invent one, and never derive one 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 existing files, proceed to populate |

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

### Phase 3.5: Complexity Assessment (Scale)

Assess the change's complexity and determine scale (`quick` / `standard` / `full`). The scale drives process weight in subsequent SDD stages (ff/plan/review/verify/archive all 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. Read `prospec/specs/features/` on demand to check whether existing REQs cover the affected behavior.
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`)**: Present proposed scale WITH reasoning against criteria table. 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**: Context and problem statement
2. **User Stories**: INVEST stories with Priority (P1/P2/P3), 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.

> **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)

### 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** hand-edit metadata.yaml — scaffold, `scale`, and `quality_log` writes go through `prospec change story` / `change scale` / `change log` (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 |