thesis-docx

---
name: thesis-docx
description: Create, revise, and format thesis or dissertation Word documents with strict academic formatting control. Use when an AI agent needs to generate or revise thesis content, normalize Word styles, follow a school template, fix captions or page numbers or section levels, or produce evidence-based Mermaid figures and LaTeX-formatted code listings for a thesis document.
license: MIT
---

# Thesis DOCX

## Overview

Use this skill for thesis-oriented `.docx` work where content quality and
format fidelity both matter. Prefer Microsoft Word desktop automation over
WPS-like alternatives whenever the task involves batch formatting, styles,
captions, pagination, tables of contents, or cross-references.

This skill is designed to avoid the most common thesis-editing failure mode:
the agent makes broad formatting changes too early, introduces new layout
problems, and then forces the user to catch them one by one. The default
behavior should therefore be:

1. audit first,
2. separate explicit school requirements from unspecified formatting,
3. fix only what is justified,
4. re-check page by page before claiming completion.

## Workflow

1. Check Microsoft Word and COM/DOM automation first.
   - On Windows, run:
   ```powershell
   powershell -ExecutionPolicy Bypass -File scripts/check_word_com.ps1 -Json
   ```
   - If Word is missing, COM is unavailable, or DOM access fails:
     - Stop the automation-heavy plan.
     - Tell the user to install desktop Microsoft Word.
     - Explain briefly that WPS or similar tools are likely to degrade layout
       fidelity for thesis formatting.
2. Read the user's real constraints before editing.
   - Collect the thesis template, school formatting guide, screenshots,
     existing document, sample pages, and any explicit chapter rules.
   - If the user gave formal requirements, follow them strictly.
   - If the user did not give requirements, do not invent school-specific
     standards. Use conservative academic defaults and say that they are
     defaults.
   - Explicitly classify requirements into two buckets before editing:
     - `must enforce`: school guide, template, user-confirmed style rules
     - `preserve current state`: anything the school guide does not define
3. Audit the DOCX / OOXML before risky bulk edits.
   - Prefer `scripts/audit_docx_ooxml.py` before large-scale formatting.
   - Use it to detect hidden indentation, section drift, stale REF display
     text, and style-ID mismatches before deciding on a repair strategy.
4. Standardize with styles, not scattered direct formatting.
   - Reuse and repair existing styles whenever possible.
   - Create missing styles only when no matching style exists.
   - Keep body text, headings, figure captions, table captions, references,
     abstract, and appendix styles separate and consistent.
   - Before changing any style globally, inspect whether the document contains
     direct paragraph formatting or OOXML overrides that will survive the style
     change.
5. Edit content only from user-provided facts.
   - Expand, polish, or reorganize thesis text only within the user's topic,
     evidence, codebase, notes, or source material.
   - Do not invent experimental data, system structure, entities, or results.
   - Do not expose agent reasoning or data-feeding context inside the thesis
     prose. Forbidden patterns include thesis-language such as:
     - "根据已有工程"
     - "根据现有代码"
     - "将任务书和代码喂给模型后"
     - "通过分析用户提供的代码"
     - any wording that sounds like an AI workflow note instead of thesis prose
   - Write in normal thesis voice, not in prompt-engineering voice, review
     voice, or chain-of-thought voice.
   - Prefer neutral academic narration that reads like student writing, e.g.
     "本文设计并实现了……", "系统采用了……", "在该模块中……"
   - Avoid first-order meta-explanations about how the text was generated,
     inferred, or assembled.
6. Generate figures only when the source material is sufficient.
   - Use Mermaid for architecture diagrams, E-R diagrams, flow charts, state
     diagrams, and similar thesis figures.
   - Base every node, field, relation, and dependency on real materials from
     the user, such as code, SQL schema, API docs, project docs, or the thesis
     draft itself.
   - If the materials are insufficient, refuse to fabricate the figure and ask
     for the missing source information.
7. Typeset code with LaTeX conventions when thesis code excerpts are needed.
   - Keep only the code relevant to the argument.
   - Preserve real identifiers from the user's code or design.
   - Avoid synthetic filler code written only to look complete.
8. Audit before you claim completion.
   - Run a structure audit first: styles, sections, captions, references,
     page number scheme, cross-references, hidden paragraph overrides.
   - Then export the document to PDF from Word and review page by page.
   - Only say the task is complete after the PDF-level audit passes or after
     you clearly state the remaining manual visual checks.

## Style Strategy

- Treat styles as the single source of truth for formatting.
- Prefer these logical style buckets:
  - `Body Text`
  - `Heading 1` / `Heading 2` / `Heading 3`
  - `Figure Caption`
  - `Table Caption`
  - `References`
  - `Abstract`
  - `Keywords`
  - `Appendix Title`
- If the document already has equivalent styles, map to them and normalize
  their font, spacing, indentation, and numbering behavior.
- If direct formatting conflicts with styles, reduce the direct formatting and
  bring the document back under style control.
