add-writing

Add a Writing

You are helping author a new long-form post in the _writings/ collection of this academic site. Every piece must read as if written by the same person and be typeset with the same components as the existing posts. This skill encodes both.

Three companion documents are authoritative and must be followed:

• WRITING-STYLE-GUIDE.md (repo root) governs voice, punctuation, and emphasis. Read it before drafting.
• references/components.md (in this skill folder) holds the exact copy-paste HTML for every formatting component. Read it before formatting.
• references/template.md (in this skill folder) is the canonical post skeleton. Copy it into _writings/<slug>.md and fill it in; keep the section order so every post is consistent.

The supporting CSS already lives in _sass/_writings.scss (compiled to /css/writings.css, loaded only on Writings pages); do not add new styles. Reuse the existing classes so a new post looks identical to the first. Never style Writings work in css/main.scss or _sass/_layout.scss: Writings changes must not touch any other part of the website.

The Page Style (why every post looks the same)

Consistency is not optional; it is the point. Every Writings post is typeset as a modernized journal offprint (redesigned July 2026: an 18.5px serif body in a 640px column, hierarchy from scale and space rather than ornament) and shares one fixed visual system. Do not redesign per post. The system is:

• Family: IBM Plex Serif body, IBM Plex Sans for labels/kickers. One accent colour, deep crimson #96172E, restricted to a small set of fixed jobs (link underlines, kicker marks, step numerals, timeline marks, aside rules, specimen labels). Warm off-white page.
• Fixed page furniture (applied by the post layout and stylesheet, never hand-coded): the header stack (kicker row "Writings · <Month D, YYYY> · <N> min read", the serif title, an italic standfirst rendered from summary, closed by a hairline rule; no byline, since the site header identifies the author), a sticky "On this page" contents rail on wide screens, ink-coloured links with a quiet crimson underline, and heading rhythm from space alone.
• A fixed component palette for everything else (numbered step headings, caveat aside, correspondence specimen, step/interval timeline, booktabs table, drawn-square checklist, revision history). Use these and only these; see references/components.md.
• What is banned, because it reads as generic or ornamental: emoji in the prose or components, coloured callout cards, sidebars, margin-note "Source" apparatus, drop caps, rules above headings, end-of-article marks, monospace transcripts, and any new bespoke styling. These were each tried and removed; do not reintroduce them.

If a post seems to need a component that does not exist, prefer restraint (plain prose) over inventing one. Raise it with the user before adding any new style to _sass/_writings.scss.

Task Overview

When invoked with /add-writing, you will:

1. Gather the topic, sources, and shape of the piece
2. Verify any process or factual claims against primary sources
3. Draft the post in the house style, saved to _writings/<slug>.md
4. Format it with the established components
5. Optimize any images and wire the hero as the social-card image
6. Build, verify style compliance, and open a PR

Step 1: Gather Information

Use AskUserQuestion to collect what you cannot infer. Ask only what you need:

• Topic and working title: what is the piece about?
• Type: is it a process/how-to guide (needs a caveat epigraph and a "last verified" posture, and its facts must be verified against primary sources) or a reflection/essay (no caveat needed)?
• Source material: does the user have notes, emails, a PDF, or links to draw from? These become the spine and the provenance. Ask them to point you to files or paste text.
• Hero image: is there one, should the user generate one, or none? If they want to generate one, offer detailed prompts (see Images below).
• Audience: who is it for? This sets how much to explain.

Do not ask about mechanics you can decide yourself (slug, date, file location).

Step 2: Verify Facts (process/guide posts)

If the piece states processes, deadlines, numbers, or institutional rules, verify each against the authoritative source with WebFetch before writing it down. Link that source inline in the prose. Never state a policy number from memory. Add a caveat epigraph ("checked against X as of <Month Year>") and keep the piece evergreen.

Provenance rule: attribution goes inline in the sentence, with a hyperlink to the source. Do not use margin notes, footnote apparatus, or "Source ·" labels; that approach was tried and removed.

Step 3: Start From the Template

Copy references/template.md into _writings/<slug>.md, where <slug> is short, kebab-case, and descriptive. The template already carries the front matter and the canonical section order; fill it in rather than composing structure from scratch. Front matter fields:

