| name | haipipe-paper-restructure |
| description | Migrate an existing paper into the layout ruled 2026-07-26 (design board QA6, the delete test): un-number the deliverable, split a monolithic driver into sections/ + appendices/, rewire the \input tree, normalize NN-MM naming, unitize loose assets into displays/unit/assets/, move the build script to 2-src/. Prose stays byte-identical; gated by prose parity + compile parity + the delete test. Also handles in-layout repairs: renumber after deletes, rehouse stray assets. Trigger: restructure paper, migrate paper layout, un-number a paper, convert 0-sections to sections, delete test failing, renumber sections, close numbering gap, /haipipe-paper-restructure. |
| allowed-tools | Bash, Read, Write, Edit, Grep, Glob, AskUserQuestion |
| metadata | {"argument_hint":"[paper-dir] [--plan-only] [--repair]","version":"0.2.0","last_updated":"2026-07-26","summary":"Existing paper → the ruled layout; prose byte-identical, compile verified, delete test passing."} |
Skill: haipipe-paper-restructure (3-deliver)
Re-house an existing paper in the layout ruled on the design board (QA6) without changing a
single sentence. Two modes:
- Migrate (default): the folder does not conform at all: a monolithic driver, a numbered
deliverable,
0-sections/, 0-displays/, loose figures/, 1-compile.sh at the root.
Produce the full ruled tree.
- Repair (
--repair): the folder already follows the layout but has drifted: numbering gaps
after a delete, a leaf never \input, an asset outside its unit.
Fix only the findings (usually handed over from haipipe-paper-conform).
Not this skill: creating a paper from nothing (haipipe-paper-folder, Board-first and minimal),
adding the LaTeX toolchain to a paper that never had one (haipipe-paper-scaffold), or any wording
change (the section stage).
The target layout, and the test that defines it
The NUMBER is the delete test. rm -rf 0-* 1-* 2-* must leave a paper that still compiles and
still submits. Migration is largely the work of making that true.
NUMBERED, working machinery 0-lifecycle/ the board, including nested topic probes
2-src/ how the deliverable is BUILT
UNNUMBERED, the deliverable <paper>.tex · <paper>.bib · <paper>.pdf
sections/ · appendices/ · displays/
<venue>.cls · <venue>.bst
The most common migration is therefore a RENAME, not a split: 0-<paper>.tex loses its prefix,
0-sections/ becomes sections/, 0-displays/ becomes displays/, 1-compile.sh moves into
2-src/. Do not treat that as cosmetic: while the prefix is there, the delete test deletes the
manuscript.
There is no top-level figures/ and no Figure//Table/ bucket. A display is a UNIT and its render
lives in displays/displayNN-<slug>/assets/. Loose assets are unitized during migration.
Usage
/haipipe-paper-restructure paper/ migrate to the ruled layout
/haipipe-paper-restructure paper/ --plan-only propose the mapping, change nothing
/haipipe-paper-restructure paper/ --repair fix structure-check findings only
The two gates (non-negotiable)
Every restructure run must pass both before it may report ok:
| Gate | Check |
|---|
| Prose parity | Concatenate all non-comment body text before and after (strip %-lines, \input lines, whitespace); the two streams must be identical. Moving, splitting, and renaming files is allowed; rewording is not. |
| Compile parity | Compile before (if it compiled) and after; after must produce a PDF for every master. Compare page counts; explain any delta (a pure restructure should be ±0). |
| The delete test | haipipe-paper-conform block J must pass: no target the deliverable reaches, and no master, .bib, .cls or .bst, sits behind a 0-/1-/2- prefix. This is the gate that says the migration actually happened. |
Snapshot first: refuse to run on a dirty git tree, or create a wip-restructure commit/stash so the migration is one reviewable diff.
Workflow (migrate mode)
Phase 1: Inventory
- Find the real source of truth: which
.tex has \documentclass and is actually compiled (check build scripts, Makefile, latexmkrc, newest PDF).
- Map its structure:
\section / \subsection tree, where the prose physically lives, every \input/\include, every \includegraphics path, the .bib, style files.
- Detect existing fragments worth keeping (a partial
sections/ split is remapped, not flattened back).
Phase 2: Mapping plan (always shown to the user)
Produce a migration table and stop for approval (this is the whole output under --plan-only):
SOURCE (today) → TARGET (the ruled layout)
0-<paper>.tex preamble+title → <paper>.tex (driver, UN-NUMBERED)
0-<paper>.tex §Results intro → sections/02-00_overview.tex (leaf)
0-<paper>.tex §Results/Subsec "Traits" → sections/02-01_trait-targets.tex
0-sections/methods.tex (whole) → sections/04_methods.tex + 04-0M leaves (split at \subsection)
0-sections/A_prompts.tex → appendices/A_prompts.tex
0-displays/ (as a folder) → displays/ (rename; units keep their shape)
figures/pipeline.pdf → displays/displayNN-pipeline/assets/pipeline.pdf (+ rewrite path)
0-displays/Figure/main-result.pdf → displays/displayNN-main-result/assets/… (unitize the flat bucket)
0-<paper>.bib → <paper>.bib (+ rewrite \bibliography)
1-compile.sh · 1-config.yaml → 2-src/compile.sh · 2-src/config.yaml
0-extra/ · 1-board/ (empty or junk) → _archive/ or deletion, ASK; never silently drop
Naming decisions (NN order per venue, slugs from subsection titles) are made here, once, and the user approves them here, once.
Phase 3: Execute
git mv / copy content per the table; cut at heading boundaries only, taking each heading's trailing comments and floats with it.- Build the driver: preamble +
\section{} + \input lines (driver owns headings; strip \section{}/\subsection{} lines that became filenames or remain as the task-folder's first line, per 2-phase/REF/tex-file-anatomy.md).
- Build wrappers for sections with multiple leaves; pure
\input lines.
- Rewrite every path that moved:
\includegraphics, table \input, \bibliography.
- Install
2-src/compile.sh from ../haipipe-paper-scaffold/templates/compile.sh.tpl if no conforming build script exists; chmod +x. If one exists at the old root path, git mv it and fix its internal paths, which are root-relative.
- Leave
0-lifecycle/ alone. It is the board; migrating it is /haipipe-board's job, not this skill's, and its purity is checked separately by conform block D.
- Do not create a
STATUS.md. STATUS.md is RETIRED (design board QA6, 260726): the frontier is derived from disk, the venue pin lives on S-Venue-0-venue.md's state: line, and the Gate Ledger lives in each S page's ## Log. If one exists, migrate its gate rows onto their S pages FIRST, then remove it, and say in the report which rows moved where. Never drop a ledger row: it is history, and it is the only part of that file that cannot be re-derived.
Phase 4: Verify
- Prose-parity gate (script it inline: strip-and-diff; show the diff if it fails and stop).
- Compile-parity gate via
2-src/compile.sh, run from the paper root.
../haipipe-paper-conform/scripts/check_structure.sh . → exit 0. Quote block J's line explicitly in the report: it is the whole point of the migration.- Report the file-mapping table again as the change log; suggest a commit message.
Repair mode (--repair)
Input is a finding list (typically haipipe-paper-conform output).
For each finding apply the standard remedy, then re-run both gates once at the end:
| Finding | Remedy |
|---|
Numbering gap (04-05 missing) | Rename downstream leaves up by one and rewire their \input lines in the same pass; never leave a gap or a dangling input. Stable-ids and \labels do not change. |
Orphan leaf (never \input) | Ask: wire it in (where?) or retire it to _old/; never silently delete. |
| Wrapper contains prose | Move the prose into the correct leaf (existing or new NN-MM); wrapper returns to pure \input. |
| Display asset outside its unit | Move it to displays/<unit>/assets/, rewrite the referencing path. Never into a figures/ or Figure/ bucket: those are the shape being migrated away from. |
| A numbered file the deliverable needs | Drop the prefix, rewrite every reference in the same pass. This is a delete-test failure, the most severe finding there is. |
| Aux files lingering | 2-src/compile.sh --clean-only. |
Return contract
status: ok | blocked | failed
summary: mode, files moved/split/renamed, both gate results (explicit pass/fail)
artifacts: [mapping table, touched paths]
next: /haipipe-paper-conform (re-audit) or the section stage (resume prose work)
