Skip to content

vt-d-user-manual-update

Update user manual pages after a spec is completed. Reads the spec and implementation details to regenerate the corresponding feature page with actual behavior, edge cases, and technical notes. Marks auto-generated sections as DRAFT for human review. Additive --draft mode (SPEC-153) drafts an early, provisional manual page during pd-3 from the SPEC-135 decision-log, to a separate drafts surface.

Plugin: vt-product-dev
Category: Other
Command: /vt-d-user-manual-update

/vt-d-user-manual-update — Update Manual After Spec Completion

Keep the user manual in sync with the actual implementation by auto-generating draft updates after each spec is completed.

Called by /vt-d-complete (Step 5.5) or manually when a feature page needs refreshing.

Two modes. The default (Steps 1–10 below) regenerates a finalized feature page from a completed spec after /vt-d-complete. The additive --draft mode (see pd-3 Draft Mode below, SPEC-153) instead drafts an early, provisional page during pd-3 from the SPEC-135 decision-log — to a separate drafts/ surface, never touching the finalized path.

When to Use

  • After /vt-d-complete marks a spec as done (automatic prompt)
  • When a feature page is outdated and needs refreshing from the spec
  • When a new feature was implemented without a corresponding manual page

Prerequisites

  • docs/user-manual/ exists (generated by /vt-d-user-manual-generate)
  • A completed spec exists in specs/[N]-feature/spec.md

Invocation

/vt-d-user-manual-update                     # Update finalized page for active spec (from branch)
/vt-d-user-manual-update SPEC-003            # Update finalized page for a specific spec
/vt-d-user-manual-update --draft             # pd-3 mode: draft a provisional page from the decision-log

--draft runs the pd-3 Draft Mode below instead of Steps 1–10. It never requires a completed spec or an existing manual scaffold, and never writes into the finalized features/ surface.

Execution

Step 1: Identify Active Spec

  1. If argument provided (e.g., SPEC-003), use that spec ID.
  2. Otherwise derive from branch: feature/spec-NNN-* → SPEC-NNN.
  3. Read specs/[N]-feature/spec.md for the spec content.
  4. Read specs/[N]-feature/state.yaml for status and docs_page field.

If spec not found, display error and exit.

Step 2: Locate Target Manual Page

Priority order for finding the target page:

  1. docs_page in state.yaml (preferred) — use the explicit mapping
  2. Feature name matching — slugify the spec title and look for docs/user-manual/docs/features/[slug].md
  3. Ask the user — if no match found, present the list of existing feature pages and ask which one corresponds to this spec

If docs/user-manual/mkdocs.yml does not exist: 

No user manual found at docs/user-manual/.
Run /vt-d-user-manual-generate first to create the manual from the PRD.
Exit.

Step 3: Read Implementation Context

Gather all available context about what was actually built:

  1. Spec content — specs/[N]-feature/spec.md (user stories, acceptance criteria, edge cases)
  2. Plan — specs/[N]-feature/plan.md (if exists — architecture decisions, technical approach)
  3. Tasks — specs/[N]-feature/tasks.md (if exists — what was actually implemented)
  4. Branch commits — git log main..HEAD --oneline (summary of implementation changes)
  5. Changed files — git diff --name-only main..HEAD (which code files were touched)

Step 4: Read Existing Manual Page

If the target page exists, read it fully. Identify: - Which sections already have content from the PRD-based generation - Which sections have <!-- TODO --> placeholders - Which sections have <!-- DRAFT: review needed --> markers from a previous update

If the target page does NOT exist (new feature not in original PRD): - Display: "No existing page for [feature]. Creating new page." - Use the feature page template from /vt-d-user-manual-generate Step 7 as the base.

Step 5: Generate Updated Page

Regenerate the feature page incorporating implementation details. Use the same template structure as /vt-d-user-manual-generate Step 7 but with enriched content:

# [Feature Name]

## Overview

[Updated description — refine from spec Goal section with implementation reality]

