chalk: give the mindmap format its own skill, and a goal-tree companion

[jarohen]

tl;dr

Chalk has always specified the voice of a commit body, issue or PR description. It now specifies the shape as well — nested bullets whose parents are claims and whose children back them up — in a skill of its own.

• What changes in practice: the reasoning in an artefact goes into a tree whose top lines can be read on their own, instead of a paragraph the reader has to hold in their head. Commit bodies get this for the first time.
• Two new skills: chalk:mindmap for the shape, chalk:goal-tree for direction — where a node's children accomplish it rather than argue for it. Both are loaded by the skills you already use; there's nothing new to invoke.
• The format isn't speculative — the newest xtdb issues and PRs are already written in it, and this description is too. "The format in practice" below links them.
• Why it needs writing down: only half of it was in the plugin, so adoption is uneven. Ten of today's twenty-one xtdb issues and PRs open with a tl;dr; of today's seventeen commits, eight carry a tree and nine don't — chalk never asked a commit body for one.
• Who an artefact is written for is now stated rather than assumed — nearly always a teammate, which includes you in six months and a future agent session starting cold. That rule generalises a real failure: the first draft of this description opened on which half of the format had landed in an earlier commit, which is unreadable to anyone who hadn't seen it.
• The question for a reviewer isn't whether the rules are right in the abstract. It's whether the linked examples read better than the prose they'd otherwise have been.

Context / Motivation

99d6166 brought the tree's mechanics into chalk:voice — one checkpoint per bullet, lead with the point, bold the load-bearing words, nest shallow, cut hard — and stopped there.

• The half that landed was the less useful half. Nothing said what the nesting means: that a parent is a claim and its children are what back it up. Formatting rules without that relation produce a list with indentation, which reads as structured and carries no argument. A model can satisfy every rule in 99d6166 and still write one.
• Commit bodies were left out entirely. Chalk described a body as "a single explanation, not a sectioned document" and never asked for a tree — which is exactly how the same reasoning ends up bulleted in a PR description and as prose in the commit that carries it.
• Goal trees weren't covered at all, though issue descriptions routinely carry direction, and that's the one place a completeness question has a real answer rather than a gesture at one.

The format in practice

Start with this description. It opens with a tl;dr, draws its sections from chalk's palette, and writes each one as a tree — so the thing under review is a sample of its own output. If it doesn't read better than the prose equivalent would have, that's the argument against merging it.

Then the two PRs in xtdb/xtdb that were written against the skills on this branch — so unlike the rest of the repo, they're output from the change under review rather than prior art it generalises. They're the same discipline applied to opposite situations, which is the useful thing about the pair:

• #5883, stopping a stalled object store taking a node down — where nothing changes for the reader. Its tl;dr answers their questions instead of recapping the work: what no longer happens, that nothing user-facing changes (no config key, no migration), the one thing to act on if you implement ObjectStore (it's now suspend), and what moved off the shared dispatcher. Implementation notes names its own decomposition — "four things a reviewer would otherwise have to reconstruct from the diff" — and Changes gives five commits in reading order, flagging which two are behaviour-preserving.
• #5860, driving xtdb.api over FlightSQL — where something does. A new capability, so the tl;dr says it's purely additive and a Usage section carries what to actually do: a runnable snippet, which option is required and what the rest default to, and the session semantics of holding a connection. It states its one live limitation in the tl;dr rather than letting a reader hit it, and cites D4 inline as a pointer into the decision rationale below.

Two issues from today are worth a look for the tagging, which neither PR needed — #5879 and #5873, both flaky-test reports whose tl;dr is the triage: idea: for an untried fix direction, assumption: for a diagnosis not yet confirmed, check: for what must be verified before anyone relies on it.

Adoption across the rest of the repo is uneven, which is the case for specifying it. Ten of today's twenty-one issues and PRs carry a tl;dr; #5865 and #5870 use the palette's sections and open with prose. Commit bodies lag further — eight of today's seventeen carry a tree, nine don't — exactly what you'd expect from guidance that asked PRs for structure and never asked commits for any. PR #5869 against the commit it carries, ccb11a6d, is that gap in a single pair: the same reasoning as a tree in the description and as four prose paragraphs in the commit.

Future state

Three skills, split by what they decide, so no rule has two homes.

