Prospec Promote Backfill

---
name: prospec-promote-backfill
description: "Promote Backfill - Formalize a reviewed backfill-draft.md into the backfill change scaffold (proposal.md + delta-spec.md + metadata.yaml with scale: backfill, status: implemented) so brownfield behavior can graduate through verify → archive. A light scale like quick — no hollow plan.md/tasks.md; the single, repeatable draft→scaffold step; never writes the trust zone. Triggers: promote backfill, formalize backfill, backfill to delta-spec, promote draft, 晉升回填, 正式化回填, 回填轉正, 提升草稿"
---
<!-- Generated by `prospec agent sync`. Do not edit — this file is regenerated on every sync. -->

# Prospec Promote Backfill Skill

## Activation

When triggered, briefly describe:
- That you'll formalize a **reviewed** `backfill-draft.md` into the backfill change scaffold — `proposal.md` + `delta-spec.md` + `metadata.yaml` — so it can graduate through `prospec-verify` (backfill mode) → `prospec-archive`
- That this is the single, repeatable draft→scaffold step — it replaces ad-hoc hand conversion and is where the `scale: backfill` marker is set
- That `backfill` is a **light scale** like `quick`: it records *existing* behavior, so there is **no `plan.md` and no `tasks.md`** (nothing to plan, no work to schedule). The scaffold enters the lifecycle directly at `status: implemented`
- That it **never** writes the trust zone (`prospec/specs/features/`) — `prospec archive` (the CLI) stays the sole writer

## 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] **MANDATORY** — Load the format references this scaffold must match: `references/proposal-format.md`, `references/delta-spec-format.md`
2. [DYNAMIC] Read `.prospec/changes/[name]/backfill-draft.md` — the reviewed source draft to formalize
3. [DYNAMIC] Read `prospec/index.md` + `prospec/ai-knowledge/module-map.yaml` — map the draft's traced `file:line` to module names for `related_modules`
4. [DYNAMIC] Read `prospec/specs/features/` — align the candidate feature slug to an existing Feature Spec when one fits

## Entry Gate

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

- `.prospec/changes/[name]/backfill-draft.md` exists and is route-compatible (`**Feature:**`/`**Story:**` headers + User Story + Acceptance Criteria candidates).
- The draft has **no unresolved `[NEEDS CLARIFICATION]`** — promotion is a record of *confirmed* behavior; an unresolved marker means the user-review gate (`prospec-backfill-spec` Phase 5) is incomplete. FAIL → send the user back to resolve it; never carry it into the scaffold.
- The candidate feature slug is confirmed and `prospec validate slug <candidate>` (Bash) PASSes.

## Core Workflow

> The draft is already fidelity-checked (every AC backed by `file:line`, no fabricated intent, no uncounted facts — `prospec-backfill-spec` guarantees this). Promotion **reshapes** that material into the forward-path artifacts; it does not re-derive behavior and **adds no claim the draft did not already ground**.

### Phase 1: Validate and route the draft

