Lintel on GitHub Copilot. Generated from skills/generate-word/SKILL.md; edit the canonical file, then run
li-copilot init.
- Resource root:
../../.. from this skill's base directory (the Lintel source with bin/,
lib/, skills/). Write plans, state and evidence into the working repository's .claude/
tree, never into the resource root.
- Skill-relative paths: this skill's own
scripts/, references/ and data/ folders (and a
<base> that the workflow defines as its own directory) mean
../../../skills/generate-word/ in the Lintel source, not this generated folder.
${LINTEL_SKILLS_DIR:-skills} means the skills root, ../../../skills. A bin/li-run step
runs in the working repository, so use $LINTEL_SKILLS_DIR/generate-word/ there.
- Shell steps: run Bash snippets with Bash (Git for Windows'
bash.exe on Windows, never
System32\bash.exe). Save a snippet to a temporary .sh file and run
bash "<resource root>/bin/li-run" <file>; it prepares LINTEL_SOURCE_ROOT, LINTEL_REPO_ROOT
and the profile context.
- Tools: Read=
view, Write=create, Edit=edit, Bash=bash/powershell, Grep=grep,
Glob=glob, AskUserQuestion=ask_user, TodoWrite=the plan checklist, Task or a named role=task
with that custom agent, WebFetch=web_fetch.
- Other Lintel workflows are native skills: invoke
/li-<name> rather than reading their
files. Named roles such as CodeReviewer are custom agents.
/generate-word
Editable Word document generation with source fidelity and applicable configured
policy. Three target variants:
technical — engineering-internal deliverable (technical spec, runbook, ADR-style doc) — voice: internal
customer-summary — customer-bound engagement summary — voice: pack-resolved (customer-facing tier), gated
transparency-note — AI-feature transparency note — voice: pack-resolved (customer-facing tier), gated, includes honest-limitations check
--brief is a standalone route: it does not require generate-design, a domain
envelope or an invented shared design input. Preserve the complete brief and its
evidence, not just an outline or slide summary.
Prerequisites
Discover the host's actual create/read/edit/render operations and their schemas.
Prefer a native Word artifact API when available. On the Copilot canvas surface,
call list_canvas_capabilities for word, then open_canvas on an explicit owned
path; use the discovered get_model and batch actions. The
native Word procedure documents that observed route
and its page-render boundary. Never guess an action or claim a tool ran from its
presence in a manifest.
Retain the existing declared library alternatives: docxtemplater plus pizzip
for a compatible .docx template, or docx for programmatic generation. Check the
selected task-local environment before use. Only after an actual missing-tool
failure may an authorized task-local restore be considered; do not install
automatically/globally or assume every library can consume every template.
If no writer exists, retain the Markdown source and mark DOCX generation blocked.
An explicitly chosen Markdown/PDF alternative is not an editable DOCX substitute.
When to use
- Customer engagement summary deliverable
- Technical spec / architecture doc with the active pack's brand identity
- AI-feature transparency note (compliance artifact, if the active pack requires one)
When NOT to use
- Quick markdown note — use direct editing
- Slide content — use
/generate-ppt
- Multi-page wiki/site — use
/generate-web
Inputs
- Required
--brief <path|inline> — content brief or source markdown OR --from-pipeline <dir> (shared pipeline mode)
- Required
--target <technical|customer-summary|transparency-note> — variant
- Optional
--template <name|path> — explicit selection overrides the omitted-flag default <target>.docx in the verified configured brand directory
- Optional
--audience <text> — primary audience
- Optional
--voice — voice tier override (default per target)
- Optional
--use-defaults — use an available neutral template or an explicitly blank native document; never invent a missing bundled template
- Optional
--ignore-stale-brand <reason> — record an advisory staleness exception; cannot waive mandatory policy
- Optional
--out <path> — explicit new .docx output (default: <brief-stem>.docx in the working directory)
Standalone template selection
Without --template and without --use-defaults, select <target>.docx from
the already verified configured brand directory:
| Target |
Default template filename |
technical |
technical.docx |
customer-summary |
customer-summary.docx |
transparency-note |
transparency-note.docx |
Explicit --template takes precedence over <target>.docx on this brand route:
use its explicit path, or resolve its name inside that same verified directory.
--use-defaults selects the explicit neutral/default route described above
instead of the implicit brand-template lookup; required policy still applies.
Omitting --template does not imply --use-defaults.
No personal-directory scan is permitted. If the selected template/directory is
unavailable, report that gap; do not silently choose another variant or claim a
blank document satisfies required brand policy.
From-pipeline mode (v3.5 Phase 2 — generate-pipeline integration)
If invoked with --from-pipeline <run-dir> instead of --brief:
Keep this existing entry path and field names. First follow
existing pipeline input admission
with --format word, the external input context, original package/leaves and
current profile. It verifies canonical sibling paths/hashes and the existing
Word projection, not a web renderer or completed artifact. Actual native/source
inspections remain separate required P05 evidence; retired document-format
acceptance is not a live gate. Never fabricate design-spec.json to unblock a consumer.
Read shared pipeline-output:
<run-dir>/content.md — sections with H1/H2/H3 hierarchy + bodies + voice-annotations
<run-dir>/design-spec.json — read per_format.word.sections for heading-levels + slot-mappings
Replace brief-parsing logic with direct-read of content.md (per target-variant):
technical: headings + paragraphs + code blocks + tables
customer-summary: narrative paragraphs + key findings + next steps
transparency-note: capabilities + limitations + data + decisions + appeals
Apply format-specific design-pass via design_pass_hook:
- Reads
per_format.word.sections[N].design_pass_hook (canonical: WordTechnicalEditor)
- Invokes agent for a Word-specific fidelity-pass (heading-style consistency, technical-tone, tables-formatting)
- Per Reviewer Concern #7: WordTechnicalEditor stays word-specific
CLI stays backward-compat: existing --brief-flag invocations work unchanged. --from-pipeline is additive.
Apply the same fidelity/inspection and configured controls as standalone mode.
Shared content must survive in full; heading/slot mappings cannot discard
unmapped paragraphs, tables, citations or qualifications.
Retain all three standalone target/template/default choices. Select any
explicit override as an input before admission and revalidate the actual
template mapping; an omitted projection template is not --use-defaults.
Final changed DOCX and its actual observations need a fresh external P05
binding. Missing Word page rendering remains unverified.
Workflow
Preflight and policy. Follow the
P05/P07 fidelity and evidence procedure.
Resolve source/output paths and the standalone template selection above;
refuse unapproved replacement.
Verify the pinned profile and requested controls. Use only configured brand/voice
rules and their actual applicability. A required template, policy or inspection
that is unavailable remains blocked. Neutral mode needs no personal brand scan.
Read the complete brief and compose the target.
- technical: meaningful heading styles, multi-paragraph reasoning, code,
editable tables with headers/units, references and material limitations.
- customer-summary: audience-appropriate narrative, supported findings and
next steps; retain qualifications rather than enforcing a fixed page count.
- transparency-note: capabilities, material limitations and failure
conditions, data, decision impact, appeals and disclosure as required by the
brief/policy. Map each material claim to its evidence and relevant boundary.
Preserve the claim/evidence ledger and citation targets. Label missing evidence;
do not invent a legal basis, retention period, contact or measured result.
Use WordTechnicalEditor as the format-specific review method.
Read its accepted source; delegate only through a real available host operation,
with read-only source/artifact inputs. It checks structure and claim accuracy;
pack voice scoring remains separate. Source-only advice is pre-generation
review, not DOCX inspection. A builder's own pass is self-review, not independent.
Create editable content through the selected writer.
With native operations, inspect available styles, insert complete paragraphs,
apply real heading styles, and create/edit table cells. With a declared library,
fill only a compatible explicit template or create the same document structure.
Keep code and list semantics, cross-references, table headers and cited evidence.
If an unsupported field, footnote, image or layout is required, report that
specific gap instead of silently flattening it or claiming fidelity.
Reopen, edit/read back, and inspect the actual artifact.
Open the saved .docx through the available application/API. Read body, tables,
styles, headers/footers and relevant notes/fields. Make a small authorized edit,
read it back and restore it if it is only a verification marker. Compare the
full source ledger to the saved content. Render every page where supported;
inspect pagination, heading orphans, table continuation, margins, references,
clipping and legibility. A ZIP parse or get_model is not rendered page evidence.
Record actual outcomes, not a four-score shortcut.
Retain the familiar voice, brand, honest-limitations and provenance categories
with grounded applicability, plus source retention, editability and rendered
inspection. Mandatory failure/error/unverified blocks the affected completion
or distribution regardless of other scores. An absent optional brand/voice
requirement is not failed compliance or verified enterprise enforcement.
Persist P05 evidence bound to the final artifact and current P07 reference.
Keep incomplete output at its explicit owned path, clearly marked unverified;
do not move it through an implicit personal draft directory.
Reusable patterns
Follow the reusable pattern consumer contract.
Brief mode resolves for the brief's context; from-pipeline mode verifies the run's
pattern_context attachment. Both receive the same clauses before structure and content
choices: sections required by mandatory clauses become headings, and the clauses go to the
existing quality review and the QA report. Removing a required section is a failed clause. A
helper fixture proves only this integration; a real generated-document case is separate host
evidence.
Report format
Report the exact source/output paths and hashes; target; actual template or blank
choice; verified profile reference; writer/tool/provider/instance/actions; retained
claims, paragraphs, tables, citations and limitations; reopen/edit result; rendered
pages inspected or precise missing renderer; each configured control's observed
status and evidence; and the remaining acceptance/review gates. Do not fill this
report with illustrative PASS scores, invented provenance IDs or guessed page counts.
Compliance integration
- Honor applicable configured controls and the brief's disclosure requirements.
A transparency note needs claim-to-evidence/limitation coverage, not a count ratio.
- No customer data, secrets, macro execution or external upload in synthetic validation.
- Generation is not authorization to distribute. Required independent review and
delivery controls stay open until their actual evidence exists.
Failure modes
- Template/placeholder mismatch: preserve the source and identify the missing slot; do not drop content.
- Material limitation/evidence missing: name the uncovered claim and keep the relevant control unresolved.
- Required voice/template unavailable: block that action;
--use-defaults cannot override required policy.
- Page renderer absent: retain editable DOCX and model evidence, with rendered layout unverified.
- Only Markdown/PDF available: disclose the alternative and keep promised DOCX editability open.
Examples
Technical spec:
> /generate-word --brief docs/spec/auth-rewrite.md --target technical
[Resolve applicable controls, select an available writer, then inspect actual output.]
Customer summary:
> /generate-word --brief summary-brief.md --target customer-summary --audience "Technical decision makers" --out summary.docx
[Preserve sources and qualifications; run the configured customer-facing controls.]
Transparency note:
> /generate-word --brief case-analysis-design.md --target transparency-note
[Check material claim boundaries and required disclosures; no limitation-count proxy.]
Neutral standalone:
> /generate-word --brief synthetic-brief.md --target technical --use-defaults --out synthetic.docx
[Use an explicitly blank native document when available; no personal template lookup.]
See also
1---2name: li-generate-word3description: Use to create an editable Word document from selected source material through available native tools or a declared library, preserving detail and reporting actual inspection evidence.4metadata:5 source: https://skillmd.com/skills/jokerman89/li-generate-word6---78> **Lintel on GitHub Copilot.** Generated from `skills/generate-word/SKILL.md`; edit the canonical file, then run9> `li-copilot init`.10> - **Resource root:** `../../..` from this skill's base directory (the Lintel source with `bin/`,11> `lib/`, `skills/`). Write plans, state and evidence into the working repository's `.claude/`12> tree, never into the resource root.13> - **Skill-relative paths:** this skill's own `scripts/`, `references/` and `data/` folders (and a14> `<base>` that the workflow defines as its own directory) mean15> `../../../skills/generate-word/` in the Lintel source, not this generated folder.16> `${LINTEL_SKILLS_DIR:-skills}` means the skills root, `../../../skills`. A `bin/li-run` step17> runs in the working repository, so use `$LINTEL_SKILLS_DIR/generate-word/` there.18> - **Shell steps:** run Bash snippets with Bash (Git for Windows' `bash.exe` on Windows, never19> `System32\bash.exe`). Save a snippet to a temporary `.sh` file and run20> `bash "<resource root>/bin/li-run" <file>`; it prepares `LINTEL_SOURCE_ROOT`, `LINTEL_REPO_ROOT`21> and the profile context.22> - **Tools:** Read=`view`, Write=`create`, Edit=`edit`, Bash=`bash`/`powershell`, Grep=`grep`,23> Glob=`glob`, AskUserQuestion=`ask_user`, TodoWrite=the plan checklist, Task or a named role=`task`24> with that custom agent, WebFetch=`web_fetch`.25> - **Other Lintel workflows** are native skills: invoke `/li-<name>` rather than reading their26> files. Named roles such as `CodeReviewer` are custom agents.2728# /generate-word2930Editable Word document generation with source fidelity and applicable configured31policy. Three target variants:3233- **`technical`** — engineering-internal deliverable (technical spec, runbook, ADR-style doc) — voice: internal34- **`customer-summary`** — customer-bound engagement summary — voice: pack-resolved (customer-facing tier), gated35- **`transparency-note`** — AI-feature transparency note — voice: pack-resolved (customer-facing tier), gated, includes honest-limitations check3637`--brief` is a standalone route: it does not require generate-design, a domain38envelope or an invented shared design input. Preserve the complete brief and its39evidence, not just an outline or slide summary.4041## Prerequisites4243Discover the host's actual create/read/edit/render operations and their schemas.44Prefer a native Word artifact API when available. On the Copilot canvas surface,45call `list_canvas_capabilities` for `word`, then `open_canvas` on an explicit owned46path; use the discovered `get_model` and `batch` actions. The47[native Word procedure](../../../skills/generate-word/references/native-word.md) documents that observed route48and its page-render boundary. Never guess an action or claim a tool ran from its49presence in a manifest.5051Retain the existing declared library alternatives: `docxtemplater` plus `pizzip`52for a compatible `.docx` template, or `docx` for programmatic generation. Check the53selected task-local environment before use. Only after an actual missing-tool54failure may an authorized task-local restore be considered; do not install55automatically/globally or assume every library can consume every template.56If no writer exists, retain the Markdown source and mark DOCX generation blocked.57An explicitly chosen Markdown/PDF alternative is not an editable DOCX substitute.5859## When to use6061- Customer engagement summary deliverable62- Technical spec / architecture doc with the active pack's brand identity63- AI-feature transparency note (compliance artifact, if the active pack requires one)6465## When NOT to use6667- Quick markdown note — use direct editing68- Slide content — use `/generate-ppt`69- Multi-page wiki/site — use `/generate-web`7071## Inputs7273- Required `--brief <path|inline>` — content brief or source markdown **OR** `--from-pipeline <dir>` (shared pipeline mode)74- Required `--target <technical|customer-summary|transparency-note>` — variant75- Optional `--template <name|path>` — explicit selection overrides the omitted-flag default `<target>.docx` in the verified configured brand directory76- Optional `--audience <text>` — primary audience77- Optional `--voice` — voice tier override (default per target)78- Optional `--use-defaults` — use an available neutral template or an explicitly blank native document; never invent a missing bundled template79- Optional `--ignore-stale-brand <reason>` — record an advisory staleness exception; cannot waive mandatory policy80- Optional `--out <path>` — explicit new `.docx` output (default: `<brief-stem>.docx` in the working directory)8182### Standalone template selection8384Without `--template` and without `--use-defaults`, select `<target>.docx` from85the already verified configured brand directory:8687| Target | Default template filename |88|---|---|89| `technical` | `technical.docx` |90| `customer-summary` | `customer-summary.docx` |91| `transparency-note` | `transparency-note.docx` |9293Explicit `--template` takes precedence over `<target>.docx` on this brand route:94use its explicit path, or resolve its name inside that same verified directory.95`--use-defaults` selects the explicit neutral/default route described above96instead of the implicit brand-template lookup; required policy still applies.97Omitting `--template` does not imply `--use-defaults`.98No personal-directory scan is permitted. If the selected template/directory is99unavailable, report that gap; do not silently choose another variant or claim a100blank document satisfies required brand policy.101102## From-pipeline mode (v3.5 Phase 2 — generate-pipeline integration)103104If invoked with `--from-pipeline <run-dir>` instead of `--brief`:105106Keep this existing entry path and field names. First follow107[existing pipeline input admission](../../../skills/generate-write/references/fidelity-and-evidence.md#existing-pipeline-input-admission)108with `--format word`, the external input context, original package/leaves and109current profile. It verifies canonical sibling paths/hashes and the existing110Word projection, not a web renderer or completed artifact. Actual native/source111inspections remain separate required P05 evidence; retired document-format112acceptance is not a live gate. Never fabricate design-spec.json to unblock a consumer.1131141. **Read shared pipeline-output:**115 - `<run-dir>/content.md` — sections with H1/H2/H3 hierarchy + bodies + voice-annotations116 - `<run-dir>/design-spec.json` — read `per_format.word.sections` for heading-levels + slot-mappings1171182. **Replace brief-parsing logic** with direct-read of content.md (per target-variant):119 - `technical`: headings + paragraphs + code blocks + tables120 - `customer-summary`: narrative paragraphs + key findings + next steps121 - `transparency-note`: capabilities + limitations + data + decisions + appeals1221233. **Apply format-specific design-pass via design_pass_hook:**124 - Reads `per_format.word.sections[N].design_pass_hook` (canonical: WordTechnicalEditor)125 - Invokes agent for a Word-specific fidelity-pass (heading-style consistency, technical-tone, tables-formatting)126 - Per Reviewer Concern #7: WordTechnicalEditor stays word-specific1271284. **CLI stays backward-compat:** existing `--brief`-flag invocations work unchanged. `--from-pipeline` is additive.1291305. **Apply the same fidelity/inspection and configured controls as standalone mode.**131 Shared content must survive in full; heading/slot mappings cannot discard132 unmapped paragraphs, tables, citations or qualifications.133 Retain all three standalone target/template/default choices. Select any134 explicit override as an input before admission and revalidate the actual135 template mapping; an omitted projection template is not `--use-defaults`.136 Final changed DOCX and its actual observations need a fresh external P05137 binding. Missing Word page rendering remains unverified.138139## Workflow1401411. **Preflight and policy.** Follow the142 [P05/P07 fidelity and evidence procedure](../../../skills/generate-write/references/fidelity-and-evidence.md).143 Resolve source/output paths and the standalone template selection above;144 refuse unapproved replacement.145 Verify the pinned profile and requested controls. Use only configured brand/voice146 rules and their actual applicability. A required template, policy or inspection147 that is unavailable remains blocked. Neutral mode needs no personal brand scan.1481492. **Read the complete brief and compose the target.**150 - **technical:** meaningful heading styles, multi-paragraph reasoning, code,151 editable tables with headers/units, references and material limitations.152 - **customer-summary:** audience-appropriate narrative, supported findings and153 next steps; retain qualifications rather than enforcing a fixed page count.154 - **transparency-note:** capabilities, material limitations and failure155 conditions, data, decision impact, appeals and disclosure as required by the156 brief/policy. Map each material claim to its evidence and relevant boundary.157 Preserve the claim/evidence ledger and citation targets. Label missing evidence;158 do not invent a legal basis, retention period, contact or measured result.1591603. **Use WordTechnicalEditor as the format-specific review method.**161 Read its accepted source; delegate only through a real available host operation,162 with read-only source/artifact inputs. It checks structure and claim accuracy;163 pack voice scoring remains separate. Source-only advice is pre-generation164 review, not DOCX inspection. A builder's own pass is self-review, not independent.1651664. **Create editable content through the selected writer.**167 With native operations, inspect available styles, insert complete paragraphs,168 apply real heading styles, and create/edit table cells. With a declared library,169 fill only a compatible explicit template or create the same document structure.170 Keep code and list semantics, cross-references, table headers and cited evidence.171 If an unsupported field, footnote, image or layout is required, report that172 specific gap instead of silently flattening it or claiming fidelity.1731745. **Reopen, edit/read back, and inspect the actual artifact.**175 Open the saved `.docx` through the available application/API. Read body, tables,176 styles, headers/footers and relevant notes/fields. Make a small authorized edit,177 read it back and restore it if it is only a verification marker. Compare the178 full source ledger to the saved content. Render every page where supported;179 inspect pagination, heading orphans, table continuation, margins, references,180 clipping and legibility. A ZIP parse or `get_model` is not rendered page evidence.1811826. **Record actual outcomes, not a four-score shortcut.**183 Retain the familiar voice, brand, honest-limitations and provenance categories184 with grounded applicability, plus source retention, editability and rendered185 inspection. Mandatory failure/error/unverified blocks the affected completion186 or distribution regardless of other scores. An absent optional brand/voice187 requirement is not failed compliance or verified enterprise enforcement.188 Persist P05 evidence bound to the final artifact and current P07 reference.189 Keep incomplete output at its explicit owned path, clearly marked unverified;190 do not move it through an implicit personal draft directory.191192## Reusable patterns193194Follow the [reusable pattern consumer contract](../../../skills/pattern/references/consumer-contract.md).195Brief mode resolves for the brief's context; from-pipeline mode verifies the run's196`pattern_context` attachment. Both receive the same clauses before structure and content197choices: sections required by mandatory clauses become headings, and the clauses go to the198existing quality review and the QA report. Removing a required section is a failed clause. A199helper fixture proves only this integration; a real generated-document case is separate host200evidence.201202## Report format203204Report the exact source/output paths and hashes; target; actual template or blank205choice; verified profile reference; writer/tool/provider/instance/actions; retained206claims, paragraphs, tables, citations and limitations; reopen/edit result; rendered207pages inspected or precise missing renderer; each configured control's observed208status and evidence; and the remaining acceptance/review gates. Do not fill this209report with illustrative PASS scores, invented provenance IDs or guessed page counts.210211## Compliance integration212213- Honor applicable configured controls and the brief's disclosure requirements.214 A transparency note needs claim-to-evidence/limitation coverage, not a count ratio.215- No customer data, secrets, macro execution or external upload in synthetic validation.216- Generation is not authorization to distribute. Required independent review and217 delivery controls stay open until their actual evidence exists.218219## Failure modes220221- **Template/placeholder mismatch:** preserve the source and identify the missing slot; do not drop content.222- **Material limitation/evidence missing:** name the uncovered claim and keep the relevant control unresolved.223- **Required voice/template unavailable:** block that action; `--use-defaults` cannot override required policy.224- **Page renderer absent:** retain editable DOCX and model evidence, with rendered layout unverified.225- **Only Markdown/PDF available:** disclose the alternative and keep promised DOCX editability open.226227## Examples228229**Technical spec:**230```231> /generate-word --brief docs/spec/auth-rewrite.md --target technical232[Resolve applicable controls, select an available writer, then inspect actual output.]233```234235**Customer summary:**236```237> /generate-word --brief summary-brief.md --target customer-summary --audience "Technical decision makers" --out summary.docx238[Preserve sources and qualifications; run the configured customer-facing controls.]239```240241**Transparency note:**242```243> /generate-word --brief case-analysis-design.md --target transparency-note244[Check material claim boundaries and required disclosures; no limitation-count proxy.]245```246247**Neutral standalone:**248```249> /generate-word --brief synthetic-brief.md --target technical --use-defaults --out synthetic.docx250[Use an explicitly blank native document when available; no personal template lookup.]251```252253## See also254255- [Native Word procedure](../../../skills/generate-word/references/native-word.md)256- [Content fidelity and evidence](../../../skills/generate-write/references/fidelity-and-evidence.md)257- `WordTechnicalEditor` agent258- The active pack's compliance gates (`resolve_pack_field compliance.hooks`; none by default)259- `/generate-ppt`, `/generate-web`