| name | detailed-article |
| description | Write or revise the detailed main article (index.md) of a spec-driven journal post from its spec.md contract, following the house record style (status highlight, MADR-inspired sections, cross-links). Use when asked to write, draft, expand, or revise a post's main article, index.md, or "the article modality" in _journals/*/posts/*/. |
Detailed Article (the index modality)
Goal
Write or revise index.md — the detailed main article of a post — from the
sibling spec.md. The article is the required, default modality: every
post has one, and it is the default tab on the rendered post page. Other
modalities (summary.md, dialog.md, comics.md) are derived from the spec
and this article; when the article changes substantively, flag sibling
modality files that may now be stale.
Contract rules
spec.md is the contract. Never edit spec.md from this skill. If the
requested article diverges from the spec's Intent or Success criteria, stop
and say so — either the user updates the spec first (spec-first rule) or
narrows the request.- If the post already exists and has moved beyond its spec, flag the drift:
suggest setting the spec's
status: drifted and updating revised: — but
let the user make that edit decision.
permalink: and id: front matter never change once published.
Workflow
- Read
spec.md (Intent, Audience, Success criteria, Non-goals, Modalities,
Sources) and the existing index.md if present.
- Skim 1-2 neighboring posts in the same journal for tone and section shape.
- Write/revise
index.md following the house style below.
- Walk the spec's Success criteria one by one and verify each against the
draft; report the checklist to the user.
- If this is a new post, wire it into
_journals/<journal>/config.yaml
(add - <slug>/index.md under the right section).
- Run
python3 _wiring/build.py; confirm [built] <journal> and that
docs/<journal>/<permalink>.html exists and embeds "key": "index".
House style
-
Front matter: title, date, author, excerpt, permalink,
timetoread, tags; ADR-shaped posts also carry id and
status: <state>:<colour> (e.g. proposed:orange, accepted:green).
-
Opening highlight before the first ## Heading. Two shapes — pick by
post kind:
-
ADR-shaped posts (decisions, principles, foundations) — a fixed
two-line status/decision blockquote:
> **Status**: PROPOSED
>
> **Decision**: One paragraph stating the decision clearly enough that a
> reader gets the direction before reading the body.
Use **Principle** instead of **Decision** for principle posts. Keep
the visible status aligned with the front-matter status: value.
-
Essay-shaped posts (e.g. the ai-notes journal) — a KEY POINTS
blockquote of exactly three bullets that capture the essence of the
essay: typically the problem, the core insight or symptom, and the
resolution. Three is the rule, not a range — force the synthesis down to
three even when the essay has many threads; collapse related ideas into a
single bullet rather than adding a fourth. Each bullet is one or two
sentences, leads with bolded key phrases, and stands on its own so a
skim reader gets the whole argument from the block alone.
> **KEY POINTS:**
>
> * **First essential point** — the problem or the gap, stated so it lands
> before the body.
> * **Second essential point** — the core insight, mechanism, or symptom
> that the essay turns on.
> * **Third essential point** — the resolution or the move it argues for.
<br>
Follow the block with a <br> before the lead paragraph, matching the
existing ai-notes posts.
-
Body order (MADR-inspired): Statement/Decision → How to Read This
→ Rationale → Implications → What This Means for Teams →
Anti-Patterns → Examples → Related Principles/cross-links →
Scope and Revisiting → Authoritative References. Sections may be
omitted, but keep the order.
-
Section headings use Title Case — capitalize principal words; keep articles,
coordinating conjunctions, and short prepositions (a, the, and, or,
to, by, in, of, for) lowercase unless first; capitalize the first
word after a colon. E.g. ## The Root: A Trap We Built by Being True to Ourselves, not ## The root: a trap we built by being true to ourselves.
Applies to every ##/### heading, including descriptive ones on reflective
posts. (The MADR section names above are already in this form.)
-
Tables of contrasts ("What it says / What it does not say") and
grouped bullets read well in the rendered HTML — prefer them over long
prose.
-
Cross-link related records with [[permalink]] rather than ad-hoc
text references. Link liberally — unresolved [[slugs]] survive the build
as visible TODOs.
-
Tone: declarative. Records are read by humans and by AI tools as
context.
-
Image references stay journal-root-relative (assets/images/...); put
files in the post's own assets/ folder.
