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 stated first, every sentence carries weight, thesis echoed rather than filler repeated. Rubric: scribe:slop-detector module document-economy.md.
3. Sentence-level tiers: banned vocabulary, negative parallelism, throat-clearing openers, participial tails, and the 2026 pattern set. Catalog: scribe:slop-detector module vocabulary-patterns.md and the rule file's tier lists.

Slop-check CI

.github/workflows/slop-check.yml runs on any PR touching a .md file. It scans only files under docs/ and book/src/ and scores each file:

score = (tier1_hits * 3 + tier2_hits * 2 + em_dashes) / words * 100

Any file scoring above 3.0 fails the job and gets a PR comment. The tier-1 and tier-2 word lists live in the workflow file itself (variables TIER1 and TIER2 in slop-check.yml); read them there rather than memorizing. Quick local pre-check on a doc you touched:

grep -o '—' docs/your-file.md | wc -l
grep -oiE 'delve|tapestry|pivotal|meticulous|leveraging|comprehensive' \
  docs/your-file.md

Files outside docs/ and book/src/ (plugin skills, READMEs) skip this CI job but still fall under the rule file and review.

Reader-time budget (constitution rule 8)

Every doc is paid for in cumulative reader-time: audience size times read frequency times per-read time. Estimate that product BEFORE drafting and match your writing time to it. A skill loaded hundreds of times a day earns hours of polish. A one-off report earns minutes. If the budget is near zero, do not write the doc. Full framework: scribe:slop-detector module document-economy.md.

ADR conventions

An ADR (Architecture Decision Record) captures a decision that is expensive to reverse. They live in docs/adr/ as NNNN-kebab-slug.md with zero-padded sequential numbers (0001-0017 as of 2026-07-02).

Header template (verified against ADR-0001 and ADR-0017):

# ADR-NNNN: Title

**Date**: YYYY-MM-DD
**Status**: Accepted
**Deciders**: Claude Night Market maintainers
**Source**: Issue #NNN, Discussion #NNN
**Supersedes**: ADR-NNNN

## Context

## Decision

## Consequences

Rules:

• Status values in use: Accepted, Superseded by ADR-NNNN. Never delete or rewrite a superseded ADR. Example chain: ADR-0012 and ADR-0013 both carry "Superseded by ADR-0017", and 0017 lists "Supersedes: ADR-0012, ADR-0013" in its header.
• An ADR may supersede itself in place for a scoped correction (ADR-0008 swapped its mechanism and documented the change inline).
• Source links the issue or discussion that forced the decision.

ADR vs journal entry vs discussion post

Record	Use for	Where
ADR	Load-bearing, hard-to-reverse design decision	docs/adr/NNNN-*.md
Decision journal	Tradeoff taken or lesson learned, append-only, stable TR-NNN / LL-NNN ids	docs/tradeoffs.md, docs/lessons-learned.md per leyline:decision-journal
Discussion post	Ambient collective memory: [Learning], [PR Finding], [War Room]	GitHub Discussions via GraphQL (no gh discussion subcommand exists)

For the Discussions mechanics and promotion path, use the sibling skill night-market-collective-memory.

Changelog conventions

CHANGELOG.md follows Keep a Changelog 1.1.0 and SemVer:

• ## [Unreleased] stays at the top; new entries land there and get moved under a ## [X.Y.Z] - YYYY-MM-DD heading at release.
• Standard subsections: ### Added, ### Fixed, ### Changed.
• Never retroactively de-slop or reword historical entries. The slop anti-goals (scribe:slop-detector module anti-goals.md) explicitly exempt changelog history: it is a record, not prose to polish.

Skill description contract

Every SKILL.md and command description: field is loaded into the model's skill-discovery budget, so length is policed:

• Hard cap: 160 characters per description (hard fail).
• Third person only. Template: [Verb phrase] [domain]. Use when [trigger]. Do not use when [negative]; use [alternative] instead.
• Full guide: docs/skill-description-guide.md.

