markdown-style

What this skill does

# markdown-style

The Markdown authoring and review skill. Owns two layers of rules and the procedure for applying them:

1. **Syntax canon** — what valid Markdown looks like. Derived from the Markdown Guide basic-syntax reference. Full canon: `references/syntax-canon.md`.
2. **Style overlay** — opinionated rules a reviewer enforces on top of valid syntax. Derived from Google's Markdown style guide. Full overlay: `references/style-overlay.md`.

Load this skill when the question is **"is this doc well-formed?"** — not **"does this doc belong here?"** (that is `doc-diagnostic`). Style review never decides whether a doc should exist. It assumes the doc earned its place and asks whether the prose, structure, and Markdown are clean.

## How to run a review

Run in two passes. Do not interleave them — the architect reads a syntax violation differently from a style violation, and conflating the two confuses the response.

### Pass 1 — Syntax (must-fix)

Walk the file top to bottom. For each construct that violates the syntax canon (setext heading where ATX is expected, unfenced code block, missing blank line around a block element, ordered list using `)` instead of `.`, etc.), emit one finding at a time:

```text
Line N:
  Original: <verbatim line(s)>
  Layer:    syntax
  Rule:     <one-line rule from references/syntax-canon.md>
  Rewrite:  <corrected line(s)>
  Apply?    yes / no / adjust
```

Wait for the architect's reply before flagging the next finding. No bulk edits. Syntax findings always come before style findings.

### Pass 2 — Style (should-fix)

Re-walk the file. For each violation of the style overlay (heading > H2 used as the document title, no `[TOC]` directive on a long doc, prose line > 80 characters outside an exception, uninformative link text like "here", reference link defined far from its use, generic repeated subheading like "Summary" under multiple parents, etc.), emit the same finding format with `Layer: style`.

The style pass is suggestion, not enforcement. The architect can decline any finding without justification — the rule is opinionated, not canonical. Reasonable disagreement is acceptable; flag it and move on.

### Apply approved findings

After both passes are complete, apply only the approved rewrites in a single Edit pass. No audit markers in the file. No `[reviewed]` stamps. The diff is the audit trail.

## The two layers — quick reference

Detailed rules live in `references/`. The summaries below cover the violations that account for most findings.

### Syntax (must-fix) — quick reference

| Construct           | Rule                                                                            |
|---------------------|---------------------------------------------------------------------------------|
| Headings            | ATX (`#`–`######`), space after `#`, blank lines before and after.              |
| Paragraphs          | Separated by a blank line. Do not indent.                                       |
| Line breaks         | Trailing-two-spaces is "controversial" (see style overlay). Prefer a paragraph break. |
| Emphasis            | `**bold**`, `*italic*`, `***both***`. Use asterisks mid-word (underscores break). |
| Blockquotes         | `>` prefix; `>` on the blank line between paragraphs; nest with `>>`.           |
| Ordered lists       | `1.` `2.` `3.` (period, not `)`). Start at 1. Numbering can be lazy.            |
| Unordered lists     | Choose one of `-` / `*` / `+` and do not mix within a list.                     |
| Nested list content | Indent 4 spaces (1 tab). Code inside a list item indents 8 spaces (2 tabs).     |
| Inline code         | Single backticks. Double backticks if the code contains a backtick.             |
| Code blocks         | Fenced (` ``` `) with a language tag. Indented blocks are valid but discouraged. |
| Horizontal rule     | Three or more `---` / `***` / `___` alone on a line with blank lines around.    |
| Links               | `[text](url)`. Autolink with `<https://…>`. Reference links resolve elsewhere.  |
| Images              | `![alt](path "title")`. Always include alt text.                                |
| Escapes             | Prefix the following with `\`: `` \ ` * _ { } [ ] < > ( ) # + - . ! | ``.       |
| Inline HTML         | Allowed. Separate block-level HTML with blank lines. Do not indent the tags.    |

Full canon with examples and known-broken edge cases: `references/syntax-canon.md`.

### Style (should-fix) — quick reference

| Concern               | Rule                                                                                          |
|-----------------------|-----------------------------------------------------------------------------------------------|
| H1                    | Exactly one H1, used as the document title. Subsequent headings start at H2.                  |
| Heading style         | ATX only. Do not use setext underlines.                                                       |
| Heading uniqueness    | Avoid repeating bare subheadings ("Summary", "Example") under multiple parents. Prefix them.  |
| Document skeleton     | Title -> optional author -> 1–3 sentence intro -> `[TOC]` -> `## Topic` sections -> `## See also`. |
| Table of contents     | Use `[TOC]` for any doc that would not fit on one laptop screen. Place between intro and first H2. |
| Line length           | 80 characters. Exceptions: links, tables, headings, code blocks. Text around a long link still wraps. |
| Trailing whitespace   | None. Prefer a paragraph break to the two-space line-break trick.                              |
| Lists                 | Lazy numbering (`1.` repeated) for long ordered lists; full numbering for short stable ones. Prefer lists to tables when the data is one-dimensional. |
| Code fencing          | Always fenced (` ``` `), never indented. Always declare a language. Escape shell newlines with `\`. |
| Links                 | Explicit repo-absolute paths (`/path/to/page.md`) over `https://…` for in-repo links. Avoid `../` traversal. |
| Link text             | Informative. Never "here", "link", or a raw URL.                                              |
| Reference links       | Use them in tables, when the URL hurts readability, or when the same target appears multiple times. Define them just before the next heading. |
| Tables                | Only for scannable two-dimensional data. Avoid prose cells. Cells cannot wrap.                |
| Images                | Sparingly. Always include alt text.                                                            |
| Capitalization        | Preserve product / tool / binary capitalization (`Markdown`, not `markdown`).                  |
| HTML in Markdown      | Avoid. Big tables are the only common exception.                                              |

Full overlay with rationales: `references/style-overlay.md`.

## Routing — what this skill does not own

- **"Should this doc exist?"** -> `doc-diagnostic` (four-question diagnostic).
- **"Is this ADR honest?"** -> `adr-critique` (line-by-line audit against the "ADR is NOT" checklist — a *content* audit, not a *form* audit). Style and ADR critique can run on the same file; run ADR critique first because supersession may invalidate style work.
- **"Where does this doc belong?"** -> `doc-diagnostic` alternatives catalog.
- **"Is the prose understandable?"** -> out of scope. This skill enforces Markdown form, not prose clarity. Suggest a `doc-diagnostic` Audience check if the prose is unfit for its named audience.

## What this skill does NOT cover

This skill is **Markdown form only.** It covers heading style, list indentation, code-fence language tags, link syntax, line length, and the rest of the Markdown-Guide / Google-style-overlay rule sets. It does **not** cover:

- **Prose-level enforcement** — terminology consistency, inclusive-language substitutions, banned phrases, voice / tense / mood rules. The next layer up for that work is