Night Market Docs And Writing

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

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-8, ship at 7+): thesis stated first, every sentence carries weight, thesis echoed rather than filler repeated, and one audience tier declared and served. Rubric: scribe:slop-detector module document-economy.md; tier table and extraction protocol: module audience-targeting.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:

textCopy code
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 workflow no longer holds its own word lists. It calls scripts/slop_score.py, which reads plugins/scribe/data/languages/en.yaml, so a category added there reaches CI with no workflow edit.

Three modes, one script. Gate mode answers whether this merges. Ratchet mode answers whether a changed file got worse than its committed version, which is what the pre-commit hook asks of staged markdown and what CI asks of a PR's markdown against the merge base. Audit mode answers where the slop is, which is the question you have while fixing it:

bashCopy code
uv run --with pyyaml python scripts/slop_score.py --audit <files>
uv run --with pyyaml python scripts/slop_score.py --threshold 3.0 docs book/src
uv run --with pyyaml python scripts/slop_score.py --ratchet HEAD <changed files>

Audit takes files or directories, prints a file and a line per finding, and exits 0. It also runs the categories the gate declines to score: semicolon splices, negative definition, over-explained fixes, contrastive scaffolds, and the per-document negation-density reading. Those are labeled (low) or (medium). A person judges them. Nothing auto-rewrites them.

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):

markdownCopy code
# 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

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:

bashCopy code
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:

bashCopy code
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.