Document formatting uplift
LLMs produce documents with predictable failure modes: bullet walls where paragraphs belong, four levels of headings for a single idea, and filler phrases that signal machine authorship. This skill replaces those defaults with prose-first hierarchy, deliberate whitespace, and direct language.
The skill is rigid. Every document produced under its governance must pass the eval criteria at the end of this file. There are no soft recommendations here — each rule exists because its violation is detectable and its correction is measurable.
When to apply
Positive triggers
Activate this skill when the task involves producing or revising written documents:
- "write a document", "write a report", "write a guide", "format document"
- README creation or revision
- Specification, proposal, or architecture document authoring
- "documentation style", "technical writing", "formatting"
- Any task where the primary output is a Markdown or prose document
Negative triggers
Do not activate for tasks where the output is primarily code, configuration, or data:
- Code-only implementations (use
tddinstead) - API route or endpoint creation
- Test file authoring
- Database migrations or schema changes
- Git operations, CI/CD configuration
Banned defaults
Twelve anti-patterns that LLMs produce by default. Each is banned unconditionally.
| # | Banned pattern | Why it's bad | Replacement |
|---|---|---|---|
| 1 | Wall of bullets for connected ideas | Fragments relationships between concepts; forces the reader to reconstruct the narrative | Prose paragraphs that link cause to effect, context to consequence |
| 2 | H2 to H3 to H4 nesting for one paragraph of content | Creates visual noise and false hierarchy; a single paragraph does not warrant three heading levels | Appropriate heading depth — maximum 2 levels per section |
| 3 | Opening a section by restating the heading | Wastes the reader's time; they already read the heading | Lead with the actual content — the first sentence should advance understanding |
| 4 | "Let's dive in", "Here's a comprehensive overview", "In conclusion" | Filler phrases that signal machine authorship and add zero information | Direct opening sentence that delivers content immediately |
| 5 | "It's worth noting", "It's important to mention", "As we can see" | Hedge phrases that pad word count while diluting authority | Delete entirely — if it's worth noting, just note it |
| 6 | Every list item starting with bold text + dash | Creates monotonous visual rhythm and buries the actual content | Mix formatting as content demands — bold only when emphasis is warranted |
| 7 | Overuse of "Key" prefix ("Key features", "Key benefits", "Key takeaways") | Generic qualifier that communicates nothing; everything in a document should be key | Use specific nouns — "Authentication methods", "Cost drivers", "Performance bottlenecks" |
| 8 | Three-column comparison tables for prose content | Forces nuanced comparisons into rigid cells; truncates reasoning | Prose with inline comparisons, or two-column tables when data is genuinely tabular |
| 9 | Exclamation marks in technical documentation | Unprofessional tone; reads as marketing copy rather than engineering communication | Period or no punctuation. Technical docs inform, they do not exclaim |
| 10 | Generic section ordering (Overview, Features, Getting Started) | Cookie-cutter structure ignores what the reader actually needs first | Content-appropriate structure driven by the document's purpose and audience |
| 11 | Emoji in headers or bullet points | Visual clutter that degrades scannability and prints poorly | Words only in technical documentation |
| 12 | Code blocks for non-code content | Misuses monospace formatting; makes text harder to read and copy | Proper formatting — bold, italics, blockquotes as semantics demand |
Reference: See references/anti-patterns.md for full before/after examples of each pattern.
Replacement standards
These rules govern all document output when this skill is active.
Prose-first principle
Default to paragraphs. A bullet list is appropriate only when the items are genuinely unordered, independent, and benefit from visual separation. If the items form a sequence, tell a story, or build on each other, write them as prose.
Connected ideas demand connected prose. The paragraph is the fundamental unit of technical writing because it preserves the relationships between statements — cause and effect, condition and consequence, claim and evidence. Bullets destroy these relationships by isolating each statement into a fragment.
Heading discipline
Use a maximum of two heading levels per page section. An H2 introduces a major section; an H3 may subdivide it if the content genuinely warrants subdivision. H4 and deeper headings are banned except in reference documentation with established hierarchies (API docs with method/parameter/return structure).
Every heading must use sentence case. Title Case Looks Like Marketing Copy. Sentence case reads as technical communication.
Whitespace rhythm
Apply geometric spacing ratios: section gaps are larger than paragraph gaps, which are larger than line gaps. In Markdown this means a blank line between paragraphs and two blank lines before a new H2 section. The reader's eye uses whitespace to parse document structure before reading a single word.
Table usage
Tables are for structured data with consistent columns — configuration values, API parameters, comparison matrices with discrete values. If a cell would contain more than one sentence, the content belongs in prose. A table that compares two approaches across subjective dimensions (flexibility, maintainability, team preference) is nearly always better as prose.
Opening sentences
The first sentence of any section must deliver content. It must not summarise what the section will cover, restate the heading, or welcome the reader. The reader chose to read this section — respect that choice by giving them information immediately.
Styling references
For Scientific Luxury projects, apply references/standards.md — spectral colour annotations, OLED-friendly contrast, JetBrains Mono for data, Editorial New for titles.
For all other projects, apply references/standards-generic.md — system fonts, 1.25 typographic scale, minimal borders, professional whitespace.
Document archetypes
Five document types with prescribed structures. Each structure exists because it matches how the target audience reads that type of document.
Technical specification
Structure: Problem, Approach, Design, Implementation, Verification
The reader is an engineer who needs to understand what is being built and why. Lead with the problem because engineers evaluate solutions against the problem they solve. The approach section justifies the chosen path — what alternatives were considered and why this one won. Design covers architecture and data flow. Implementation is a phased plan with concrete deliverables. Verification defines how the team will know the spec has been fulfilled.
Template: assets/templates/scientific-luxury/technical-spec.md or assets/templates/generic/technical-spec.md
User guide
Structure: Goal, Prerequisites, Steps, Troubleshooting
The reader wants to accomplish a specific task. State the goal so they can confirm they are reading the right document. List prerequisites so they can verify readiness before starting. Steps are sequential and numbered — this is the one context where an ordered list is correct. Troubleshooting addresses the failure modes that actual users encounter, not theoretical edge cases.
Template: assets/templates/scientific-luxury/user-guide.md or assets/templates/generic/user-guide.md
Report
Structure: Summary, Findings, Evidence, Recommendations
The reader is a decision-maker who may read only the summary. The summary must stand alone — it contains the conclusion, not a preview of the conclusion. Findings present the data. Evidence supports the findings with specifics. Recommendations are actionable and tied to specific findings.
Proposal
Structure: Context, Problem, Solution, Cost, Timeline
The reader needs to decide whether to invest resources. Context establishes shared understanding. The problem statement must be specific enough that the reader can verify they agree it is a problem. The solution addresses the stated problem directly. Cost and timeline are honest — padding estimates erodes trust.
README
Structure: What, Why, Quick start, Architecture, Contributing
The reader is evaluating whether to use or contribute to the project. "What" is a single sentence. "Why" explains the problem this solves. Quick start gets them running in under five minutes. Architecture is a high-level map for orientation. Contributing tells them how to participate.
en-AU enforcement
All documents produced under this skill must use Australian English spelling and conventions.
Spelling: colour, behaviour, optimisation, organised, licence (noun), analyse, centre, defence, honour, programme (but "program" for software).
Dates use DD/MM/YYYY format. Currency uses AUD ($). Times reference AEST or AEDT. Sentence case for all headings.
Eval criteria
Every document produced under this skill must pass all eight checks. A single failure means the document requires revision.
| # | Criterion | PASS condition |
|---|---|---|
| 1 | Prose-first | Connected ideas are in paragraphs, not bullet lists. Bullets used only for genuinely unordered, independent items. |
| 2 | Heading discipline | Maximum 2 heading levels per section. No H4 or deeper except in API reference docs. Sentence case throughout. |
| 3 | No filler phrases | Zero instances of "Let's dive in", "It's worth noting", "comprehensive overview", "In conclusion", or equivalent. |
| 4 | Direct openings | Every section's first sentence delivers content. No restatements of the heading. No "In this section, we will..." |
| 5 | Appropriate tables | Every table has structured, consistently-typed data. No table cells contain more than one sentence. |
| 6 | No banned formatting | No emoji in headers. No code blocks for non-code. No exclamation marks. No bold-dash list pattern throughout. |
| 7 | en-AU compliance | Australian spelling, DD/MM/YYYY dates, AUD currency, sentence case headings. |
| 8 | Archetype alignment | Document follows the prescribed structure for its type, or has a justified reason for deviation documented in a comment. |
Run this checklist mentally before declaring any document task complete. If any criterion fails, fix it before delivering.