# Release Maintenance Guide

> Generate a professional Release & Maintenance Guide as a formatted Word (.docx) file — release/branch strategy, coding standards, documentation index, external/vendor dependencies, team contacts, known issues, technical debt, pending enhancements, and an ownership transfer checklist with sign-off. Use this whenever someone asks for a "release guide," "maintenance guide," "ongoing ownership doc," "handover sign-off," or wants a standalone document covering how a project continues to be maintained and by whom after a transition. Part of an enterprise handover documentation suite (see also: project-overview-doc, architecture-document, high-level-design, operations-deployment-guide, support-runbook, api-documentation, database-design) but fully usable standalone.

- Skill: `vedkathe/release-maintenance-guide` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add vedkathe/release-maintenance-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vedkathe/release-maintenance-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: VedKathe (https://skillmd.com/u/vedkathe)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vedkathe/release-maintenance-guide

---


# Release & Maintenance Guide Generator

Produce a single `.docx` document covering how a project keeps moving forward
after a transition — release process, coding conventions, who owns what, what's
outstanding, and a concrete ownership-transfer checklist with sign-off. This is
the most people-and-process-oriented of the handover documents: prefer
checklists and tables over long narrative paragraphs so a new team can act on
it, not just read it once.

## Sections (in this order)

Cover page, Version History, Document Approval, Revision Log, and TOC are
automatic — your `sections` array starts at "1. Release Overview".

| # | Section | Content | Diagram? |
|---|---|---|---|
| 1 | Release Overview | Why this handover/transition is happening and its effective date; current release status | |
| 2 | Branch Strategy & Release Process | Branching model, naming conventions, versioning/tagging, merge/release process, branch protection rules | |
| 3 | Coding Standards | Linting/formatting tools, naming conventions, PR/review requirements | |
| 4 | Documentation References | Links to the other handover documents (Project Overview, Architecture, HLD, Ops & Deployment Guide, Runbook, API docs, Database Design) and any wikis/ADRs | |
| 5 | External Dependencies & Vendor Ownership | Third-party services/vendors the project depends on, and who owns each relationship | |
| 6 | Team Contacts | Table: Name, Role, Area of Expertise, Contact, Availability After Handover | |
| 7 | Known Issues | Table: Issue, Impact, Current Workaround, Tracking Ticket | |
| 8 | Technical Debt | Table: Item, Reason It Exists, Risk if Unaddressed, Suggested Priority | |
| 9 | Pending Enhancements / Roadmap | Bullet list: in-flight or planned work, with status/owner/target date where known | |
| 10 | Ownership Transfer Checklist | Checklist table: Item (repo access, cloud console, domain/DNS, third-party accounts, on-call rotation, Slack channels, shared inboxes...), Transferred? (Y/N), Date, Notes | **Ownership Transfer Flow** diagram |
| 11 | Sign-off | Use `documentApprovalTable()`-style table captioned "Handed over by" / "Received by" — name, signature, date | |
| 12 | Appendix | Anything else worth preserving | |

## Diagram Policy

**Applies to the `.docx` path only** — Markdown embeds Mermaid source
directly instead of rendering anything (see "Output Format" below).

Prefer a real Mermaid diagram — rendered via `mmdc` and embedded with
`B.diagramImage()` — over `diagramPlaceholder()`, but only once you have
concrete structure to draw (real names, not "TBD"). Read
`references/diagram-generation.md` when you're actually about to render one
— it has the full build order, the bundled config
(`assets/mermaid-config.json`), the exact `mmdc` flags, and token-saving
tips. Skip it entirely if this document ends up needing no diagrams.

## Missing Information Policy

Never invent contacts, known issues, or technical debt items you have no
basis for. Use `toBeCompleted("...")` for sections you lack real input for,
explaining what's needed, and still generate everything else. Never place
actual passwords, API keys, or secret values anywhere in this document —
reference where they're stored (password manager, secrets vault) and who can
grant access instead.

## Output Format

Ask the user which output format they want, unless they've already said so in
this request (e.g., "as a docx", "in markdown," "just give me an .md file") —
a quick single-choice question is enough, don't block on it otherwise:

- **Word document (.docx)** — the default assumption if the person hasn't
  specified and their context suggests a formal deliverable. Follow "Using
  the builder" below.
- **Markdown (.md)** — no script needed, write the file directly. Use these
  conventions so it stays structurally equivalent to the docx version:

  - Front matter: instead of a cover page, open with the title as an `#`
    heading, the project name as an italic subtitle line, then a metadata
    table instead of separate Version History / Approval / Revision Log
    tables:

    ```markdown
    # Release & Maintenance Guide
    *Acme Order Platform*

    | Field | Value |
    |---|---|
    | Version | 0.1 |
    | Author | Jane Doe |
    | Date | 2026-07-19 |
    | Status | Draft |
    | Approved By | Jane Doe (Tech Lead) |
    ```
  - Headings: `#`/`##`/`###`/`####` matching the same section levels used in
    the table above — don't flatten everything to one level, that's what
    keeps the document skimmable and consistent with the docx version.
  - Tables: standard Markdown tables.
  - Diagrams — unlike the `.docx` path, don't render or embed an image here.
    Write the actual Mermaid source directly in a fenced code block; GitHub,
    GitLab, Obsidian, and most modern Markdown viewers render `mermaid` code
    blocks natively, so this is a real diagram, not a placeholder:

    ````markdown
    ```mermaid
    flowchart TD
        A[Client] --> B[API Gateway]
        B --> C[Order Service]
        C --> D[(Database)]
    ```
    ````
    Only fall back to a text placeholder if you don't yet have concrete
    enough detail to draw something real (mirrors `toBeCompleted` above):
    ```markdown
    > 📊 **DIAGRAM PLACEHOLDER — TO BE COMPLETED**
    > Not enough detail yet to draw the System Architecture Diagram — need
    > the actual component names and how they connect.
    ```
  - "To be completed" callout — same blockquote treatment:

    ```markdown
    > ⚠️ **TO BE COMPLETED**
    > Explanation of what input is needed to fill this in.
    ```
  - Save as `Release_and_Maintenance_Guide.md` instead of `Release_and_Maintenance_Guide.docx`.

## Workflow

Ask the output format first (see "Output Format" above). For Markdown, skip straight to writing the file using those conventions — the numbered steps below describe the `.docx` path.

1. Gather what's available — issue tracker export, existing contact list, or
   ask directly about known issues, tech debt, and pending work.
2. Draft each section as data using the builder functions below. Be as
   concrete and exhaustive as the available information allows on the
   Ownership Transfer Checklist — it's often the single most useful table in
   the whole package for the receiving team.
3. Build with `scripts/docx_builder.js`.
4. Skip PDF conversion by default — `docx_builder.js` is already tested and
   hardened (table widths and text alignment are enforced at the library
   level), so routine generations don't need a re-render just to confirm it
   worked. Only convert to PDF and view it if the user explicitly asks for
   visual verification, or if something about this generation is unusual
   (e.g., a new kind of content the library hasn't handled before, or a
   reported rendering problem). When you do need it: `soffice --headless
   --convert-to pdf <file>.docx` (or `libreoffice --headless ...`), then
   `pdftoppm -jpeg -r 100 <file>.pdf page` and view the images.
5. Save to `/mnt/user-data/outputs/Release_and_Maintenance_Guide.docx` (or `.md` if that's the chosen format) and present it.

## Using the builder (for the .docx path)

This library requires the `docx` npm package. Before running any script,
check it's available with `node -e "require('docx')"`; if that fails, install
it with `npm install docx` in the working directory first — don't assume it's
pre-installed, since that varies by environment.

```javascript
const B = require("./scripts/docx_builder.js");

const sections = [
  B.h1("1. Release Overview"),
  B.para("This project is transitioning from the founding team to the Platform Engineering team, effective 2026-08-01."),

  B.h1("6. Team Contacts"),
  B.table(["Name", "Role", "Area of Expertise", "Contact", "Availability After Handover"],
    [["Jane Doe", "Tech Lead", "Order Service", "jane@acme.com", "Available 2 weeks post-handover"]],
    [1800, 1800, 2000, 1800, 1800]),

  B.h1("10. Ownership Transfer Checklist"),
  B.table(["Item", "Transferred?", "Date", "Notes"],
    [["GitHub repo admin access", "No", "", "Pending — needs org owner approval"]],
    [3200, 1600, 1600, 2600]),

  // Prefer B.diagramImage(path, {caption}) with a real mmdc render when
  // possible (see "Diagram Policy" above) — diagramPlaceholder() is the fallback:
  B.diagramPlaceholder({
    name: "Ownership Transfer Flow",
    purpose: "Show the sequence of access/ownership transfers and who approves each.",
    recommendedContent: ["Outgoing team", "Incoming team", "Org admin approvals", "Vendor account transfers"],
  }),

  B.h1("11. Sign-off"),
  B.table(["", "Name", "Signature", "Date"],
    [["Handed over by", "", "", ""], ["Received by", "", "", ""]],
    [2400, 2400, 2400, 1800]),
];

await B.buildDocument("/mnt/user-data/outputs/Release_and_Maintenance_Guide.docx", {
  docLabel: "Release & Maintenance Guide",
  title: "Release & Maintenance Guide",
  subtitle: "Acme Order Platform",
  versionHistory: [["0.1", "2026-07-19", "Jane Doe", "Initial draft"]],
  approvers: [["Jane Doe", "Delivery Manager", "", ""]],
  revisionLog: [],
  sections,
});
```

Available functions: `h1`/`h2`/`h3`/`h4`, `para`, `bullets`, `table(headers,
rows, widths)`, `pageBreak`, `toBeCompleted(explanation)`,
`diagramPlaceholder({name, purpose, recommendedContent, notes})`, and
`buildDocument(path, options)`. Always use heading functions for titles so
Word's Table of Contents and Navigation Pane work correctly.

## Success Criteria

A new team should be able to release a change, follow the project's
conventions, know who to ask about what, and see exactly what access still
needs transferring — using only this document.