Skip to content

Prototype Decision-Log (pd-3)

Wave 1 of SPEC-135 — the capture core. Wires existing skills so the why behind prototype iterations is recorded and no longer drifts away from the PRD and user-manual. This is a recommendation, opt-in per step (Empfehlung, nicht Zwang) — apply it per iteration, skip it freely.

The problem it solves

During /vt-c-pd-3-prototype you make many small changes — layout tweaks, component swaps, token switches. Git records what changed, but the why is captured nowhere. At the next iteration you end up asking: "Warum hatte ich das damals so gemacht?" — and the PRD and user-manual quietly drift from the prototype as actually built.

The wired chain

Three existing skills, wired into the pd-3 loop. Nothing new is added — the two producer/consumer skills each gain a new opt-in mode, and pd-3-prototype gains the orchestration block that ties them together.

Skill Role in the chain
vt-c-session-journal Producer — pd-3 side-car mode collects rationale live into journal-pd3-<feature>.md
vt-c-pd-capture-decisions Consumer — prototype-iteration mode drafts one decision record per iteration
vt-c-pd-3-prototype Orchestrator — opt-in starts the side-car, manual signal triggers the capture

Maintenance: the <!-- decision-log-chain --> anchor above and the three load-bearing literals (side-car path, mode name, output pattern) are machine-checked by tests/spec-135/. That drift-guard reddens if a wired skill is renamed/removed or a literal drifts from the SKILL contracts — keep the anchor markers intact and the literals byte-identical when editing. The Downstream consumers backflow literals (below) are separately guarded by tests/spec-153/.

/vt-c-pd-3-prototype --feature NAME
        │
        │  (a) opt-in, at iteration start
        ▼
/vt-c-session-journal  ── pd-3 Iteration Side-Car Mode ──►  docs/vt-c-journal/pd3/journal-pd3-<feature>.md
        │                                                      (the WHY, captured live)
        │  ... make iteration changes (git records the WHAT) ...
        │
        │  (b) manual signal, at iteration end
        ▼
/vt-c-pd-capture-decisions ── pd-3 prototype-iteration mode ──►  docs/decisions/NNN-prototype-<feature>-iter-<N>.md
        (reads side-car + git-diff, drafts one record per iteration; you edit before commit)

Triggers (both opt-in / manual — Wave 1)

Step When Trigger Locked by
Start side-car Iteration start Opt-in — user chooses to start it; never auto-on decisions.md Decision 4
Capture decision Iteration end Manual signal — user invokes capture; no counter, no auto-fire decisions.md Decision 3
Granularity — One record per logical iteration — never per file-edit decisions.md Decision 2

The auto-on journal variant (gated by disable_pd3_journal: true) and an iteration-counter trigger are documented as future upgrades, deliberately not built in Wave 1 — "erstmal manuell zum Lernen".

Worked example

VisiMatch prototype, feature booking-flow, iteration 3:

  1. Start of iteration — you opt in: start /vt-c-session-journal in pd-3 side-car mode. Entries land in docs/vt-c-journal/pd3/journal-pd3-booking-flow.md.
  2. During work — you swap a p-table for a card grid and say "cards read better on mobile than a dense table here". The "after design decisions" trigger appends that rationale to the side-car.
  3. End of iteration — you manually run /vt-c-pd-capture-decisions in pd-3 prototype-iteration mode. It reads the side-car + the iteration git-diff and drafts:
docs/decisions/014-prototype-booking-flow-iter-3.md


---
id: DEC-014
iteration: 3
pd-phase: 3
evidence:
  - "docs/vt-c-journal/pd3/journal-pd3-booking-flow.md#decision-cards-vs-table"
rationale: >
  Replaced the dense booking table with a card grid — cards read better on mobile
  than a dense table for this flow.
linked-files:
  - "04-prototyp/src/app/features/booking-flow/booking-flow.component.html"
tags: [product-design, prototype, decision-log]
---
4. You edit the draft if needed, then commit. Next iteration, the why is right there.

Skip case: if you never started the side-car, capture still works — it falls back to the git-diff alone and notes in rationale that no live journal was captured. Still one record per iteration.

Downstream consumers

The three skills in the chain table above are the capture core (journal → capture → prototype) — they record the why. A separate skill then consumes those decision records downstream. It is deliberately not a row in the counted <!-- decision-log-chain --> anchor: it reads the chain's output, it is not part of the core loop.

Skill Role Wired by
vt-c-user-manual-update Consumer — --draft mode drafts an early, provisional user-manual page from the latest decision entry SPEC-153 (US-3)

Draft user-manual backflow (US-3)

During pd-3, /vt-c-user-manual-update --draft turns the latest decision-log entry into an early, clearly-provisional user-manual page — so the PM sees what is being built before /vt-c-complete. It is additive: the finalized /vt-c-complete-driven manual path is unchanged, and drafts land on a separate surface that never overwrites a finalized page.

Four load-bearing literals keep this backflow wired — byte-identical to the vt-c-user-manual-update SKILL contract, and guarded by tests/spec-153/:

Literal Value Role
Mode flag --draft invocation
Source record docs/decisions/NNN-prototype-<feature>-iter-<N>.md connectedness with the SPEC-135 producer output
Draft surface docs/user-manual/drafts/<feature>.md separate from finalized features/ — never overwrites it
Provisional notice DRAFT — pd-3 iteration, expect changes. mandatory page-top banner

The draft page uses a thin template — What's being built / Why / Files touched, drawn only from the decision record's rationale, evidence, and linked-files. It fabricates no step-by-step "How it works" (no user stories exist at pd-3). Re-running --draft overwrites the single per-feature draft page (supersede, not append).

Future Waves (deferred follow-up specs)

These were intentionally out of scope for SPEC-135 Wave 1 (see decisions.md Decision 1) and become follow-up specs depends_on: [SPEC-135]. US-3 has since shipped as SPEC-153 (see Downstream consumers above); US-4 remains deferred.

Wave Story What it adds Target skill
3 US-4 PRD-delta mechanics — which decisions conflict with the PRD vt-c-pd-analyze-changes (or a new /vt-c-prd-delta)
  • Prototype Refinement Loop — the SPEC-134 sibling; visual/UX refinement helpers for the same pd-3 phase.
  • plugins/core-standards/skills/session-journal/SKILL.md → pd-3 Iteration Side-Car Mode
  • plugins/core-standards/skills/pd-capture-decisions/SKILL.md → pd-3 Prototype-Iteration Mode
  • plugins/core-standards/skills/pd-3-prototype/SKILL.md → Decision-Log & Journal Integration