Override default LLM document formatting. Replaces wall-of-bullets, header spam, and AI prose tells with prose-first hierarchy, typographic rhythm, and intentional whitespace. Triggers on document creation, reports, guides, specs, and READMEs.
Instrucciones de origen · Vista previa de solo lectura
id
document-formatting-uplift
name
document-formatting-uplift
type
rigid
version
1.0.0
created
26/03/2026
modified
26/03/2026
status
active
metadata
{"author":"NodeJS-Starter-V1","locale":"en-AU"}
description
Override default LLM document formatting. Replaces wall-of-bullets, header spam, and AI prose tells with prose-first hierarchy, typographic rhythm, and intentional whitespace. Triggers on document creation, reports, guides, specs, and READMEs.
context
fork
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
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.
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
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
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.
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.
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.
