Skip to content

docs(architecture): slop sweep — clear negative-framing headings + prose tells#170

Merged
Yambr merged 2 commits into
next/v1from
fix/canon-slop-sweep
May 30, 2026
Merged

docs(architecture): slop sweep — clear negative-framing headings + prose tells#170
Yambr merged 2 commits into
next/v1from
fix/canon-slop-sweep

Conversation

@Yambr

@Yambr Yambr commented May 30, 2026

Copy link
Copy Markdown
Collaborator

Applies the new CLAUDE.md "Slop patterns" rules across the already-merged canon. Found by the doc-slop-reviewer sweep of all 13 architecture docs — 0 blockers, structural warnings only.

Fixed

  • Negative-framing / question headings → noun phrases (the systemic pattern):
    • README.md: ## What's here## Contents; ## What's NOT here yet## Not yet present
    • PROCESS.md: ## What this file is not## Scope boundary (negation list → one sentence)
    • adr/README.md: ## When to write an ADR (vs. inline note)## ADR threshold
  • Prose tells:
    • 01-audience: adjective-triple "security, compliance, and operational scale we know" tightened
    • 02-nfrs: defensive tail "not contradictions" dropped
    • adr/0001: "replaced from scratch" restatement removed
    • adr/0000-template: "Neutral but worth noting:" → "Neutral:" (template was seeding a banned hedge)
    • 03-c4-context: duplicate "visible at a glance" removed

Left as-is

## Why now in 01-audience — recognized positioning-section label, body is all dated fact; a noun-phrase rewrite reads worse. Reviewer rated Info/low-risk.

Clean (no findings)

02-trust-boundaries.md, MANIFESTO.md, glossary.md, primitives-backlog.md, 04-bounded-contexts.md.

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

  • Documentation
    • Clarified architecture documentation structure with updated section headings and guidance
    • Enhanced ADR (Architecture Decision Record) template and threshold guidance
    • Refined scope boundaries and navigation pointers across documentation
    • Improved descriptions of audience definitions and non-functional requirements

Review Change Stack

…ose tells

Apply the new CLAUDE.md "Slop patterns" rules across the merged canon
(found by the doc-slop-reviewer sweep; 0 blockers, structural warnings):

- Negative-framing / question headings → noun phrases:
  README "What's here"/"What's NOT here yet" → "Contents"/"Not yet present";
  PROCESS "What this file is not" → "Scope boundary" (negation list folded
  into one sentence); adr/README "When to write an ADR (vs. inline note)" →
  "ADR threshold".
- 01-audience: drop the "security, compliance, and operational scale we know"
  adjective-triple + "we know" hedge; keep the tier-1-ceiling rationale.
- 02-nfrs: drop the defensive tail "not contradictions".
- adr/0001: drop the "replaced from scratch" restatement (already stated in
  Context); fold the rewrite-timing into the rejection clause.
- adr/0000-template: "Neutral but worth noting:" → "Neutral:" (the template
  was seeding the banned hedge).
- 03-c4-context: drop the second "visible at a glance" restatement.

"## Why now" in 01-audience kept — recognized positioning-section label,
body is dated fact; a noun-phrase rewrite reads worse.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented May 30, 2026

Copy link
Copy Markdown

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0a179250-5a5c-4fd0-b327-2d8d232ffb00

📥 Commits

Reviewing files that changed from the base of the PR and between a196c71 and 5f24035.

📒 Files selected for processing (8)
  • docs/architecture/03-c4-context.md
  • docs/architecture/PROCESS.md
  • docs/architecture/README.md
  • docs/architecture/adr/0000-template.md
  • docs/architecture/adr/0001-layer-0-gate-legacy-exclusion.md
  • docs/architecture/adr/README.md
  • docs/architecture/manifesto/01-audience-and-buyer.md
  • docs/architecture/manifesto/02-nfrs.md

Walkthrough

Nine single-line and multi-line documentation updates across the docs/architecture/ tree refine section headings, restructure navigation guidance, simplify template placeholders, and tighten technical wording in the C4 context, ADR process, manifesto audience, and NFR sections.

Changes

Architecture Documentation Refinements

Layer / File(s) Summary
Documentation structure and scope boundaries
docs/architecture/README.md, docs/architecture/PROCESS.md
README.md sections renamed to "Files in this directory" and "Not yet present" for consistency. PROCESS.md introduces explicit "Scope boundary" section pointing readers to inventory, routing rules, and roadmap resources elsewhere.
ADR process and template guidance
docs/architecture/adr/README.md, docs/architecture/adr/0000-template.md
ADR README heading changed from "When to write an ADR (vs. inline note)" to "ADR threshold." Template's "Consequences" neutral-item label simplified from "Neutral but worth noting: …" to "Neutral: …".
Technical specifications and design wording
docs/architecture/03-c4-context.md, docs/architecture/adr/0001-layer-0-gate-legacy-exclusion.md, docs/architecture/manifesto/01-audience-and-buyer.md, docs/architecture/manifesto/02-nfrs.md
C4 context §4 intro reworded to emphasize table reference for actor optionality. ADR-0001 clarifies legacy code is not patched on next/v1 but replaced from scratch in Layer 6+. Manifesto audience capability-ceiling rephrased from "security, compliance, and operational scale we know" to "regulatory and operational-scale envelope we design against." Token TTL taxonomy wording tightened to clarify scope–TTL correlation and independence of three commitments.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately captures the main intent of the changeset: removing negative-framing language and defensive prose from architecture documentation across multiple files.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/canon-slop-sweep

Comment @coderabbitai help to get the list of available commands and usage tips.

…sion

"## Contents" matched the ai-slop-detector TOC regex (treats a literal
"Contents" heading as a table of contents in a short doc). The section is a
file inventory, not a TOC → "## Files in this directory".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Yambr Yambr merged commit 4e477a6 into next/v1 May 30, 2026
17 checks passed
@Yambr Yambr deleted the fix/canon-slop-sweep branch May 30, 2026 12:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant