| name | haipipe-paper-to-word |
| description | Export ONE stage page's ## Content to a .docx for a coauthor who does not use LaTeX, carrying every citation, value and Display pointer in ANCHORED WORD COMMENTS authored as `haipipe`. The apparatus the LaTeX column drops survives here, bound to the exact digits. Ships in 4-ship beside to-overleaf: both move the argument to a target that is not the repo. Use when a coauthor or advisor must read and mark up a section, when the user says word, docx, send to my coauthor, 导出 word, or /haipipe-paper-to-word. NOT a venue delivery format: MISQ takes LaTeX, and the .docx never becomes authoritative. |
| allowed-tools | Bash, Read, Grep, Glob |
| metadata | {"version":"0.5.1","last_updated":"2026-07-30","summary":"md2docx.py turns one S page into a .docx whose apparatus rides in native Word comments (w:author=haipipe). Standard library only: pandoc cannot WRITE Word comments, so it cannot carry this exporter's central feature. Formats nothing itself: the in-text citation label and the reference list are read from .board-refs.bbl (generated by the paper's own .bst), the Display kind and \\label from the unit's float.tex, tables from assets/table-body.tex, figures from assets/figure.png. Executes the QC6 rulings of skills/diagrams/01-haipipe-paper-260725. History: ./CHANGELOG.md."} |
Skill: haipipe-paper-to-word
One stage page in, one .docx out, for one reader: a coauthor or advisor who
has to read the paper and mark it up and does not use LaTeX.
python3 <skill>/md2docx.py <0-lifecycle/4-main/S-Main-N-slug.md> \
--paper-root <paper dir> [-o out.docx] [--author NAME] [--no-displays] \
[--lanes Citation[,Value,Display]]
Default output is <paper-root>/3-dist/word/<page-stem>.docx. The folder is
NUMBERED because an export is machinery under the paper folder's delete test,
not part of the deliverable, and it is gitignored (JL 2026-07-27).
--lanes DEFAULTS TO Citation ALONE (JL 2026-07-28). All three evidence lanes
are evidence and all three are true, but one sentence of §1 drew five comments
and three were Display audits several hundred characters long: a display's
state: is a BOARD concern, and the coauthor in Word is checking the sentence.
Pass --lanes Citation,Value,Display for the full review copy. Whatever is held
back is COUNTED on the way out, never silently dropped.
⛔ ASK WHO THE ANNOTATOR IS BEFORE EXPORTING (JL 2026-07-27)
Never assume the comment author. Ask, every run, and say what the answer costs:
haipipe, the DEFAULT, is what QC6 reasoned for. The author field IS the
partition, so a coauthor opening the file can see at a glance which comments
are machine provenance and which came from a person, with no rule to
remember. Its cost is that "haipipe" means nothing to a reader who has never
heard of the toolchain.- A PERSON'S NAME,
--author "Junjie Luo", makes the markup read as theirs.
Initials are derived for the margin, so that one shows as JL. Its cost is
that the author no longer partitions anything, and the backport rule then has
to key off the LANE-TYPE PREFIX instead: every generated comment begins with
Value:, Note:, Display:, Citation: or Check:, and a human's own
comment begins with none of them.
The author is therefore a per-run fact rather than a property of the format.
Both behaviours are legitimate; guessing between them is not.
Why the apparatus becomes a comment
The LaTeX column DROPS every > Value:, > Citation: and > Display: lane at
generate time, so the provenance a human used to check the sentence is never
seen again. Word has a native mechanism that LaTeX does not: a comment anchored
to an arbitrary text range. So here the lane survives, bound to the exact
digits rather than to the paragraph.
THE COAUTHOR READS THE RECORD KEEPS
───────────────────────────── ──────────────────────────────────
normal prose, no markup every sentence unchanged
(Wang et al. 2022) 💬 key=wang2022physician
+9.34 💬 coef 9.343833 · SE 2.543594
exact p 2.39e-04 · N 767,736
run=v0618 · state=verified
a real, EDITABLE table 💬 display09 · kind=table
Figure 1 💬 display03 · kind=figure
⚖️ w:author="haipipe" is load-bearing, not cosmetic. It is what keeps
machine provenance separable from the coauthor's own comments, which arrive in
the same channel by design. Word's review pane filters on it. It is also what
makes the backport ruling mechanical: on the way back, haipipe is ours and
anything else is human input to route into the S page. Never change the author
string to something a person might also use.
This skill formats nothing
Every resolved thing is READ from a file the family already generates. That is
the whole reason there is no second bibliography to keep true.
.board-refs.bbl the in-text label AND the reference entry.
`\bibitem[{Wang et~al.(2022)Wang, Luo, …}]{key}`
packs both forms: SHORT(YEAR)FULL. Only the part
up to the year is the in-text call.
Written by haipipe-board/cli/refs.py with the
paper's OWN .bst.
displays/<unit>/float.tex the \label and the unit's kind. Kind is never
guessed from the label prefix.
displays/<unit>/assets/ table-body.tex -> a real w:tbl
figure.png -> an embedded image
A picture of a table is the wrong answer, because the coauthor you made the
file for cannot fix a typo in a picture. So a table is parsed into a real
w:tbl and stays editable.
What is read, and what is dropped
READ, and becomes the document
### <heading> a Heading style
prose sentences paragraphs, one source line each
\citep{} \citet{} the in-text label out of the .bbl
numbers verbatim
\ref{tab:…} \ref{fig:…} "Table N" / "Figure N", numbered by ORDER OF
APPEARANCE, which this exporter owns because
Word has no float and no \ref
> Value: > Citation: ANCHORED COMMENTS
> Display: > Check:
> Note:
DROPPED, and dropping it is correct
#### Pn. <job> scaffolding, not manuscript
the (…) preview line same
> JL: > CC: > USER: discussion, not evidence
### Stage Record the stage's own bookkeeping
### Stage Contract
[Q-X-n] the join key is bookkeeping; the comment
carries the probe path instead
Placement: Word has no float, so a unit lands immediately after the paragraph
that first mentions it.
An unresolved marker WARNS here, and blocks in LaTeX
\cite{TOADD} and {VAL:? …} are states, not text. The LaTeX column should
refuse to ship them, because a reviewer must never see [?] in a results
sentence. This column is the opposite: the file exists so a coauthor can see
where the paper stands, and a hidden hole is worse than a visible one. So the
export emits the marker, flags it in the run report, and continues.
⚠️ Two page shapes this cannot fix, and it reports both
Measured on the MISQ paper 2026-07-27, and neither is an exporter bug:
- A reference that lives only in a lane.
S-Main-1's citation keys appear
only inside backticks in its > Citation: lanes, so its prose cites nothing
and an export of it produces a section with no references. Eight of the nine
4-main pages have the same shape for DISPLAYS: only S-Main-4 carries a
\ref{} in prose at all.
- A placeholder reference.
Table [main-results] is prose, not a \ref{},
and names no unit. It is passed through and reported.
Both are ## Items to Finish work on the page, not something to paper over at
export time. Fixing them in the exporter would hide a defect that the LaTeX
column has too.
Where this sits
4-ship, beside haipipe-paper-to-overleaf: both move the argument to a
target that is not the repo. It is NOT a venue format. MISQ takes LaTeX, and
the .docx never becomes authoritative: a change that comes back in it is
backported into the S page.
The rulings this executes live on
skills/diagrams/01-haipipe-paper-260725/QO-delivery-build/QC6-sentence-to-word.md.
Change a rule there first.
