docs(mt#1050): surface attention-allocation frame in README

[minsky-ai]

Summary

Adds a 6th subsection under Why Minsky? in README.md:

Attention as the scarce resource

Surfaces the attention-allocation framing that already lives in docs/theory-of-operation.md (Companion Principles) and CLAUDE.md (Design Principle: Humility) at the README level — the public landing surface. Readers arriving from GitHub now encounter the framing without having to visit Notion or the theory doc first.

Composed with Claude (this is an AI-drafted subsection passed through the standard review path).

What the subsection does

• States the attention-allocation principle positively — operator attention is the scarce resource; every mechanism in Minsky routes decisions to the cheapest thing that can resolve them.
• Names both failure modes: Waste (asking about resolvable choices) and Usurp (deciding things that structurally belong to the operator).
• Frames these as a single routing problem with a kind-taxonomy of asks — setting up the work in mt#1034 without front-loading the full taxonomy.
• Links to the Notion companion essay (34a937f0-3cb4-814b-adba-f2e5cee38c08) for readers wanting the full argument.

Register calibration

Tighter than docs/theory-of-operation.md — no VSM terminology (no System 5 / System 3*), no task IDs in body copy, matches the rhythm of the existing 5 subsections (1–2 short paragraphs each). Existing 5 subsections are byte-for-byte unchanged.

Line budget

README: 140 → 147 lines. Well under the 210-line legibility target from mt#771.

Test plan

• wc -l README.md → 147 (under 210)
• grep -n -i 'attention' README.md returns the new subsection
• Existing 5 subsections unchanged (diff shows pure insertion)
• Subsection stands alone without requiring the Notion essay first
• Outsider-read sanity check — addressed at merge time by user

Context

• Depends on: nothing (mt#771, mt#770 DONE)
• Parent investigation: mt#697 (DONE)
• Companion work: mt#1034 (Ask subsystem), mt#1035 (System 3* detector) — both about to start
• Tangential bug filed during this task: mt#1067 (session_commit double-quote escape)

[minsky-ai]

Review: README attention-allocation subsection

CI status: 1 passing (Prevent Placeholder Tests), 1 in-progress (build). No failures. Not blocking for a docs-only change but should complete green before merge.

Coverage: 1/1 files reviewed (README.md — 8 insertions, 0 deletions).

Findings

No blocking issues. The diff is a pure insertion: 8 lines added after line 61 (end of "Git-native") and before "## Quick Start". Every success criterion verified below.

One thing worth flagging (non-blocking, informational):

• The Notion link https://www.notion.so/34a937f03cb4814badbaf2e5cee38c08 works iff the page is publicly shared. The spec explicitly lists this URL so treating the share setting as the user's call.

Checked and clear

• Placement: subsection sits as the 6th under "Why Minsky?", after "Git-native" and before "## Quick Start" — matches spec's default form.
• Existing subsections unchanged: diff shows no edits to the other 5 subsections (pure insertion at line 62).
• Register: no VSM jargon (no "System 5" or "System 3*"), no task IDs in body copy, paragraph lengths match existing subsections (1–2 short paragraphs). Register matches the neighbor subsections rather than docs/theory-of-operation.md.
• Principle is positive, not comparative: the opening sentence states what the resource is; the "confirmation dialogs" contrast is a clarification of the routing claim, not positioning against other tools.
• Failure modes named in bold: **Waste** and **Usurp** both bolded, making them scannable.

Spec verification

Task: mt#1050

Criterion	Status	Evidence
New subsection titled "Attention as the scarce resource"	Met	README.md:64 — exact title from spec
States principle positively; names waste and usurp	Met	README.md:66 (positive statement); README.md:68 (**Waste**, **Usurp**)
References Notion companion essay for full argument	Met	README.md:70 — link present
Existing 5 subsections unchanged in content	Met	Diff is pure insertion — no - lines on existing subsections
README stays under 210 lines	Met	140 → 147 lines (well under 210)
Grep for "attention" returns the new subsection	Met	grep -i attention README.md returns lines 64 + 66
Outsider can identify attention allocation as core framing (acceptance test)	Met	Subsection is titled explicitly; placed in top-level "Why Minsky?" section
Subsection stands alone without Notion	Met	Principle + both failure modes fully stated in-body; Notion link is optional depth

No criteria deferred or unmet. No spec update needed.

Documentation impact

Updated README.md in this PR.

No other docs need touching in this PR:

• docs/theory-of-operation.md already carries the Companion Principles section (uncommitted on main from mt#697 work — lands separately, not in scope here).
• CLAUDE.md already carries the Design Principle: Humility (same — lands separately).
• docs/architecture.md, CONTRIBUTING.md — not affected; this is a positioning/framing change, not an architectural or workflow change.

---

(Had Claude look into this — AI-assisted review. The PR was also AI-drafted; this is a self-review, hence COMMENT rather than APPROVE.)

[minsky-reviewer]

Independent adversarial review (Chinese-wall)
Reviewer: minsky-reviewer[bot] via openai:gpt-5
Tier: unknown

---

Findings

• [NON-BLOCKING] README.md:73-81 — External Notion link may be inaccessible or incorrect

  • Evidence: The new subsection ends with “The full argument … is in the companion essay” linking to https://www.notion.so/34a937f03cb4814badbaf2e5cee38c08.
  • Risk: Readers without Notion access (private workspace) or if the UUID is mistyped will hit a 404, degrading the README’s usefulness.
  • Suggestion: Provide an in-repo fallback (e.g., a brief summary in docs/ with an internal link) or clearly mark the link as “external/internal access required.” If the intent is a public Notion doc, verify it’s publicly accessible post-merge. [NEEDS VERIFICATION: out-of-repo path — reviewer cannot verify]

• [NON-BLOCKING] README.md:65-81 — Placement and duplication risk

  • Evidence: The “Attention as the scarce resource” framing overlaps with existing high-level framing under “Design Philosophy” (README.md:116-136) and “Theory of Operation.”
  • Risk: Conceptual redundancy between “Why Minsky?” and “Design Philosophy” may blur section boundaries for first-time readers.
  • Suggestion: Consider adding a short cross-link from the “Design Philosophy” section back to this subsection or clarify in a single sentence how this framing complements the later “Design Philosophy.”

• [PRE-EXISTING] CLAUDE.md:5 — Broken internal cross-reference to docs/theory-of-operation.md

  • Evidence: CLAUDE.md says “Full framing: docs/theory-of-operation.md §Companion Principles.” No “Companion Principles” section exists in docs/theory-of-operation.md (verified full file).
  • Risk: Inconsistency may confuse contributors following cross-references.
  • Scope note: This is not introduced by the current PR; flagging for future cleanup.

• [NON-BLOCKING] Consistency of Notion references across docs

  • Evidence: docs/theory-of-operation.md links to “Notion: Vision & theory” with UUIDs beginning 33a9…, while the new README link references a different Notion UUID (34a9…).
  • Risk: Multiple Notion entry points with different documents can confuse readers about canonical sources.
  • Suggestion: Briefly label each link’s purpose (“Vision & theory,” “Companion essay on attention/ask taxonomy”) and ensure both are accessible. [NEEDS VERIFICATION: out-of-repo path — reviewer cannot verify]

Spec verification

• Adds a 6th subsection under “Why Minsky?” titled “Attention as the scarce resource”: Met (README.md:65-81)
• Existing 5 subsections unchanged (pure insertion): Met (diff shows insertion only; prior content retained)
• Register calibration (tighter, no VSM terms, 1–2 short paragraphs): Met (no VSM/System 5/3* wording; two short paragraphs plus one link line)
• Links to companion essay: Met, with accessibility caveat (see NON-BLOCKING finding above)
• Line budget under 210: Met per author’s claim; README currently 147 lines (author-stated; not independently counted here)

Documentation impact

• This PR updates the public landing surface (README). No additional architecture docs changes are strictly required.
• Consider adding an in-repo summary page for the “attention/ask taxonomy” and linking to it in addition to Notion, to reduce reliance on external/private content.
• Consider aligning or fixing the pre-existing cross-reference in CLAUDE.md to a real section in docs/theory-of-operation.md.

Conclusion

COMMENT