explainer-format
The shape of an `explainer` knowledge entry — the synthesized "how a feature works, as it exists now" artifact. Load this before writing or amending an explainer (hero synthesize / feature-knowledge-s
SKILL.md.claude/skills/explainer-format/SKILL.md
GitHubExplainer format
An explainer is a type: explainer knowledge entry that describes how a
shipped feature works, end to end, as it exists now — distinct from a
decision (why we chose something) or a convention (how we do a class of
things). It is synthesized from a cluster of completed specs and is meant to be
the single doc a newcomer reads instead of reverse-engineering the feature from
spec history.
In documentation terms this is the explanation (understanding-oriented)
quadrant of the Diátaxis framework — as opposed to
tutorials, how-to guides, or reference. decision entries are the adjacent
"why we chose" (ADR) category; explainers are the "how it works."
Explainers live at .hero/knowledge/explainers/<slug>/spec.md. They are
classified as knowledge (not work), so they are excluded from work rollups
(hero queue ranking, roadmap, in-flight strips).
Frontmatter contract
---
title: <human title of the feature>
type: explainer
synthesized_from: # provenance — the spec cluster (required, >=1)
- <spec-slug>
- <spec-slug>
last_synthesized: <YYYY-MM-DD> # required — when last synthesized/amended
source_initiative: <slug> # optional — set when the boundary was an initiative
tags: [...]
---
synthesized_from and last_synthesized are required: an explainer claims to
describe current reality, so it must name what it was built from and when.
hero check warns on an explainer missing either.
Section skeleton
Fill these in order. The synthesizer owns everything above ## Developer Notes; that section and below is human-owned.
- What it is — one-paragraph purpose.
- Surfaces / entry points — commands, MCP tools, files, UI a user touches.
- How it works — the key flows, in order.
- Data & state — what it reads / writes / persists.
- Gotchas — non-obvious constraints, sharp edges.
- Related decisions — links to existing
decisionentries by slug. Link, don't restate: a decision has one home. - Developer Notes — human-owned. Automated synthesis must never read or write below this heading.
Rules
- Link, don't restate. Reference
decision/conventionentries by slug rather than duplicating their content. - Never touch Developer Notes. Everything below that heading is human tribal knowledge; the synthesizer leaves it untouched on amend.
- Provenance is not optional. Always set
synthesized_fromandlast_synthesizedso a reader can judge staleness and an amend pass knows the coverage.