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

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

1. 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.

1. 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.