harbor-exposition

license	Apache-2.0
name	harbor-exposition
description	House style for writing up research results: the seven-moves-plus-two-rails template (scene, one-breath sentence, structural analogy, boxed theorem, hand-checkable numbers, application, honest boundary — with an expert express lane and mandated relation-map/regime figures). Use when drafting, reviewing, or converting any Harbor-program result, execution report, paper section, README, or technical explainer for a smart-but-uninitiated reader. NOT for API reference docs, marketing copy, code comments, or doing the underlying proof/derivation work itself.
allowed-tools	Read,Write,Edit
metadata	{"category":"Writing & Communication","tags":["exposition","house-style","technical-writing","seven-moves","harbor"],"version":"1.0.0","pairs-with":[{"skill":"harbor-results","reason":"Supplies the results this style is used to present"},{"skill":"falsification-first","reason":"The honest-boundary move depends on the falsification discipline's outputs"}]}

Harbor Exposition: Seven Moves + Two Rails

Present every result so a smart engineer who has never read the source volume believes it before they see it formalized — and knows exactly where it stops holding.

When to Use

✅ Use for: writing or reviewing result write-ups, execution reports, paper sections, explainer posts, or converting an existing formal/terse draft to house style; deciding figure and notation choices for a technical piece. ❌ NOT for: API/reference documentation, marketing or landing-page copy, commit messages or code comments, or producing the proofs/derivations/experiments themselves (do those first; this skill presents them).

Core Process

flowchart TD
  A[Result in hand: statement + numbers + boundary] --> B[Rail A: write the express lane\none-breath sentence + pointer to the box]
  B --> C[Move 1: the scene\nconcrete situation, zero jargon]
  C --> D[Move 2: the idea in one breath\nsingle italic sentence]
  D --> E[Move 3: structural analogy\nrelations map, not surface features\nintroduce symbols at first use\nend with the misread to preempt]
  E --> F[Move 4: THE BOX\nprecise statement, self-contained,\nreadable cold by the expert path]
  F --> G[Move 5: numbers by hand\ntiny worked example, then FADE:\nhand the reader the next case]
  G --> H[Move 6: what it buys\nthe concrete application]
  H --> I[Move 7: honest boundary\nas prominent as the claim]
  I --> J{Rail B: two figures present?\nrelation-map + regime diagram}
  J -->|no| E
  J -->|yes| K{Done-tests pass?\nexpert: express lane + box stand alone\nnovice: can restate the one-breath line}
  K -->|no| C
  K -->|yes| L[Ship]

The Two Rails (run the length of every piece)

• Rail A — two reading paths. Open with a one-sentence express lane (the Move-2 sentence + "formal statement in the box"). Experts read it and jump to the box; everyone else reads straight through. Counters the expertise-reversal effect.
• Rail B — visual discipline. Exactly two figures per piece, reusing one program-wide grammar: a relation-map for the analogy (base ∥ target ∥ correspondence arrows) and a regime diagram for the boundary (axes = key parameters; shaded = where the result holds). Keep figure cost far below Distill's ~100-hour failure threshold.

Anti-Patterns

Definitions First

Novice: "Define all terms and notation up front, then use them." Expert: Terms earn their definitions through use; the formal box comes only after the reader already believes the claim (Sanderson's concrete-before-abstract; Tao's pre-rigorous stage; Sweller & Cooper's worked-example effect). Timeline: Halmos 1970 said it; cognitive-load research confirmed it experimentally (1985, 2003); codified here 2026-08. Detection: A "Notation" or "Preliminaries" section before any motivating example.

Boundary Burial

Novice: Caveats go in a trailing clause or footnote so the result looks strong. Expert: The boundary is a full move with its own regime diagram — what the result does NOT say, as prominent as what it does. A result without a boundary paragraph is not done (Halmos: "honesty is the best policy"). Detection: The word "however" carrying the entire limitation load in one sentence; no regime figure.

One Path For All Readers

Novice: One linear narrative serves everyone. Expert: Scaffolding that helps novices is redundant load for experts (expertise-reversal, Kalyuga 2003). Ship the express lane; make the box self-contained so it can be read cold. Detection: An expert must wade through the story to find the theorem statement.

Vibe Anomaly / Uncalibrated Analogy

Novice: Pick an analogy that "feels like" the topic (surface features). Expert: Analogies must map relations (Gentner structure-mapping): the reader should be able to derive new true facts about the target from the analogy. End every analogy with the predictable misread it invites, preempted. Detection: The analogy cannot survive one "so does that mean…?" question.

References

• references/style-template-v2.md — Read when actually drafting or reviewing a piece: per-move craft guidance, done-tests, figure grammar, notation rules, numeric-claim provenance policy, LaTeX skeleton.
• references/exposition-principles.md — Read when justifying a style decision, teaching the style, or evolving the template: the 14 evidence-backed principles with citations and the v1→v2 critique rationale.
• examples/worked-exemplar-R7.md — Read when unsure how a move should feel in practice: a fully annotated exemplar (the inspection tower) with each move labeled.

Scripts

• python3 scripts/check_style.py <draft.md|draft.tex> — the done-test linter: checks express lane, one-breath line, the box, the "Now you try" fade, misread-to-preempt (warn-only; waive consciously), honest boundary, and [verified]/[internal] provenance tags; exit 1 if a required check fails. Run before shipping any piece; sanity-check it against examples/worked-exemplar-R7.md (passes 7/7).