docs(mt#1936): refresh README + 4 docs/* to locked voice register; absorb PR #682 (mt#1936)#1180
Conversation
…sorb PR #682 Top-level README and four highest-visibility docs/* files refreshed to the Macx-prose register (terse, technically loaded, presupposing reader literacy) per the locked brand foundation. Brand vocabulary used where it appropriately replaces generic equivalents (principal, substrate, flock) without force-injection. Anime-stylized references kept in the brand layer only — README uses plain-language "exocortex" framing per spec criterion #1. ### README.md (top-level) - New opening: locked myth in plain language. *"An exocortex for software organizations led by a principal — the substrate that holds the cognition of one mind across a flock of agents, and translates declared intent into coordinated realized work."* Plus a new intro paragraph naming the recursive-principality framing (every level of an organization is itself a principal-substrate relationship). - New §"Attention as the scarce resource" subsection under "Why Minsky?" — absorbed verbatim (with `operator` → `principal` to match the locked vocabulary) from PR #682 (mt#1050, OPEN 2026-04-22). Per gate-(g) absorb-and-close decision 2026-05-20, PR #682 will be closed with a pointer to this PR when mt#1936's PR is created. - New §"Brand & identity" section pointing at: position paper (mt#1931 Notion URL), `docs/brand-system.md` (mt#1932), `minsky-brand` skill (mt#1933), `marketing-site-design` skill, `pz-voice` skill (mt#1952). - Cross-reference added: §"Design philosophy" closes with a pointer to the Levels of principality position paper (mt#1953) for the recursive-principality argument. - Section-heading case normalized to sentence-case (matches brand voice rules: all-caps for structural labels only, sentence-case everywhere else). - Tightened generic phrasing: "platform" → "substrate" where natural; "comprehensive guidance" / "robust" / similar generic-doc shapes replaced with direct technical prose. ### docs/README.md - Refreshed opening paragraph: names what this directory is *for* (code-adjacent operational reference) and what lives elsewhere (Notion for strategic memos / position papers / incident records, Minsky task DB + GitHub PRs for per-task history). - Added pointers to the brand stack: minsky-brand skill, brand-system operational reference, CLAUDE.md §Documentation Taxonomy. ### docs/architecture.md - Refreshed opening: names the conceptual frame (five-organ cybernetic substrate) before the code-level walk-through. Added pointer to theory-of-operation.md as the theoretical companion. ### docs/configuration-guide.md - Refreshed Overview: replaced "centralized, validated approach" / "best practices" SaaS-shape with direct description of the precedence chain (CLI args → env vars → user config → repo config → defaults) and the fail-loud-at-boot validation discipline. ### docs/development-workflow.md - Refreshed opening + Overview: names the routing principle (cheaper decisions to the substrate, surface only what requires human judgement) referencing the README §"Attention as the scarce resource" subsection. Notes the system-speaks register the hooks implement (denial messages name the rule + override mechanism). - Tightened Overview: cost-scales-with-depth framing replaces generic "rigorous workflow with automated quality gates" prose. ### Acceptance test verification All 7 from spec pass: 1. ✓ README opens with locked myth in plain language 2. ✓ Brand & identity section present (1 occurrence) 3. ✓ All three pointers in README (position paper / brand-system / marketing-site-design — 1 occurrence each) 4. ✓ No SaaS-hyperbole phrases in any refreshed doc 5. ✓ 4 docs/* files touched (≥ 4 required) 6. ✓ Tone recognizably technical-restrained Macx-prose register 7. ✓ PR #682 "Attention as the scarce resource" subsection absorbed into README; PR #682 to be closed during mt#1936 PR review ### Format check Repo-wide `bun run format:check` passes. ### Out of scope (per spec) - CLAUDE.md, AGENTS.md, .minsky/rules/** (have their own voice registers) - docs/testing-patterns.md (does not exist — see spec Out-of-scope note explaining the testing-guide skill superseded it) - Full docs/ refresh (targeted subset is the right move per spec)
![minsky-reviewer[bot]](https://avatars.githubusercontent.com/u/52695?s=60&v=4){kind=small}
There was a problem hiding this comment.
Independent adversarial review (Chinese-wall)
Reviewer: minsky-reviewer[bot] via openai:gpt-5
Tier: 3
Docs-only refresh aligns with the spec: the README opens with the exocortex framing, adds a Brand & identity section with required pointers, and four high-visibility docs were updated in a restrained technical register. I found no blocking issues. Minor nits include one incorrect CLI example (minsky sessions start → minsky session start), potential link-rot risk for private Notion links without fallback, a missing anchor to CLAUDE.md’s documentation taxonomy, and some absolute performance/test-count claims that may drift. These are polish-level and non-blocking; the PR is otherwise in good shape.
Findings
- [NON-BLOCKING] docs/configuration-guide.md:1 — CLI example uses non-existent plural subcommand
sessions start
Under### 1. Command Line Arguments, the example shows:
minsky sessions start --sessiondb-backend=sqliteEverywhere else (including the top-level README.md) the subcommand is singular — minsky session start. The command registry groups this under the SESSION category, and README examples use minsky session start --task mt#123.
Suggest correcting the example to:
minsky session start --sessiondb-backend=sqlite- [NON-BLOCKING] README.md:63 — External Notion links added without archive or fallback increase link-rot risk
The README introduces multiple Notion links (e.g.,Position: Levels of principality,Principal substrate vs team substrate, and the companion essay on attention). Notion workspaces are often private; fresh readers may hit 404s.
Given this is the top-level entry point, consider adding a short note like "private workspace; request access" next to each Notion link, or mirroring key position papers under docs/ and linking there first to avoid dead-end navigation for public readers.
-
[NON-BLOCKING] docs/README.md:1 — Reference to CLAUDE.md section lacks anchor and capitalization consistency
The line referencesCLAUDE.md §Documentation Taxonomybut does not provide a direct anchor link (e.g.,../CLAUDE.md#documentation-taxonomy). Also, the heading casing elsewhere was normalized to sentence case; consider matching the text to the actual heading and adding an anchor for smoother navigation: -
Change to:
see [CLAUDE.md §Documentation taxonomy](../CLAUDE.md#documentation-taxonomy)(verify the actual anchor inCLAUDE.md). -
[NON-BLOCKING] docs/architecture.md:1 — Introduces "five-organ cybernetic substrate" frame without a local pointer or brief definition
The opening now frames the system as a "five-organ cybernetic substrate" but only links totheory-of-operation.mdfor the theoretical mapping. For readers landing onarchitecture.md, a short parenthetical (e.g., "VSM Systems 1–5") or a direct in-doc anchor to the relevant section oftheory-of-operation.mdwould reduce cognitive load. Suggest: "The five-organ cybernetic substrate (VSM Systems 1–5) is the conceptual frame; see Theory of Operation §The Five-Organ Architecture." -
[NON-BLOCKING] docs/development-workflow.md:22 — Performance and counts stated as absolutes may drift; consider qualifying or parameterizing
Statements like "Runs all 1,400+ unit tests" and specific timing budgets ("~2 seconds", total pre-commit "~5–7 seconds") risk going stale and being cited as guarantees. Consider softening to "on the order of" or moving these to examples, or sourcing counts dynamically from CI badges. Alternatively, add a note that figures are approximate and measured as of a date to avoid future "docs vs reality" drift.
All five reviewer-bot NON-BLOCKING findings addressed in one pass. - docs/configuration-guide.md:15 — fixed CLI typo `minsky sessions start` → `minsky session start` (singular subcommand; matches the shared command registry's SESSION category and README convention). Class-not-instance scan: only one occurrence across the 5 refreshed files; no other plural-subcommand instances to fix. - docs/README.md:1 — added anchor link to the CLAUDE.md taxonomy reference: `[CLAUDE.md §Documentation Taxonomy](../CLAUDE.md#documentation-taxonomy)`. Verified CLAUDE.md heading at line 895 is exactly `# Documentation Taxonomy` so the anchor `#documentation-taxonomy` resolves cleanly. - docs/architecture.md:1 — expanded the "five-organ cybernetic substrate" intro with a brief parenthetical: `(VSM Systems 1–5 — operations, coordination, control, intelligence, identity)`. Reduces cognitive load for readers landing on architecture.md without having opened theory-of-operation.md. - README.md Brand & identity section — added a top-of-section blockquote noting Notion links are private Minsky workspace (request access). Repo-local skill surfaces and docs/brand-system.md are accessible without an external account; named explicitly so fresh public readers don't dead-end at private 404s. - docs/development-workflow.md:29,31 — softened absolute claims in the pre-commit-hook ASCII diagram: `Runs all 1,400+ unit tests` → `Runs the full unit test suite (order of 1,400 tests)`; `Fast execution (~2 seconds)` → `Fast execution (typically seconds, not minutes)`. Box-drawing alignment preserved (verified visually). Other absolute claims at lines 95, 389, 394 left unchanged: those are deeper in the doc and out-of-scope for a voice-register refresh per the spec's targeted-subset principle; a deeper claims audit is separate work. Format check passes repo-wide. All 7 acceptance tests still pass.
There was a problem hiding this comment.
Independent adversarial review (Chinese-wall)
Reviewer: minsky-reviewer[bot] via openai:gpt-5
Tier: 3
All prior non-blocking nits were addressed: CLI example corrected to singular in docs/configuration-guide.md, CLAUDE.md anchor added in docs/README.md, VSM frame clarified in docs/architecture.md, and absolute counts/timings softened in docs/development-workflow.md. README now opens with the locked-myth proposition, adds the absorbed “Attention as the scarce resource” section, and includes a complete “Brand & identity” section with required pointers and a Notion access note. I see no new blocking issues or scope creep in this docs-only PR; acceptance criteria are met. Approving.
Spec verification
| Criterion | Status | Evidence |
|---|---|---|
1. The top-level README.md opens with a paragraph that names the locked myth (in plain language; "exocortex for software organizations led by a principal" or similar) without resorting to anime-stylized references. |
Met | README.md:3-5 — opening sentence: "An exocortex for software organizations led by a principal — the substrate that holds the cognition of one mind across a flock of agents..." |
There was a problem hiding this comment.
Review: refresh README + 4 docs/* to locked voice register; absorb PR #682 (mt#1936)
CI status: pass — 3 checks passed, 0 failed (build, Prevent Placeholder Tests, bundle-boot-smoke).
Smoke: skipped — docs-only change (README + 4 markdown files in docs/*); no code path exercised.
Summary
Five-file docs refresh: top-level README.md opens with the locked-myth framing in plain language ("exocortex for software organizations led by a principal"), absorbs PR #682's "Attention as the scarce resource" subsection, and adds a "Brand & identity" section pointing at the brand-stack artifacts (position paper / brand-system doc / minsky-brand skill / marketing-site-design skill / pz-voice skill). Four docs/* files (docs/README.md, docs/architecture.md, docs/configuration-guide.md, docs/development-workflow.md) get surgical opening-paragraph refreshes — generic-doc SaaS-shape language replaced with direct technical prose, brand vocabulary used where it appropriately replaces generic equivalents. Two reviewer-bot rounds: R1 COMMENTED with 5 NON-BLOCKING (CLI typo, missing anchor, frame clarification, absolute claims, Notion link-rot disclaimer) → R2 clean APPROVE after the comprehensive fix. Zero blocking findings.
Cross-cutting concerns
None. Scope held tight: no creep beyond the targeted-subset refresh; no semantic changes to technical content; brand vocabulary used selectively, not force-injected (e.g., docs/architecture.md keeps technical neutrality; only docs/development-workflow.md adds the routing-principle framing because the spec criterion #6 explicitly calls for the system-speaks register on hook docs).
Spec verification
Task: mt#1936
| Criterion | Status | Evidence |
|---|---|---|
| 1. README opens with paragraph naming locked myth in plain language, no anime-stylized references | Met | README.md:3 — "An exocortex for software organizations led by a principal — the substrate that holds the cognition of one mind across a flock of agents, and translates declared intent into coordinated realized work." "Exocortex" is from Stross / general cyberpunk; no Section 9 / Magi / Tachikoma / Eva referenced in README body. |
| 2. README has Brand & identity section pointing at position paper, brand-system, marketing-site-design | Met | README.md Brand & identity section present (1 occurrence); pointers to all three (position paper Notion URL 365937f03cb481e78fd5e0594a6507c1, docs/brand-system.md, marketing-site-design skill) plus bonus pointers to minsky-brand and pz-voice skills. Notion-link access disclaimer added per R1 NON-BLOCKING feedback. |
3. Key docs/* files audited and updated (target: ≥4) |
Met | 4 docs/* files modified: docs/README.md (intro), docs/architecture.md (opening), docs/configuration-guide.md (Overview), docs/development-workflow.md (opening + Overview). Stale docs/testing-patterns.md target removed during /plan-task (file doesn't exist; testing material in testing-guide skill). |
| 4. No SaaS-hyperbole phrases ("the future of", "transforms your", "supercharge your", "from your first X to your IPO") in refreshed docs | Met | grep -ni "the future of|transforms your|supercharge your|from your first.*IPO" returns 0 matches across all 5 refreshed files. The only hit anywhere in the repo is docs/brand-system.md:206 which is the doc listing rejected phrases — that file is not in this PR. |
| 5. Brand vocabulary used where appropriate, not force-injected | Met | principal, substrate, flock used selectively in README + docs/development-workflow.md where the framing requires them; docs/architecture.md keeps technical neutrality (no forced vocabulary in code-walkthrough); docs/configuration-guide.md uses "Minsky" / "system" prose without forced brand-term insertion. The vocabulary stays in the brand and marketing layers per the spec; technical docs remain technical. |
6. Hook denial / system-speaks register applied to relevant docs/* examples |
Met | docs/development-workflow.md opening explicitly names the system-speaks register: "When a hook denies an action, its message names the rule and the override mechanism; that is the system-speaks register the hooks themselves implement." Cross-reference to README §"Attention as the scarce resource" added. |
| 7. PR #682 (mt#1050) content absorbed into README | Met | README.md §"Attention as the scarce resource" subsection present (1 occurrence). Content preserved verbatim from PR #682 with operator → principal to match the locked vocabulary post mt#1953. PR #682 closure plan documented in this PR's body and spec; will close PR #682 with pointer comment after this PR merges. |
All seven criteria Met. No follow-up action required.
Adoption sweep
Docs-only PR — no public exports, no CLI commands, no MCP tools, no new capabilities. Sweep not applicable.
The new public-facing surface is the README's opening paragraph (the locked myth in plain language) and the Brand & identity section. Both are static text consumed by readers, not API surfaces; no consumers to wire.
Documentation impact
This PR IS the documentation refresh. No other docs need updating:
- Architectural docs beyond
docs/architecture.md— no other architectural surface needs voice-register adjustment. - Developer-workflow docs beyond
docs/development-workflow.md—docs/pr-workflow.mdanddocs/development-workflow.mdare the two workflow docs; pr-workflow stays untouched per the spec's targeted-subset principle (already-restrained voice; lower drift from the new lock). - User-facing docs — README updated;
CONTRIBUTING.mdandLICENSEleft alone per spec out-of-scope. - CLAUDE.md / AGENTS.md / .minsky/rules/` — explicitly out of scope per spec (each has its own voice register for agent operational instructions).
docs/brand-system.md— was just shipped in mt#1932; the post-mt#1933 cross-reference updates already happened during mt#1933's R1 fix pass. No further updates needed.
(Had Claude look into this — AI-assisted review)
minsky-reviewer
Bot
added
the
review:bot-approved
There was a problem hiding this comment.
Independent adversarial review (Chinese-wall)
Reviewer: minsky-reviewer[bot] via openai:gpt-5
Tier: 3
All prior non-blocking nits from R1 were addressed in the earlier iteration and remain correct in the current HEAD. The README now opens with the plain-language locked myth, includes the absorbed “Attention as the scarce resource” section, and adds a complete Brand & identity section with the required pointers and a private-Notion access note. Four targeted docs under docs/ were refreshed to the Macx-prose register without SaaS hyperbole, and CLI examples were corrected. I find no new blocking issues or scope creep introduced by this docs-only change. Verdict: APPROVE.
Spec verification
| Criterion | Status | Evidence |
|---|---|---|
1. The top-level README.md opens with a paragraph that names the locked myth (in plain language; "exocortex for software organizations led by a principal" or similar) without resorting to anime-stylized references. |
Met | README.md:3 — “An exocortex for software organizations led by a principal — the substrate that holds the cognition of one mind across a flock of agents…” |
2. The README has a "Brand & identity" section near the bottom pointing at: the position paper (mt#), docs/brand-system.md, and the marketing-site-design skill. |
Met | README.md:153-173 — “## Brand & identity” with links to Position paper Notion, docs/brand-system.md, and .claude/skills/marketing-site-design/SKILL.md |
1 participant
Summary
Top-level README and four highest-visibility
docs/*files refreshed to the Macx-prose register (terse, technically loaded, presupposing reader literacy) per the brand foundation locked in mt#1929. Brand vocabulary (principal, substrate, flock) used where it appropriately replaces generic equivalents, never force-injected. Anime-stylized references stay in the brand layer only — README uses plain-language "exocortex" framing per spec criterion #1.Part of mt#1929 (brand workstream umbrella) — child #7 / Phase 3. Supersedes & closes PR #682 (mt#1050) by absorbing its "Attention as the scarce resource" README subsection into this PR per gate-(g) absorb-and-close resolution decided 2026-05-20 (planning session captured in mt#1936 spec).
Key changes
README.md(top-level)### Attention as the scarce resourcesubsection under "Why Minsky?" — content preserved verbatim withoperator→principalto match locked vocabulary.## Brand & identitysection pointing at: Principal Substrate position paper (mt#1931),docs/brand-system.md(mt#1932),minsky-brandskill (mt#1933),marketing-site-designskill,pz-voiceskill (mt#1952).docs/README.mddocs/architecture.mdtheory-of-operation.mdas the theoretical companion.docs/configuration-guide.mddocs/development-workflow.mdPR #682 closure plan
When this PR converges and merges, PR #682 (mt#1050) will be closed without merge, with a comment pointing here. Its content (the "Attention as the scarce resource" subsection) is preserved in this PR; closing #682 removes the open redundant change. This is the absorb-and-close path the user approved during /plan-task gate (g).
Testing
All seven acceptance tests from the spec verified before PR:
head -10 README.mdshows refreshed opening + locked-myth paragraph.grep -c "Brand & identity"returns 1.grep -ni "the future of|transforms your|supercharge your|from your first.*IPO"returns 0 matches across all 5 refreshed files.docs/*files touched (docs/README.md,docs/architecture.md,docs/configuration-guide.md,docs/development-workflow.md) — meets the ≥4 spec floor.operator→principalvocab match).Repo-wide
bun run format:checkpasses.Docs-only change. No verification artifact required per
/implement-task§7a.Out of scope (per spec)
CLAUDE.md,AGENTS.md,.minsky/rules/**— each has its own voice register (operational instructions for agents); shouldn't shift to brand-marketing voice.docs/testing-patterns.md— does not exist; testing material lives in thetesting-guideskill per CLAUDE.md§Build & Test. Stale reference in original spec removed during /plan-task.docs/refresh — out of scope; targeted subset is the right move per spec.