sonder-docs-and-writing

Writes and maintains Sonder Runtime documentation across ADRs, runbooks, wiki pages, and evidence ledgers.

6|3|Updated Jul 3, 2026
One-click install
npx skills add https://github.com/Krilliac/Sonder-runtime --skill sonder-docs-and-writing-krilliac
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: sonder-docs-and-writing
Source: https://github.com/Krilliac/Sonder-runtime/tree/main/.claude/skills/sonder-docs-and-writing
Command: npx skills add https://github.com/Krilliac/Sonder-runtime --skill sonder-docs-and-writing-krilliac

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? The Sonder Runtime repository contains over 600 markdown files governed by strict rules: every fact has exactly one home, generated catalogs must never be hand-edited, and four checker scripts fail the build when documentation drifts. This Skill tells you exactly where each kind of fact belongs and how to write it without tripping a CI gate. ## Core Features & Use Cases - Document taxonomy routing: Maps each type of fact (contracts, requirements, decisions, procedures, concepts) to its single authoritative location, from ARCHITECTURE.md to docs/runbooks/ to the 19-page wiki. - Gate-compliant writing: Provides templates and naming rules for ADRs, evidence documents, runbooks, and wiki pages that pass check_documentation_authority.py, check_evidence_documents.py, and check_requirement_evidence.py. - Ledger and checkbox discipline: Enforces the append-only requirements.jsonl workflow so master-spec checkboxes are only flipped with a verified evidence record. - Use Case: When asked to "write an ADR" for a new architectural decision, the Skill produces a correctly named docs/adr/ADR-YYYY-MM-DD-slug.md file matching the enforced regex and template, then runs the pre-commit checker suite to confirm all gates pass. ## Quick Start Ask the assistant to write an ADR documenting a new architectural decision and place it in the correct docs directory following the repository conventions.

Frequently Asked Questions about sonder-docs-and-writing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an ADR in the Sonder Runtime repository?

Create a file in docs/adr/ named ADR-YYYY-MM-DD-slug.md with a lowercase slug, matching the enforced regex. Use the template with Status, Date, Context, Decision, Rationale, and Consequences sections. The two historical numeric ADR namespaces are frozen and must never be extended.

How do I check a requirement checkbox in the master spec?

A checkbox may only be marked [x] after appending a new record to docs/architecture/evidence/requirements.jsonl with status verified, including baseline_sha, verified_sha, and evidence fields. The ledger is append-only; regressions are new records, never edits.

Which scripts validate documentation changes before commit?

Four checkers gate docs: check_documentation_authority.py, check_evidence_documents.py, check_requirement_evidence.py, and generate_documentation_catalogs.py --check. All must exit 0 before committing, and most run through the pytest suite in CI.

Can I edit generated documentation catalog files manually?

No. Files under docs/architecture/generated/ must only be regenerated with generate_documentation_catalogs.py --write or check_requirement_evidence.py --write-generated. Hand-editing them fails the freshness gate because digests are recomputed from typed sources.

When should I not use this documentation skill?

Do not use it to decide which document is authoritative in a conflict or whether a doc proves current status; those rules belong to the sonder-architecture-contract skill. It also does not cover what public claims a release note may assert.