Skip to content

vt-c-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.

Plugin: core-standards
Category: Other
Command: /vt-c-user-manual-update

/vt-c-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-c-complete (Step 5.5) or manually when a feature page needs refreshing.

When to Use

  • After /vt-c-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-c-user-manual-generate)
  • A completed spec exists in specs/[N]-feature/spec.md

Invocation

/vt-c-user-manual-update                     # Update page for active spec (from branch)
/vt-c-user-manual-update SPEC-003            # Update page for a specific spec

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

Edge Cases

ID Scenario Handling
EC-1 No docs/user-manual/ exists Error: suggest running /vt-c-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-c-complete Triggers this skill at Step 5.5 after marking spec completed
/vt-c-user-manual-generate Creates the initial manual this skill updates
/vt-c-specs-from-prd Populates docs_page in state.yaml when generating specs
/vt-c-5-finalize Validates manual builds and flags DRAFT markers (SPEC-092)