---
title: "Full Title in Sentence Case With Key Terms"
date: YYYY-MM-DD
summary: "One or two sentences. Shown on the /writings/ listing and used as the og:description and meta description. Follow the style guide here too (no em-dashes, no contractions)."
image: /resources/images/<slug>-hero.jpg   # optional; enables the hero + social card
version: 1                                  # optional; arXiv-style, shown only in the revision-history block
---

The post layout is applied automatically (via _config.yml defaults), which renders the kicker row (date, reading time), the serif title, the standfirst from summary, and the "On this page" rail. You do not add those.

Step 4: Write in the House Style

Read WRITING-STYLE-GUIDE.md and follow it exactly. The non-negotiables:

• Simple formal academic wording. First person. Direct, not stilted ("I think", not "One might consider").
• No em-dashes. Use a comma, colon, period, or parentheses. En-dashes in numeric ranges (6–7 weeks) are fine.
• No contractions. Write "do not", "it is", "you are". Possessives ("the examiner's report") are correct and required.
• Mix short and long sentences. Bold only load-bearing facts, sparingly. Italics for a word you would stress aloud or a term used as a term.
• Trust the reader; do not explain the obvious, preach, or pad with generic advice. State uncertainty plainly.
• Never include confidential material (names under embargo, private deliberations, personal contact details of others).

Step 5: Format With the Components

Read references/components.md for exact, copy-paste HTML. The palette, in the order it typically appears:

1. Hero figure (figure.writing-hero) right after the front matter, before the first paragraph. Corners are rounded by the stylesheet.
2. Opening paragraph in plain prose; the header stack and contents rail above it are automatic. Write normally.
3. Caveat aside (div.post-epigraph) for process posts: a roman aside behind a thin crimson left rule, styled to be read. Replaces any "disclaimer" blockquote.
4. Body in ##/### sections. Plain headings; for a genuine sequence, use the numbered step overline (## <span class="step-num">Step 1</span> Heading text, note the space after </span>).
5. Correspondence specimen (div.inbox-note) to quote an email or document verbatim: one uppercase source line (span.inbox-note-meta), then the transcript in the body serif. No emoji.
6. Step/interval timeline (ul.exam-timeline) for a sequential chain with intervals between steps. (The class name is historical; reuse it for any timeline.)
7. Tables: plain Markdown tables, automatically styled as booktabs (horizontal rules only).
8. Checklist: plain Markdown task list (- [ ]), automatically rendered with drawn squares.
9. Revision history (div.post-revisions) as end matter, linking to the post's real GitHub commit history.
10. Closing line: a direct invitation to email corrections, which fits the evergreen posture.

Provenance stays inline with links (Step 2). Do not reintroduce margin notes.

Step 6: Images

If a hero or figure image is provided:

1. Optimize it into resources/images/: roughly 1400px wide, JPEG quality ~82, target under ~200KB. Example: sips -s format jpeg -s formatOptions 82 --resampleWidth 1400 <src>.png --out resources/images/<slug>-hero.jpg
2. Set image: /resources/images/<slug>-hero.jpg in the front matter so it becomes the hero and the og:/Twitter card.
3. Write descriptive alt text.

If the user wants an AI-generated image, offer detailed prompts: flat minimalist editorial illustration, warm off-white (#FDFDFD) background, deep crimson (#96172E) as the sole accent, muted greys, no text/letters/watermark in the image, 2:1 for a hero. Ask them to generate and drop the file in the repo; you place and optimize it. Do not use two similar images in one post.

Step 7: Verify

1. Build: bundle exec jekyll build and confirm it completes cleanly.
2. Style check the rendered article body. Both counts must be zero:
   • em-dashes: grep -o "—" _site/writings/<slug>/index.html | wc -l
   • contractions: grep -oE "’(t|re|ll|ve|s|m|d)\b|n’t" _site/writings/<slug>/index.html | wc -l (inspect any hits; possessive 's is allowed, contractions are not)
3. Confirm the post appears on /writings/ and every link resolves.

Step 8: Publish

Follow the repo's git conventions (see CLAUDE.md):

• Branch: add-writing-<slug> (or a short descriptive name).
• Commit message: describe the post; never add "Generated with Claude Code" or "Co-Authored-By: Claude".
• Never add "Closes #XX" / "Fixes #XX" unless the user explicitly asks.
• Push and open a PR summarizing the piece and its components.

Note the Writings nav tab stays hidden until _writings/ holds at least 3 posts (threshold in `_includes/hea

Content truncated.