| name | document-restructure |
| description | Reorganize a document into new sections while preserving the author's exact words: SOUL.md, constitutions, READMEs, specs, plans, style guides. Use when the user says 'put my words into new sections', 'use the exact same words', 'reorganize this', 'what if the headers were X', 'try a different structure', or rejects your rewrite because the LANGUAGE is bad rather than the idea. Restructure is not editing and not rewriting: not one sentence may change. For improving the prose itself use writer or evaluate-content; for scoring a SOUL.md use soul-md-audit. |
Document Restructure
Reorganizing a document is a third mode, separate from drafting and from editing.
The words are fine. The arrangement is the problem. Nothing you produce here
may contain a sentence the author did not write.
When this fires
- "Put my words into new sections."
- "Use the exact same words, just reorganize."
- "Make a version with these headers: ..."
- "Are you sure those are the right sections?"
- The user rejected your rewrite with a complaint about the language, not the
idea. That is a restructure request wearing a critique costume.
The failure this exists to prevent
The user asks to reorganize a document. You hand back a shorter version in your
own voice. They tell you the language is crap and ask again, this time spelling
out "use the exact same words." You burned two turns producing prose nobody
wanted.
The tell is that you are proud of a sentence. In a restructure you should not
have written any sentences to be proud of. If your output reads better than the
input, you did the wrong job.
Rules
- Copy sentences out of the source verbatim. Whole, unsmoothed, unmerged,
unshortened, including the bold, the backticks, the arrows, the parentheticals
you find ugly. The ONLY thing that changes is which section a sentence lives
under and in what order.
- Verify by char count and report it. A pure restructure lands within a few
hundred chars of the original. Print both numbers. Coming back 40% shorter
means you rewrote and lost constraints; that is a failed restructure, not a
bonus simplification. This is the single cheapest proof that you obeyed rule 1.
- If they hand you headers, use them exactly, in the order given. Do not
improve the names, do not add a section, do not merge two.
- Ship real files, one per candidate. Nobody can compare two arrangements
from a prose description of them. Write
doc.opt1.md, doc.opt2.md, and
deliver them. Never overwrite the live original without explicit approval.
- Name the judgment calls, briefly. Which section swallowed the contested
content, and why. In a restructure, that is the only real decision you made,
so it is the only thing worth saying in the reply. Two sentences, not a tour.
Generating candidate arrangements
When asked for several, run quick-brainstorm first, and make each candidate a
different organizing principle, not a variation on one. A set of candidates
that are all "topic buckets, slightly regrouped" is a failed brainstorm.
The schemes, and what each one trades:
references/restructure-schemes.md.
State your pick and why, then build the files. Recommend, do not survey.
Cross-check against the document's own opening line. The strongest
arrangement is often already stated in the doc's first paragraph. If a file opens
with "rules are either gates or defaults," then gates/defaults IS the table of
contents, and every other scheme is one the reader has to learn separately. When
the first line can serve as the table of contents, that is usually the answer.
Diagrams during a restructure conversation
These conversations are structural, so they are diagram-shaped: before/after
section maps, what-moved-where, candidate comparisons. Draw them.
The trap: a diagram about restructuring a doc is itself writing, and the same
plain-language bar applies to the words inside the boxes. Jargon that survives in
a diagram ("attention budget", "monotonic growth", "filing system vs habit")
reads as terrible to a user who just asked for plain words. Before rendering,
read every string in the SVG as if it were a sentence in the reply, and put it
through the same test: would he say "no idea what you mean"?
Pitfalls
- Restructuring and simplifying at once. Two changes the user cannot evaluate
separately. If they want both, do the restructure, get it accepted, then offer
the simplify pass as a second step.
- Silently dropping the section you thought was redundant. Every line of the
source lands somewhere in the output. If two lines genuinely duplicate, keep
both and say so; the dedup is a separate decision they get to make.
- Describing the layouts instead of building them. Prose about "four beats vs
three buckets" is unreadable. Files are cheap. Build them.
- Improving their header names. They picked those words. Use those words.
- Assuming your first sectioning is right. When a user asks "are you sure
those are the sections?", the answer is usually no. Treat the first arrangement
as a draft of the scheme, not the deliverable.
Related
writer for changing the actual prose (drafting and revision).evaluate-content for scoring copy quality and the Seven Sweeps.soul-md-audit for scoring a SOUL.md against Hermes loading mechanics; its
Simplify pass is the word-changing counterpart to this skill.quick-brainstorm for generating the candidate schemes.