## Who uses this

[From spec user stories — which personas/roles interact with this feature]

## How it works

### [Step 1 title]

[Step-by-step instructions refined from acceptance criteria and actual implementation]
[Convert Given/When/Then to user-facing instructions]

**Expected result:** [What the user should see — derived from acceptance criteria "Then" clauses]

### [Step 2 title]
...

## States and edge cases

| State | What happens |
|-------|-------------|
| Normal flow | [From acceptance criteria — happy path] |
| [Edge case from spec] | [Handling derived from spec edge cases section] |
| [Error state from implementation] | [Recovery path from plan/tasks] |
| Empty state | [What happens with no data] |

<!-- DRAFT: review needed — edge cases generated from spec, verify against actual implementation -->

## Technical notes

[For developer audience only — API endpoints, data model references, configuration options]
[Derived from plan.md and changed files]

<!-- DRAFT: review needed — technical details generated from spec and plan -->

## Screenshots

<!-- TODO: Add screenshots from running application -->

Content generation rules: - Preserve any manually written content from the existing page (don't overwrite human edits) - Mark ALL new auto-generated sections with <!-- DRAFT: review needed --> - Convert Given/When/Then acceptance criteria into user-facing step-by-step instructions - Add a "Technical notes" section (not in original PRD-generated pages) for developer audience - If the spec has edge cases not in the existing page, add them to the table - If implementation diverged from the original PRD description, use the spec (more current)

Step 6: Write Updated Page

Write the updated content to the target path. If the page existed before, show a diff summary:

Updated: docs/user-manual/docs/features/user-registration.md

Changes:
  - "How it works" section: 3 steps → 5 steps (from spec acceptance criteria)
  - "States and edge cases" table: 2 rows → 4 rows (added validation errors)
  - NEW: "Technical notes" section (API endpoints from plan.md)
  - 3 sections marked <!-- DRAFT: review needed -->

Step 7: Update docs_page Mapping

If the spec's state.yaml does not have a docs_page field, add it:

docs_page: docs/user-manual/docs/features/[feature-slug].md

This ensures future updates can find the page automatically.

Step 8: Update Navigation

If a new page was created (not in original manual), update docs/user-manual/mkdocs.yml nav to include it.

Step 9: Summary

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
User Manual Updated for SPEC-NNN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Page: docs/user-manual/docs/features/[feature-slug].md
Source: specs/[N]-feature/spec.md
Draft markers: N sections need human review

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NEXT STEPS:
• Review pages with <!-- DRAFT: review needed --> markers
• Add screenshots from running application
• Remove DRAFT markers after review
• Run mkdocs serve in docs/user-manual/ to preview
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 10: Open Brain Capture (optional)

If capture_thought MCP tool is available:

capture_thought: "User manual updated for [feature] (SPEC-NNN). Page: [path]. Changes: [summary]. Draft sections: N."

If not available: skip silently.

pd-3 Draft Mode (--draft)

An additive mode (SPEC-153, Wave 1) for the /vt-d-pd-3-prototype phase. Invoked as /vt-d-user-manual-update --draft — it does not run Steps 1–10 above. It lets the user-manual page emerge during pd-3 so the PM gets early, clearly-provisional visibility of what is being built, driven by the SPEC-135 decision-log rather than a completed spec.

Source — the pd-3 decision-log, not a spec. --draft reads the latest decision-log entry the SPEC-135 producer (/vt-d-pd-capture-decisions, pd-3 prototype-iteration mode) writes to docs/decisions/NNN-prototype-<feature>-iter-<N>.md. This record pattern is the connectedness contract with SPEC-135 and must stay byte-identical to the producer's output literal — do not reword it on either side.

Feature slug (FR-7). Glob docs/decisions/*-prototype-<feature>-iter-*.md, take the entry with the highest <N> (latest iteration), and parse the <feature> segment from the filename between prototype- and -iter-. Slugify it → the draft page slug. No spec, no docs_page mapping, and no change to the SPEC-135 producer frontmatter is required (keeps SPEC-135 untouched).

Output surface — separate drafts/ dir, never features/ (FR-6, Decision 2). Write the draft to docs/user-manual/drafts/<feature>.md. This surface is physically distinct from the finalized docs/user-manual/docs/features/ surface that Step 6 writes; --draft must never write into features/, so it can never overwrite a finalized page — this guarantee is structural, not notice-dependent.

Works before the scaffold exists (Decision 3). During pd-3 the PRD-driven manual scaffold (docs/user-manual/ from /vt-d-user-manual-generate) may not exist yet. --draft bypasses the Step 2 "run generate first" prerequisite: create docs/user-manual/drafts/ on demand and write there. Do not auto-build a partial mkdocs scaffold or touch mkdocs.yml — leave a clean, self-contained drafts location for the eventual generate to reconcile, nothing half-built.

Thin draft template (FR-5, Decision 1). Do NOT reuse the Step 5 acceptance-criteria template — the decision-log has no user stories or Given/When/Then, so any step-by-step "How it works" or edge-case table would be fabricated. Use only fields the decision-log actually provides:

# <feature>

> **DRAFT — pd-3 iteration, expect changes.**

## What's being built

<distilled from the decision record's `rationale`>

## Why

<`rationale` + references to the `evidence` entries>

## Files touched

<the record's `linked-files`>

<!-- TODO: acceptance criteria / How-it-works pending — no user stories exist at pd-3; do not invent -->

The page-top DRAFT — pd-3 iteration, expect changes. notice is mandatory (FR-3) and is a distinct thing from the base skill's section-level <!-- DRAFT: review needed --> review markers — this banner marks the whole page as provisional; do not conflate the two. Sections that would need acceptance criteria are omitted or left as an explicit TODO placeholder, never AI-invented.

Supersede, not append (FR-8, Decision 4). One draft page per feature. Each --draft run overwrites docs/user-manual/drafts/<feature>.md to reflect the latest iteration — the opposite of the finalized path's EC-5 (append, never overwrite). Only the draft page is overwritten.

Cadence (FR-4). Runnable on-demand / manually after each decision entry. There is no auto-scheduling and no iteration-counter in Wave 1 — the user invokes --draft explicitly (consistent with SPEC-135's manual-signal philosophy).

Edge case — no decisions yet. If no docs/decisions/*-prototype-<feature>-iter-*.md entry exists, report "no pd-3 decisions to draft from" and exit cleanly (no file written).

Edge Cases

ID Scenario Handling
EC-1 No docs/user-manual/ exists Error: suggest running /vt-d-user-manual-generate first
EC-2 No matching feature page and no docs_page mapping Ask user to select from existing pages or create new
EC-3 Existing page has manual edits Preserve manual content; only update sections that match template structure
EC-4 Spec has no acceptance criteria Generate steps from goal/description; mark heavily as DRAFT
EC-5 Multiple specs map to the same feature page Read existing page content, append new sections from the latest spec below existing content. Do not overwrite sections from earlier specs. Mark new sections with DRAFT markers.
EC-6 Feature was removed (spec rejected) Don't delete the page; add a note that the feature was descoped

Integration Points

Skill Relationship
/vt-d-complete Triggers this skill at Step 5.5 after marking spec completed
/vt-d-user-manual-generate Creates the initial manual this skill updates
/vt-d-specs-from-prd Populates docs_page in state.yaml when generating specs
/vt-d-5-finalize Validates manual builds and flags DRAFT markers (SPEC-092)
/vt-d-pd-capture-decisions --draft source — its pd-3 decision-log entries (docs/decisions/NNN-prototype-<feature>-iter-<N>.md) drive pd-3 Draft Mode (SPEC-153 backflow of SPEC-135)
/vt-d-pd-3-prototype Phase where --draft runs, giving the PM an early provisional manual page