/night-market-docs-and-writing

name: night-market-docs-and-writing
description: Maintain docs of record, ADRs, changelog, and house style. Use when writing repo docs. Do not use for release steps; use night-market-operations instead.

Night Market Docs and Writing

This skill maps every document of record in claude-night-market, states which are hand-authored and which are generated, and gives the house prose style with the commands that enforce it. "Docs of record" means the files other contributors treat as canonical truth. Editing the wrong file (or a generated one) creates drift that CI then flags.

Docs-of-record map

| File | Canonical for | Authored or generated | Update trigger | |------|---------------|-----------------------|----------------| | `CONSTITUTION.md` | Supreme law: 10 non-negotiable rules | Hand-authored | Amendment PR titled `constitution: amend rule N` plus repo-owner sign-off | | `STEWARDSHIP.md` | Values and virtues behind the rules | Hand-authored | Rarely; value-level shifts only | | `.claude/rules/` (8 files) | Repo-wide behavioral rules loaded into every session | Hand-authored | A research finding or audit graduates into policy | | `docs/adr/` (0001-0017) | Load-bearing decisions with status and supersession | Hand-authored | New architectural decision; supersede, never rewrite | | `docs/quality-gates.md` | Three-layer gate system and skill gate composition | Hand-authored | Gate or threshold changes | | `docs/testing-guide.md` | Test discipline and coverage practice | Hand-authored | Testing policy changes | | `docs/plugin-development-guide.md` | Plugin authoring, release checklist, Python tiers | Hand-authored | Plugin conventions change | | `docs/skill-description-guide.md` | The 160-char description contract | Hand-authored | Description policy changes | | `docs/skill-integration-guide.md` | Skill role taxonomy (entrypoint, library, hook-target) | Hand-authored | Skill graph restructuring | | `docs/backlog/queue.md`, `docs/backlog/technical-debt.md` | Work intake and debt registry. LOCAL ONLY, not a doc of record: `docs/backlog/` is gitignored with zero tracked files, so these exist only on the authoring machine. The durable record of a deferred item is a GitHub issue | Hand-authored, gitignored | New backlog item or debt entry | | `docs/research/` | Dated research syntheses feeding the rules pipeline. LOCAL ONLY, not a doc of record: gitignored, absent on fresh clones. Background material; put load-bearing citations into the rule or ADR itself (see night-market-research-methodology) | Hand-authored, gitignored | New research pass completes | | `CHANGELOG.md` | Release history, Keep a Changelog 1.1.0 | Hand-authored | Every release and notable change | | `docs/api-overview.md` | Plugin version table and CLI entry points | Hand-authored | Every release (version table row per plugin) | | `book/src/` | Published mdBook (GitHub Pages) | Mixed: see below | Content changes; deploys on push to `book/**` | | `book/src/reference/capabilities-*.md` | Skill/command/agent/hook lookup tables | GENERATED via sync | Never hand-edit; run `/sanctum:sync-capabilities --fix` | | `.claude-plugin/marketplace.json` | Ecosystem version source of truth | Hand-authored (bumped by script) | Release version bump | | `docs/tradeoffs.md`, `docs/lessons-learned.md` | Decision journal (TR-NNN / LL-NNN entries) | Hand-authored, append-only | Recording a tradeoff or lesson (contract: `leyline:decision-journal`) | | GitHub Discussions | Collective memory ([Learning], [PR Finding], [War Room]) | Mixed (hooks post automatically) | See night-market-collective-memory |

Notes on the map:

• mdBook is the `mdbook` static-site generator. The book builds from

`book/book.toml` (`src = "src"`, `create-missing = false`) and its table of contents is `book/src/SUMMARY.md` (Getting Started, then Plugins grouped by layer, then Reference).

• The decision journal files do not exist in the working tree as of

2026-07-02. The `leyline:decision-journal` contract creates them on first append. Do not scaffold them empty.

• `docs/dependency-audit.md` and other dated reports are point-in-time

artifacts, not living docs of record.

Per-feature artifacts: overwritten each cycle

`docs/project-brief.md`, `docs/specification.md`, and `docs/implementation-plan.md` are per-feature working documents. Each feature cycle OVERWRITES them (current occupant as of 2026-07-02: the insight-palace bridge, spec v0.1.0 Draft). Never treat their content as permanent record. If a decision inside them must outlive the feature, promote it to an ADR or a decision journal entry before the next cycle.

House prose style

Full rules live in `.claude/rules/markdown-formatting.md` and `.claude/rules/slop-scan-for-docs.md`, with the detection catalog in `Skill(scribe:slop-detector)` modules. The load-bearing subset:

• Wrap prose at 80 characters. Break at sentence boundaries first,

then clauses, then before conjunctions. Never wrap tables, code blocks, headings, frontmatter, or URLs.

• ATX headings only (`# Title`). Blank line before AND after every

heading and every list.

• Reference-style links when an inline link pushes a line past 80

characters.

• Em-dash target is zero in new prose (0-2 absolute max per file).

Use colons, periods, or parentheses. Never use a spaced double dash as punctuation (a repo hook flags it).

• American spelling. No semicolon splices. No smart quotes outside

code blocks.

The three slop layers

"Slop" is the repo term for machine-generated prose patterns that waste reader time or ship falsehoods. Every new or edited markdown file passes three layers before it is done:

1. **P0 critical (any hit fails outright)**: identity leaks ("As a large language model"), hallucinated identifiers, paths, packages, or URLs, and bare TODO/FIXME stubs without a tracked issue. Constitution rule 4 makes an identity leak an automatic revert. 2. **Document economy (scored 0-6, ship at 5+)**: thesis state