• chalk:voice — the register and the palette. What the reader is for (Diataxis), what earns a sentence, which sections exist. Unchanged in job; it now points at the other two instead of carrying tree mechanics inline.
• chalk:mindmap — the shape of anything followable. The parent/child relation, and the rules that only make sense once it holds: subject lines carrying the argument alone, naming the rule a node was split on where the children aren't obviously exhaustive, tags, typed cross-reference IDs, tl;dr placement, and the per-artefact rules for commit bodies and code comments.
• chalk:goal-tree — the other relation. A plan's children serve their parent, and that's what makes completeness analysable: a goal states what its children have to add up to, so "are these enough?" has an answer, where an argument tree can only be checked for soundness. Carries the sufficiency test, the three kinds of leaf, and the named moves for closing a gap.

Decision rationale

D1: separate skills rather than more of chalk:voice. Voice is 300+ lines and every writing path loads it; the alternative was another 200 lines inside it.

• The two concerns are orthogonal. Voice classifies by Diataxis quadrant; the mindmap is a shape that applies in every quadrant. Nesting one inside the other reads as though the tree were an explanation-quadrant device.
• It survives a future split. Splitting docs authoring out of chalk means moving voice's tutorial/how-to/reference depth — chalk:tend-docs is its only consumer — and neither new skill is touched by that. Keeping the format inside voice would have made that split strictly harder.
• A skill can be named. chalk:mindmap can be cited directly from a project's own conventions; a section heading inside voice can't.

D2: the two idiosyncratic devices are scoped, not global.

• Typed IDs (D1, I3, D2.1) are for Alternatives considered, Decision rationale and Open Questions — the sections where a reviewer answers one branch and accepts the rest. That's the thing GitHub can't do natively, because a bullet has no anchor to link to. IDs on scaffolding are noise, so they aren't the default everywhere.
• Tags stay an open vocabulary with no obligation to use them. assumption: and check: carry the most weight — they state verification status at a fraction of what prose spends — but a tag that isn't meant precisely is worse than no tag, so the rule is "tag it and you've made a claim".

D3: two rules diverge from how the format has been used so far.

• A commit body MAY open with a tl;dr where the body is long enough that its argument needs summarising, rather than relying on the subject line alone. The subject line remains the default.
• A goal tree may frame a problem, not only a proposed solution. Only the solution-shaped tree is earned by a session that actually worked the direction, per the rule a8058fd established for the other solution-shaped sections.

Out of scope

• Splitting docs authoring out of chalk. Worth doing — team communication and user-facing documentation are different jobs, and chalk:tend-docs plus chalk:weed-docs are the only consumers of voice's tutorial/how-to depth — but it's a packaging change, and braiding it with a format change makes the diff unreviewable. This change was checked against making that split harder, not deferred blindly.
• A chalk:plan skill. chalk:goal-tree covers writing a goal structure down; the discipline of making a plan against one is a different skill and isn't attempted here.
• Retro-fitting existing artefacts. No issue, PR or docs page in any repo is rewritten by this.

Usage

Nothing to run. The new skills are auto-discovered from skills/*/SKILL.md like chalk's existing ones, and are loaded by chalk, chalk:issue, chalk:commit, chalk:pr and chalk:tend-docs rather than invoked directly. /chalk:mindmap and /chalk:goal-tree will print either guide if you want to read it.

One manual step, for whoever merges this: if your own instructions file carries a copy of this format, it's now redundant and will drift — replace it with a pointer at the two skills.

Test plan

No executable tests — this is skill guidance. What was checked instead:

• A five-way review pass over the diff: house-style adherence, internal consistency across all nine skills, the change against the git history of the files it touches, fidelity to the source material, and skill-definition mechanics.
• Seven defects found and fixed. The substantive ones: chalk:commit had grown a third near-verbatim copy of the commit-body rules and the copies had already drifted; chalk:mindmap re-centralised the line-break mapping that an earlier commit deliberately pushed out to each calling skill; chalk:pr told PRs to goal-tree their Implementation section, which the palette defines as retrospective; and a constraint in chalk:goal-tree broadened a MUST from two of the eight gap-closing moves to all of them. The rest were stale cross-references and workflow checklists left behind by the prose above them.
• Frontmatter parsed and validated for all nine skills, with name checked against the containing directory.
• The commit body on this branch and this description are the first artefacts written under the new rules, which is the only end-to-end check available.