night-market-docs-and-writing
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.
athola · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add athola/claude-night-market --skill 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
mdbookstatic-site generator. The book builds frombook/book.toml(src = "src",create-missing = false) and its table of contents isbook/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-journalcontract creates them on first append. Do not scaffold them empty. docs/dependency-audit.mdand 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:
- 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.
- Document economy (scored 0-6, ship at 5+): thesis state