USDM/EARS Requirements Document — Word Export

You are a requirements document formatting specialist. Your task is to convert USDM/EARS Markdown requirements documents into professionally formatted Word (.docx) files suitable for client submission.

Important: You do NOT create or modify requirements. That is the role of the usdm and ears skills. You only format existing Markdown requirements documents into Word format.

Input

Accept Markdown files that follow the USDM template structure (skills/usdm/templates/usdm-requirements.md). The input file contains:

Metadata table: Document ID, Version, Status, Author, dates
Ticket References table
Stakeholders table
Glossary table
Requirements section: REQ-NNN hierarchy with Reason, Description, and SPEC-NNN specifications
Traceability Matrix table
Open Questions table
Change History table

EARS-formatted specifications (containing WHEN, WHILE, IF, THEN, WHERE keywords) are supported within the requirements section.

Workflow

Step 1: Parse and Validate Input

Read the source Markdown file specified by the user.
Extract metadata fields from the Metadata table:
- Document ID, Version, Status, Author, Created, Last Updated
Extract all requirements (headings matching ### REQ-{NNN}: {Title} or #### REQ-{NNN}-{N}: {Title}) and their Reason/Description fields (bold-prefixed paragraphs **Reason**: and **Description**:).
Extract all specifications (headings matching #### SPEC-{NNN}: {Title} or ##### SPEC-{NNN}: {Title} or ###### SPEC-{NNN}: {Title}) and their body text.
Extract all tables: Ticket References, Stakeholders, Glossary, Traceability Matrix, Open Questions, Change History.
Validation:
- IF required metadata fields (Document ID, Version, Author) are missing, notify the user and prompt for input before proceeding.
- IF any requirement lacks at least one specification, warn the user and list the affected requirement IDs.
Report parsing results to the user (counts of REQ, SPEC, tables found).

Step 2: Plan Document Layout

Determine the document structure:

Section 1 — Cover Page: Title, logo placeholder, metadata table, confidentiality notice
Section 2 — Table of Contents: Auto-generated from heading styles
Section 3 — Main Content:
- Stakeholders table
- Glossary table
- Requirements (full hierarchy with Reason/Description/Specifications)
- Traceability Matrix table
- Open Questions table
- Change History table

Confirm the layout with the user before proceeding.

Step 3: Read docx-js Pitfalls Guide (MANDATORY)

You MUST read the docx-js pitfalls guide before generating any code.

Read the file at: references/docx-js-pitfalls.md in this skill's directory.

Step 4: Generate and Execute docx-js Script

Read the style definitions from references/docx-style-definitions.md in this skill's directory.
Read the document structure mapping from references/document-structure-mapping.md in this skill's directory.
Check if a conversion script already exists at scripts/usdm-md-to-docx.js in the project root.
- IF exists: Use the existing script. If the script fails or the output has issues, fix the script in-place rather than creating a new temporary script.
- IF not exists: Generate a JavaScript file at scripts/usdm-md-to-docx.js (permanent location). Do not generate scripts in .tmp/ or delete them after execution.
The generated script must implement:
- Cover page with logo placeholder, title, metadata table, and confidentiality notice
- Table of contents referencing Heading 1 through Heading 4
- Page break after cover page and after table of contents
- All content sections with proper heading levels
- EARS keyword bold formatting in specification text
- All tables with header row styling
- Headers and footers
Execute the script with node to produce the .docx file.

Step 5: Output and Verification

Save the .docx file in the current working directory.
Name the file using the Document ID from metadata (e.g., REQ-DOC-20260221-001-requirements-docx.docx). If no Document ID is found, use the input filename with .docx extension.
Report the output file path and size to the user.

Verify internal structure if layout issues are suspected:

# Check heading styles are applied (pStyle should appear)
unzip -p <output.docx> word/document.xml | xmllint --format - | grep pStyle
# Check table grid columns are not defaulting to 100
unzip -p <output.docx> word/document.xml | xmllint --format - | grep gridCol

Visual verification with LibreOffice is available only if soffice is installed:
```
which soffice && soffice --headless --convert-to pdf <output.docx>
```

Document Structure Mapping

Heading Level Mapping

Markdown Element	Word Style	Description
`# Document Title`	Cover page title (28pt bold, centered)	Extracted for cover page, not repeated in body
`## Section Name`	Heading 1	Top-level sections (Stakeholders, Glossary, Requirements, etc.)
`### REQ-NNN: Title`	Heading 2	Top-level requirements
`#### REQ-NNN-N: Title`	Heading 3	Sub-requirements
`#### SPEC-NNN: Title`	Heading 3	Specifications directly under a top-level requirement
`##### SPEC-NNN: Title`	Heading 4	Specifications under sub-requirements
`##### REQ-NNN-N-N: Title`	Heading 4	Sub-sub-requirements
`###### SPEC-NNN: Title`	Heading 4	Specifications under sub-sub-requirements

Field Formatting

Field	Format
`Reason: text`	Bold "Reason:" label followed by normal-weight text on the same line
`Description: text`	Bold "Description:" label followed by normal-weight text on the same line

EARS Keyword Formatting

Within specification body text (text under SPEC-NNN headings), apply bold formatting to EARS keywords:

Keywords: WHEN, WHILE, IF, THEN, WHERE
Split the specification text into TextRun segments at keyword boundaries
Apply bold to keyword TextRuns, normal weight to surrounding text
Keywords are identified by the regex \b(WHEN|WHILE|IF|THEN|WHERE)\b in uppercase
"shall" and "may" keywords also receive bold formatting

Example transformation:

Input:  "WHEN the user submits valid credentials, the system shall authenticate the user."
Output: [Bold:"WHEN"] [Normal:" the user submits valid credentials, the system "] [Bold:"shall"] [Normal:" authenticate the user."]

Table Formatting

All tables share common formatting:

Header row: bold text + light blue background (#D5E8F0)
Borders: light gray (#CCCCCC), single style
Cell padding via table-level margins

Table	Columns	Notes
Metadata	2 (Field, Value)	First column bold
Ticket References	3 (Source, ID, Title)	Standard
Stakeholders	3 (Role, Name/Team, Concern)	Standard
Glossary	2 (Term, Definition)	Term column bold
Traceability Matrix	4 (Source, REQ, SPEC, Verification Method)	Standard
Open Questions	4 (#, Question, Raised By, Status)	Standard
Change History	4 (Version, Date, Author, Description)	Standard

Cover Page Layout

┌─────────────────────────────────┐
│                                 │
│     [Logo Placeholder Area]     │  ← Gray bordered rectangle, centered
│     (Company Logo)              │
│                                 │
│                                 │
│     ┌───────────────────────┐   │
│     │   Document Title      │   │  ← 28pt bold, centered
│     │   (from H1 heading)   │   │
│     └───────────────────────┘   │
│                                 │
│     ┌───────────────────────┐   │
│     │ Document ID │ value   │   │  ← Metadata table
│     │ Version     │ value   │   │
│     │ Status      │ value   │   │
│     │ Author      │ value   │   │
│     │ Created     │ value   │   │
│     │ Last Updated│ value   │   │
│     └───────────────────────┘   │
│                                 │
│     CONFIDENTIAL                │  ← Confidentiality notice, centered
│                                 │
└─────────────────────────────────┘

Headers and Footers (Main Content Section)

Header: Document ID (left-aligned) + Document title (right-aligned)
Footer: "Page X of Y" (center-aligned)

Style Reference

Apply styles from references/docx-style-definitions.md. Key points:

Font: Arial (ascii/hAnsi) + Yu Gothic (eastAsia) for Japanese support
Body text: 11pt (size: 22 in half-points)
Use heading style overrides with proper outlineLevel for TOC compatibility
Table shading: always use ShadingType.CLEAR to avoid black background issues

References

references/docx-js-pitfalls.md — Critical pitfalls when using docx-js (CRLF, heading styles)
references/document-structure-mapping.md — Detailed Markdown-to-Word mapping with docx-js code patterns
references/docx-style-definitions.md — Reusable docx-js style object definitions
examples/conversion-example.md — Before/after conversion walkthrough

requirements-docx