Two pre-commit hooks enforce it:

python3 plugins/abstract/scripts/validate_budget.py
python3 scripts/fix_descriptions.py --check

validate_budget.py hard-fails any description over 160 chars and warns when the ecosystem total approaches its budget (default 90,000 chars, override via SLASH_COMMAND_TOOL_CHAR_BUDGET). Note: docs/skill-description-guide.md still cites an older 60,000-char ceiling; the script value is current (the script is the enforcer).

The book (mdBook)

• Structure: edit book/src/SUMMARY.md to add pages; create-missing = false means a SUMMARY entry without a file breaks the build.
• Local build: cd book && mdbook build (output in book/build/). mdbook is installed separately; CI uses the unpinned latest.
• Deploy: .github/workflows/deploy-book.yml publishes to GitHub Pages on push to master touching book/**. PRs touching book/** get a build check.
• book/src/reference/capabilities-*.md are generated from plugin manifests. Check drift with make docs-sync-check (runs scripts/capabilities-sync-check.sh); fix drift with the /sanctum:sync-capabilities --fix command, not by hand.

Doc gate command checklist

Run before committing markdown:

python3 scripts/check-markdown-links.py path/to/file.md
python3 plugins/abstract/scripts/validate_budget.py   # if SKILL.md touched
make docs-sync-check                                  # if manifests touched

Then walk the three slop layers manually or via Skill(scribe:slop-detector). Every new or modified SKILL.md also needs a ## Exit Criteria section (.claude/rules/skill-exit-criteria.md, issue #454).

When NOT to use

• Running tests, lint, releases, or the version bump: use night-market-operations.
• Classifying whether a change needs an ADR-gated review at all: use night-market-change-control.
• Posting to or querying GitHub Discussions, journal promotion paths, ADR-vs-memory routing details: use night-market-collective-memory.
• Plugin/skill/hook file mechanics (frontmatter fields, discovery): use claude-code-plugin-reference.
• Test evidence standards and coverage thresholds: use night-market-validation-and-qa.

Exit Criteria

• Any doc edit touched the file the map marks as canonical, and no file marked GENERATED was hand-edited (verify: git diff --stat shows no book/src/reference/capabilities-* unless produced by the sync command).
• New prose passes the local slop pre-check: zero P0 hits, zero new em dashes, no tier-1 vocabulary in the diff.
• python3 scripts/check-markdown-links.py <file> exits 0 for each markdown file touched.
• If a SKILL.md was touched: python3 plugins/abstract/scripts/validate_budget.py exits 0 and the file contains a ## Exit Criteria section.
• If a decision was recorded: it landed as a numbered ADR, a TR-NNN/LL-NNN journal entry, or a Discussion post, and any superseded ADR's Status field was updated in place.
• CHANGELOG.md still has ## [Unreleased] as its first version heading and no historical entry was reworded.

Provenance and maintenance

Compiled 2026-07-02 against repo v1.9.15 (branch discussions-fix-1.9.14). Volatile facts and how to re-verify:

• ADR count (17) and statuses: ls docs/adr/ and rg -l "Superseded" docs/adr/.
• Slop CI threshold (3.0) and scanned paths (docs/, book/src/): read .github/workflows/slop-check.yml.
• Description cap (160) and total budget (90,000): rg "DESCRIPTION_MAX|DEFAULT_BUDGET" plugins/abstract/scripts/validate_budget.py.
• Rules inventory (8 files): ls .claude/rules/.
• Per-feature doc occupant: head -5 docs/project-brief.md.
• Journal files existence: ls docs/tradeoffs.md docs/lessons-learned.md.
• Book deploy trigger: read .github/workflows/deploy-book.yml.
• Guide-vs-script budget drift (60K vs 90K): re-check docs/skill-description-guide.md in case the guide was updated.