Deploy notes

deploy-notes skill

You are generating two release notes artifacts from a raw deployment notes .docx file written by a developer. The audience is the operations and testing team — non-technical people who need to understand what changed and what to check. Write in plain language. No jargon.

---

0. Customize before first use

Two values are meant to be adapted per company — set them once and keep them consistent:

• {COMPANY_NAME} — appears in the page header (e.g. Acme Corp)
• Brand colors — BRAND_BLUE and LIGHT_BLUE_BG in the palette below are the accent colors; swap them for your brand. The three badge colors are semantic (feature/enhancement/fix) and can stay as-is.

---

1. Understand the input

The raw .docx is a loose bullet list. Each top-level bullet is one item (feature, fix, or enhancement). Sub-bullets give detail. Inline screenshots (images) are embedded and belong to the item immediately above them.

Parse steps (helper scripts ship in this skill's scripts/ folder — resolve paths relative to this SKILL.md):

1. Extract full text with pandoc input.docx -o content.md
2. Unpack images: python3 <skill-dir>/scripts/unpack.py input.docx unpacked/ → images are in unpacked/word/media/
3. Copy images to outputs: cp unpacked/word/media/image*.png outputs/
4. Map images to items by their position in the markdown output (images appear as ![](media/imageN.png) immediately after the text they illustrate)

---

2. Classify each item

Assign exactly one type to each item:

Type	When to use	Badge color (hex)
New Feature	Brand-new capability that did not exist before	0F7B4F (green)
Enhancement	Improvement or extension to an existing feature	6B21A8 (purple)
Bug Fix	Something was broken and is now fixed	B45309 (amber)

If an item is ambiguous, ask before classifying — do not guess.

Order in the document: preserve the original order from the raw doc. Do NOT regroup by type. The summary table at the top gives the overview; the detailed sections follow in raw-doc order.

---

3. Visual Word document (.docx)

File naming

Release_Notes_{MonthName}{Day}_{Year}.docx Examples: Release_Notes_June_2026.docx, Release_Notes_July5_2026.docx, Release_Notes_July12_2026.docx

Output location

outputs/ directory (the session working folder)

Build method

Use the docx npm package. Install in a temp directory with npm install docx. Run your generation script from the same directory (local node_modules resolution requires it).

Page setup

Page size: US Letter (12240 × 15840 DXA)
Margins: 1 inch all sides (1440 DXA each)
Content width: 9360 DXA
Default font: Arial 11pt (size: 22 in half-points)

Color palette

BRAND_BLUE      = "1A56A4"   // header accent, table header bg, infoBox left border — SWAP FOR YOUR BRAND
LIGHT_BLUE_BG   = "EBF3FB"   // infoBox background — SWAP FOR YOUR BRAND (light tint of BRAND_BLUE)
NEW_FEAT_COLOR  = "0F7B4F"   // New Feature badge fill
ENHANCE_COLOR   = "6B21A8"   // Enhancement badge fill
FIX_COLOR       = "B45309"   // Bug Fix badge fill
GRAY_TEXT       = "555555"   // all body text
DIVIDER_COLOR   = "D1D5DB"   // horizontal rules, table borders
WHITE           = "FFFFFF"

Header / Footer

• Header: "{COMPANY_NAME} | Release Notes | {Month} {Day}, {Year}" — 9pt Arial, gray (94A3B8), blue (BRAND_BLUE) bottom border
• Footer: right-aligned "Page X of Y" — 9pt Arial, gray, light (DIVIDER_COLOR) top border

Document structure

Cover block

"Release Notes"                     26pt bold BRAND_BLUE
"Deployment Update  •  {Date}"      12pt slate (64748B)
"Prepared for: Operations & Testing Team"   11pt muted (94A3B8)
[horizontal divider]

Intro block

"What's in this release?"           16pt bold dark (1E293B)
One sentence: "This update includes X new features, Y enhancements, and Z bug fixes."

Summary table

Columns (DXA): # (700), Feature / Change (3500), Type (1800), Who it helps (3260)

• Header row: BRAND_BLUE bg, white bold text
• Data rows: alternating white / F8FAFC
• Type cell: colored text matching badge color (not the fill — text only)
• "Who it helps": short audience label, e.g. "All users" / "Operations team" / "Billing team" / "Ops & Testing" — pick most accurate per item

Per-item sections (in original doc order)

[horizontal divider]
[BADGE]           ← colored pill: "NEW FEATURE" / "ENHANCEMENT" / "BUG FIX"
[Section title]   ← "{N}. {Human-readable title}" — 14pt bold dark (1E293B)
[Body paragraphs] ← 2–4 sentences, plain language, 11pt GRAY_TEXT
[Bullet list]     ← only if item has distinct enumerable sub-points
[spacer]
[infoBox]         ← "What this means for you: ..." — always present
[screenshot(s)]   ← AFTER the infoBox, one imageBlock() call per image

Image sizing: compute height as Math.round(580 * origH / origW). Check original dimensions with Pillow:

python3 -c "from PIL import Image; img=Image.open('img.png'); print(img.size)"

infoBox: left border 8pt BRAND_BLUE, other borders 1pt BFDBFE, bg LIGHT_BLUE_BG, text 10.5pt dark blue (1E3A5F).

Badge: ALL-CAPS label, padded with spaces (" LABEL "), white bold 8pt, fill = type color.

Bullet lists: LevelFormat.BULLET with •, indent left=720 hanging=360. Never raw unicode bullets.

Sub-sections (complex items only)

Use when one item has 2+ distinct named aspects. Pattern:

[sectionTitle]
[overview body]
[spacer]
[subTitle for aspect 1]     ← 12pt bold dark, spacing before 160
[body + bullets]
[images for aspect 1]       ← placed after aspect 1 prose, before next subTitle
[subTitle for aspect 2]
[body]
[spacer]
[infoBox]                   ← single infoBox at END covering the whole section

---

4. Markdown / plain-text version

No file needed — deliver as text in the chat response for the user to copy into a notes app or message.

Format

**Release Notes — {Month} {Day}, {Year}**
*Deployment Update for Ops & Testing Team*

---

**{N}. {Title}** — *{Type}*
2–4 sentence plain-language description. No infoBox callout — fold the
"what this means for you" message into the prose directly.

---

Rules:

• Divider is exactly ---
• Type label exactly: Bug Fix, New Feature, or Enhancement
• NO images, NO captions, NO sub-section headings
• Flatten complex multi-sub-section items into 1–2 paragraphs
• Sequential numbering matching Word doc order
• Same tone as Word doc body text

---

5. Edge cases

Situation	Resolution
Item has no screenshot	Skip imageBlock; infoBox is the last element
Item has multiple screenshots	One imageBlock() per image, all after the infoBox
Complex item with named sub-aspects	Use subTitle() per aspect; images go after each sub-aspect prose; single infoBox at section end
Ambiguous classification (bug vs enhancement)	Ask the user — do not guess
Raw doc has spelling errors / poor grammar	Rewrite cleanly; preserve meaning
Non-English text in raw doc	Translate to English; treat as regular detail
Image aspect ratio unknown	Check with Pillow; compute proportional height from 580px width

---

6. Validation

python3 <skill-dir>/scripts/validate.py outputs/Release_Notes_*.docx

Must pass before presenting the file. Fix any XML errors and re-run.

---

7. Skeletons

Word doc — simple item (no sub-sections)

children.push(
  divider(),
  badge("BUG FIX", FIX_COLOR),
  sectionTitle("3. Auto-Logout Fix"),
  body("Users were being logged out while actively working. Fixed — auto-logout now only triggers on genuine idle time."),
  body("After logging back in, you are redirected to the page you were on."),
  spacer(),
  infoBox("What this means for you: No more unexpected logouts mid-task. Logging back in picks up where you left off."),
  ...imageBlock(`${OUTPUTS}/img1.png`, "Caption describing the screenshot", 580, 304),
);

Word doc — complex item (with sub-sections)

children.push(
  divider(),
  badge("ENHANCEMENT", ENHANCE_COLOR),
  sectionTitle("5. Customer Address Lookup & Validation"),
  body("The order form now has two smart address features."),
  spacer(),
  subTitle("Smart Address Validation"),
  body("Entering a shipping address that conflicts with the selected region triggers a warning and clears the fields."),
  ...imageBlock(`${OUTPUTS}/img2.png`, "Entering a mismatched address", 580, 332),
  ...imageBlock(`${OUTPUTS}/img3.png`, "Alert shown after conflict detected", 580, 332),
  subTitle("Create a New Customer On the Spot"),
  body("New customers can be created directly from the order form and are auto-selected."),
  spacer(),
  infoBox("What this means for you: Fewer data-entry mistakes and no need to leave the form to add a missing customer."),
);

Markdown version

**Release Notes — July 12, 2026**
*Deployment Update for Ops & Testing Team*

---

**1. Auto-Logout Now Works Correctly** — *Bug Fix*
Users were being logged out while actively working. Fixed — it now only
triggers on genuine idle time. After logging back in you are automatically
returned to the page you were on.

---

**2. Exported Reports Include All Columns** — *Bug Fix*
Exported CSV reports were missing the last two columns on some pages. Now
fixed — every export contains the full column set shown on screen.

---

---

8. Helper function signatures (for generation scripts)

divider()                              // horizontal rule (bottom border, DIVIDER_COLOR)
badge(label, colorHex)                 // ALL-CAPS colored pill label
sectionTitle(text)                     // 14pt bold section heading
subTitle(text)                         // 12pt bold sub-heading (complex items only)
body(text)                             // 11pt gray body paragraph
bullet(text)                           // bulleted list item
infoBox(text)                          // blue left-border highlight box
imageBlock(path, caption, width, height) // centered image + italic caption → returns array
spacer()                               // blank paragraph, 120 DXA top spacing