Confirm the Entry Gate held. Cluster the draft's stories under the confirmed feature slug; align to an existing `prospec/specs/features/{slug}.md` when one fits. Map each story's traced `file:line` to module names via `prospec/ai-knowledge/module-map.yaml` — this set becomes `related_modules` (archive's backfill module-derivation source; it must be non-empty).

> **Phase 1 Gate** — proceed when:
> - [ ] Entry Gate satisfied; feature slug confirmed + `prospec validate slug` PASSes
> - [ ] every story's traced `file:line` mapped to ≥1 module → `related_modules` set (non-empty)

### Phase 2: Scaffold + proposal.md

Run `prospec change story [slug] --description "<one-liner>" --related-module <m>` (Bash; repeat
`--related-module` per traced module from Phase 1 — explicit modules override the name-keyword
auto-match, which knows nothing about the traced code). The CLI scaffolds the change directory,
metadata.yaml (status: story), and a proposal.md skeleton.

Then overwrite `proposal.md` per `references/proposal-format.md`: each draft story → an INVEST User Story (As a / I want / So that + WHEN/THEN Acceptance Scenarios from the draft's AC). Carry the draft's *So that* / role verbatim — they were confirmed at review. Edge Cases and FR/SC trace to the draft's behaviors. (`prospec-archive` Phase 3.5 graduates the Feature Spec from this proposal + the delta-spec below.)

### Phase 3: delta-spec.md

Write `delta-spec.md` per `references/delta-spec-format.md`: each draft AC candidate → a REQ under `## ADDED` with `**Feature:**` (the confirmed slug) and `**Story:**` routing. Keep the feature-first REQ-id (`REQ-{FEATURE-SLUG}-NNN`) — archive routes by `**Feature:**` and derives modules from `related_modules`/feature-map, so the REQ-id need not be module-based. Every AC keeps its `file:line` citation so `prospec-verify` can re-confirm fidelity.

### Phase 4: metadata.yaml (CLI-written)

Run `prospec change scale backfill` then `prospec change status implemented` (Bash) — brownfield
code pre-exists, so `implemented` is backfill's lifecycle entry point (a legal forward jump; no
earlier transition runs). `name`/`related_modules`/`description` were already CLI-written at Phase 2.
Never hand-serialize metadata.yaml. Finally run `prospec validate promote-scaffold --change [name]`
(Bash) — the complete machine verdict for this scaffold: draft + proposal present, **no
plan.md/tasks.md**, `scale: backfill` + `status: implemented`, and no uncommitted trust-zone writes.

> **No `plan.md` and no `tasks.md`.** `prospec validate promote-scaffold` refuses a scaffold that carries them — the absence is intentional, not laziness: backfill records existing code, so a `plan.md`/`tasks.md` produced only to satisfy a forward-path gate would be hollow make-work.

> **Phase 4 Gate** — proceed when:
> - [ ] `prospec validate promote-scaffold` reports PASS (scale/status/artifact set/trust-zone all machine-verified)
> - [ ] nothing written under `prospec/specs/features/`

### Phase 5: Handoff

Present the produced scaffold and route the user to `prospec-verify` — under `scale: backfill`, verify grades **spec-fidelity** (every REQ's `file:line` must resolve) and treats pre-existing code-quality gaps as informational tech debt, so a faithful draft reaches grade S/A → `verified` → archivable.

## Output Contract

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

### Success Criteria
- [ ] `proposal.md` + `delta-spec.md` written under `.prospec/changes/[name]/`; `prospec validate promote-scaffold` PASSes (no `plan.md`/`tasks.md`, `scale: backfill`, `status: implemented`, non-empty `related_modules`)
- [ ] no `[NEEDS CLARIFICATION]` in any produced artifact (grep)
- [ ] nothing written under `prospec/specs/features/` (trust zone untouched)

### Failure Conditions
- produced a scaffold carrying an unresolved `[NEEDS CLARIFICATION]`
- wrote a hollow `plan.md`/`tasks.md`, or anything under `prospec/specs/features/`
- `related_modules` empty, or a REQ AC stripped of its `file:line` citation

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

## NEVER

- **NEVER** write under `prospec/specs/features/` — promotion only stages the change scaffold under `.prospec/changes/[name]/`; `prospec archive` (the CLI) stays the sole writer of the trust zone
- **NEVER** carry an unresolved `[NEEDS CLARIFICATION]` into the scaffold — a backfill change records *confirmed* behavior; send the user back to the draft's review gate instead
- **NEVER** add a behavior, count, or cross-module flow the draft did not already ground in `file:line` — promotion reshapes the fidelity-checked draft, it does not re-extract or fabricate
- **NEVER** leave `related_modules` empty — archive's backfill knowledge-sync derives affected modules from it; an empty set would silently pass the gate
- **NEVER** strip a REQ's `file:line` citation — `prospec-verify` needs it to re-confirm spec-fidelity
- **NEVER** set `scale` to anything but `backfill`, or `status` to anything but `implemented` — promotion is the backfill lifecycle entry; other values misroute verify/archive

## Error Handling

| Scenario | Action |
|----------|--------|
| `backfill-draft.md` missing | Guide user to run `prospec-backfill-spec` first (it stages the draft) |
| Unresolved `[NEEDS CLARIFICATION]` in the draft | STOP; send the user back to `prospec-backfill-spec` Phase 5 to resolve before promoting |
| Candidate feature slug fails `prospec validate slug` | Reject; ask the user to confirm a safe slug |
| No module resolves from the draft's `file:line` | STOP; `related_modules` cannot be empty — the draft's tracing is incomplete |

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