Contributing to the handbook & toolkit

This repository is the versioned, single home of the RAPID process — the handbook you are reading and the toolkit/ artefacts it governs live together, change by PR, and carry their history in Git. A process that lives in slide decks and chat threads drifts; one that lives in a repo is reviewed, diffed and owned like the products it governs. This page is how to change it without breaking it.

Ownership

• Every standard and playbook has an owning role — the role named in the RACI accountable for that area. The owner reviews changes to their pages; they don't have to write them.
• Changes land by PR, never by direct push — the same discipline RAPID demands of product repos applies to the process itself. Small, reviewable diffs; one concern per PR.
• Toolkit decision rights sit with the Guild — prompts, skills and radar moves follow toolkit governance; anyone may draft, the Guild approves what's published as proven.

Pending — named owners per page

The RACI names the owning roles; assigning a named individual per standard/playbook is a leadership decision still to be made. Until then, the Guild reviews toolkit changes and the relevant role lead reviews handbook changes.

Versioning

• Prompts and skills use SemVer — each carries version front-matter and a lifecycle (draft → trial → proven → deprecated). Breaking a prompt's contract (different inputs, different output shape) is a major bump, not a quiet edit; see the schema in toolkit/prompts/README.md and the skill spec template.
• Decisions are superseded, never edited — per the decision records standard. A changed decision is a new record linking back to the one it replaces; history stays legible to humans and agents.
• Handbook pages evolve in place — Git history is their version history. When a page changes meaning (not just wording), say so in the PR description so downstream readers can find the change.

The split: handbook vs toolkit

Written rules live in the handbook; the artefacts they govern live in the toolkit. The handbook (docusaurus/docs/) is the human reading source — process definition, standards, playbooks, gate rationale. The toolkit (toolkit/) holds the machine-consumable counterparts — gate cards, templates, prompts, skills, registers, the scaffold — the things you instantiate or an agent loads verbatim. If you're explaining why or what the rule is, it's a handbook page; if you're writing something a squad copies or an agent executes, it's a toolkit artefact. Most substantial changes touch both, in the same PR.

Link conventions

Four rules, by direction. Get these wrong and either the site build fails or the sync step can't rewrite the link.

From → to	Form	Example
Handbook → handbook	Relative .md link	../standards/metrics.md or gates.md
Handbook → toolkit	In-site route, no extension	/toolkit/templates/pfd
Toolkit → toolkit	Relative .md link	../templates/adr.md
Toolkit → handbook	Relative path into the docs tree, with .md	../../docusaurus/docs/standards/raci.md

• Never link handbook → toolkit with a .md suffix — the toolkit pages exist in the site only as generated routes, so /toolkit/templates/pfd.md 404s where /toolkit/templates/pfd resolves.
• Adjust ../ depth for toolkit → handbook links to the linking file's location — a file in toolkit/skills/code-archaeology/ needs three ../, one in toolkit/gates/ needs two.
• The build is the linter — broken internal links fail npm run build, so a green build is your link check.

The sync step

docusaurus/scripts/sync-toolkit.mjs runs automatically on every npm run build and npm run start (via the prebuild/prestart hooks). It pulls every toolkit .md into docs/toolkit/, rewrites cross-tree links to in-site routes, escapes braces for MDX, strips authoring comments, and stamps each page with a "generated from the toolkit" banner.

docs/toolkit/ is generated — never edit it

docusaurus/docs/toolkit/ is gitignored output, deleted and rebuilt on every build. Any edit made there is silently lost. The source of truth is toolkit/ — edit there, rebuild, and the site page follows.

Building locally

• npm run start (in docusaurus/) — live-reloading dev server; the sync step runs first, so toolkit changes need a restart to appear.
• npm run build — full production build with broken-link checking; run before pushing anything link-heavy.
• npm run clear — if links or sidebars behave oddly after renames, the culprit is almost always Docusaurus's stale cache; clear it and rebuild.

Navigation & the reading flow

The sidebar is curated in docusaurus/sidebars.ts, not auto-generated — it's deliberately ordered as a reading flow (Understand → The process → Adopt → Standards → Playbooks → Contributing → Toolkit reference), and the big Standards/Playbooks sections are broken into sub-groups there. Two consequences:

• Adding a handbook page? Add its doc id to the right group in sidebars.ts, or it won't appear in the sidebar (it's still reachable by URL, but orphaned from navigation). The build fails loudly if you reference an id that doesn't exist.
• The sidebar_position front-matter is now ignored for handbook pages (order comes from sidebars.ts); leave it or drop it. The Toolkit reference section is the one exception — it's auto-generated from docs/toolkit/, so new toolkit files appear there automatically.

Page conventions

• UK spelling throughout — artefact, prioritise, licence (noun), behaviour. The audience is a UK insurance business; write like it.
• UK spelling throughout — artefact, prioritise, licence (noun), behaviour. The audience is a UK insurance business; write like it.
• Admonitions use bracket syntax — :::note[Title] / :::warning[Title], closed with :::.
• No raw curly braces in handbook pages — MDX parses { and } as JavaScript expressions and the build fails, often confusingly. Keep braces inside code spans or fences. Toolkit files are plain CommonMark where {placeholder} tokens are fine — the sync step escapes them on the way in.
• Match the house shape — an opening paragraph saying what the page is and why it exists, then short sections of bold-lead bullets. End standards with a "Standards referenced:" line where industry standards apply.

Standards referenced: SemVer, Keep a Changelog.