- Do not globally normalize sections that the school guide does not specify.
  Examples of high-risk overreach:
  - page header/footer redesign when the user only asked for headings
  - changing code box appearance when the task is only about references
  - normalizing table internals when the school guide does not regulate them
- When a visual issue remains after style normalization, inspect hidden OOXML
  state such as `firstLineChars`, numbering indentation, `titlePg`,
  `differentFirstPageHeaderFooter`, REF field display text, and direct run
  formatting.

## Audit-First Discipline

Before bulk editing, produce and internally follow a checklist like this:

1. Which parts are explicitly regulated by the school guide?
2. Which parts are user-defined house rules?
3. Which parts are currently acceptable and must be preserved?
4. Which problems are structural vs. visual-only?
5. Which fixes can be done safely through styles?
6. Which fixes require Word COM or OOXML-level patching?

Do not say "finished" merely because a structural audit looks good. For thesis
work, pagination and page-level rendering are part of correctness.

## High-Risk Pitfalls

Read `references/failure-patterns-and-quality-gates.md` before large-scale
formatting work. In particular, guard against:

- style names that look correct but map to the wrong style IDs
- paragraph-level direct formatting that overrides the intended style
- `firstLineChars` or numbering indentation creating invisible extra indents
- TOC fields or cross-reference fields showing stale display text
- section-level first-page settings causing missing headers or page numbers
- Word vs. WPS differences for table row height, vertical alignment, and code
  box title clipping
- punctuation normalization that accidentally rewrites DOI, URLs, code, or
  English references

## Visual Review Rule

For school-format-sensitive thesis work, final verification should prefer this
order:

1. Word COM/DOM structural checks
2. Word export to PDF
3. page-by-page PDF review
4. only then final delivery language

If page rendering cannot be verified, say so explicitly instead of implying the
 formatting is fully validated.

## Figure Rules

- Use Mermaid when a thesis figure is needed and the structure can be traced to
  real source material.
- Keep the diagram academically neutral and concise.
- Avoid decorative labels, chatty callouts, and speculative entities.
- Match the user's terminology unless it conflicts with the real materials.
- Read `references/figure-and-code-rules.md` before generating diagrams.

## Thesis Voice Rule

Read `references/thesis-voice-and-style.md` before generating or rewriting
body text. In particular:

- thesis prose must sound like thesis prose, not like notes about how the AI
  reasoned
- student-facing academic narration is preferred over review-style meta
  commentary
- do not leak the existence of source-feeding, code-ingestion, or analysis
  steps into the final paper text

Before finalizing thesis prose, quickly self-check:

1. Does the paragraph describe the system/research itself, rather than how the
   assistant inferred it?
2. Does the paragraph sound like thesis narration instead of prompt notes?
3. Does the paragraph avoid phrases like "根据现有代码", "根据已有工程",
   "通过分析用户提供的代码", or similar workflow-language?
4. Would the sentence still make sense if the reader had no idea an AI helped
   draft it?

## Code Listing Rules

- Prefer LaTeX-oriented code presentation when the thesis includes code
  listings.
- Keep the listing faithful to the actual code.
- Trim non-essential boilerplate when it does not support the thesis argument.
- If the user requests a specific LaTeX package or listing style, follow it.

## Resource Guide

- `scripts/check_word_com.ps1`
  - Detect whether Microsoft Word desktop and COM/DOM automation are available.
- `scripts/audit_docx_ooxml.py`
  - Audit DOCX styles, direct indentation, section settings, numbering, and REF
    field behavior before making risky formatting changes.
- `scripts/normalize_word_styles.ps1`
  - Batch-normalize thesis body text, Heading 1-3, figure captions, and table
    captions through Word COM automation.
- `scripts/export_word_pdf.ps1`
  - Export the current thesis document to PDF through Word COM for page-level
    review.
- `scripts/render_mermaid_figure.ps1`
  - Render Mermaid source into thesis-ready SVG, PNG, or PDF figure assets.
- `references/paper-format-workflow.md`
  - Read for the standard Word thesis formatting workflow.
- `references/figure-and-code-rules.md`
  - Read before generating Mermaid figures or LaTeX code listings.
- `references/thesis-voice-and-style.md`
  - Read before generating or rewriting thesis prose.
- `references/failure-patterns-and-quality-gates.md`
  - Read before large-scale formatting or before claiming the thesis is fully
    checked.
- `references/script-usage.md`
  - Read for command examples and config file conventions.

## Final Checks

- Confirm the document is still style-driven after edits.
- Confirm captions, numbering, page breaks, and table of contents are coherent.
- Confirm cross-references display the current target labels, not stale field
  text.
- Confirm section settings do not silently remove page headers or page numbers
  from first pages.
- Confirm references are formatted according to the school rules and that
  punctuation normalization did not damage DOI or English references.
- Confirm every diagram and code block is grounded in user-provided material.
- Export to PDF and inspect every page before saying the format is complete.
- If Word automation or PDF verification was unavailable, explicitly warn that
  layout fidelity was not guaranteed.