diff --git a/conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md b/conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md index 4c8dbc5c..7a2da25e 100644 --- a/conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md +++ b/conductor/tracks/nagent_review_20260608/nagent_review_v3_20260619.md @@ -430,7 +430,62 @@ The `{ssdl}` markers note the abstractions: `scan` is an inspectable transformat ## §8 Operating rules -(filled in by Phase 9 — covers `a1f0680` + cross-refs Fable) +**Source:** nagent `a1f0680` (`context/data-oriented-design.md:102-116` + `:151-164`); cross-ref `conductor/tracks/fable_review_20260617/`. +**One-liner:** Sampling justifies *replacing* the machine, not only trimming it. The data's shape can show that a different algorithm or representation is the better-fit machine — and a plateau in optimization is the signal to re-sample, not the signal to keep filing. The simplification pass gains a ninth question. +**Pattern(s) vs v2.3:** UPDATE. v2.3 cited `context/data-oriented-design.md` as Acton's canonical rule set; v3 deep-dives the Q9 expansion (the only addition since v2.3 was published on 2026-06-12). The Q9 insight generalizes v2.3 Pattern 1 ("durable work, disposable workers") — replacing the machine is a more radical form of "trimming the machine" that the original 8-question pass did not surface. The project's own `conductor/code_styleguides/data_oriented_design.md` is itself derived from Acton's file (per `conductor/code_styleguides/data_oriented_design.md` header); v3's §8 surfaces the delta so the project's styleguide can track. +**Manual Slop implications:** Manual Slop's `conductor/code_styleguides/data_oriented_design.md` (Tier 0/1/2, simplification pass, enforceable deliverables) is the canonical reference for agent directives. The Q9 addition is the "what's new since v2.3" delta; if the project styleguide adopts Q9 explicitly, agents applying it will know to consider "different machine" rather than only "trim current machine" when sampling points to a plateau. +**Decision candidate:** NEW Candidate 24 (LOW). "Document Q9 ('consider a different machine') in the project's `conductor/code_styleguides/data_oriented_design.md`" — the styleguide is already a derivative of nagent's file; add the Q9 expansion as a Tier 1+ reading-note. See `decisions.md` Candidate 24. +**Cross-refs:** `conductor/tracks/fable_review_20260617/` — Fable's analysis of "watch-dogging" is the opposite pattern. Fable's persona framing ("be careful, watch yourself") substitutes for the data-oriented question "what does the data say?". §8 closes the loop: Acton's operating rules are the data-grounded alternative. +**Source-read citations:** +- `context/data-oriented-design.md:102-116` — "Sample the data you already have" expanded: "the data's *shape* can show that a **different algorithm or representation is the better-fit machine** (sorted-enough → a different sort/merge; skewed → a different code; runny → a run/stream form; sparse → a different container), not just that the current machine needs filing. Sampling justifies *replacing* the machine, not only trimming it. Sampling is also how you find *new* opportunities mid-optimization, not just before starting: when a pass **stalls or plateaus**, that is the signal to re-sample the hottest stage's data and ask whether a different machine fits it better — not to keep filing the current one." (a1f0680) +- `context/data-oriented-design.md:151-164` — new Q9 in simplification pass: "Is there a **different algorithm or representation that fits the data better** than the current machine? Subtraction has a floor; when filing the current approach stops paying (a plateau), the win is often a *different* machine the data's shape points to — reconsider the approach, don't only shrink it." (a1f0680) +- `context/data-oriented-design.md:18-39` — Scope, tiers, and precedence (Tier 0 trivial, Tier 1 non-trivial change, Tier 2 subsystem-scale); "An explicit instruction from the user for the current task" wins over this document (the precedence rule) +- `context/data-oriented-design.md:41-58` — 3 defaults to reject (tools-are-platform, model-of-world, solution-matters-more) +- `context/data-oriented-design.md:60-78` — 8 core defaults (problem-is-data, state-cost, solve-only-problem-you-have, where-theres-one-theres-many, common-case-dominates, exploit-constraints, simplicity-is-removing-work, cant-be-done-is-cost-claim) +- `context/data-oriented-design.md:82-125` — Get the real data (inspect-before-assuming, sample, label-every-assumption, never-fabricate) +- `context/data-oriented-design.md:130-148` — Method (frame → get-data → state-cost → design-transform → simplification-pass → define-done → verify) +- `context/data-oriented-design.md:156-176` — Design rules (minimize-states, explicit-OOR, complexity-requires-evidence) +- `context/data-oriented-design.md:182-191` — Performance claims (never assert unmeasured; label hypotheses) +- `context/data-oriented-design.md:198-227` — Software specifics (batch-first, memory layout, data protocols, hardware is platform) +- `context/data-oriented-design.md:233-243` — Enforceable deliverables (tier 2) +- `context/data-oriented-design.md:249-261` — Final self-check (the 10-question checklist) +**Honest gaps in this cluster:** +- The Q9 expansion is in `data-oriented-design.md` but nagent itself doesn't have a worked example of "replace the machine" reasoning in its commits (the case studies — §10, §11 — demonstrate it empirically but the rules file does not name the pattern). A future track could add a worked example. +- The project's `conductor/code_styleguides/data_oriented_design.md` is derived from this file but may not include the Q9 addition. The v3 delta is the trigger to verify. +- The "stalls or plateaus" signal is a heuristic. When is "the pass is done" vs "the pass is plateauing"? The rule does not distinguish. A worked example would help. + +**Pattern deep-dive.** The Q9 expansion is the most subtle single-commit change in v3. The original 8-question simplification pass (Q1: not do this at all? Q2: only once? Q3: fewer times? Q4: approximate? Q5: small lookup? Q6: large lookup? Q7: small buffer/FIFO? Q8: constrain further?) is the radical form of "trim the machine." Q9 ("is there a different machine?") is the meta-level question — not "how do I shrink this?" but "is this the right machine at all?" The data's shape can tell you. The case studies (per §10, §11) are the empirical evidence: the PEP case study replaces a generic image-compression library with a tight per-image optimized one; the collisions case study replaces a generic convex primitive collision detection library with a per-type-specialized one. Both optimizations are "different machine," not "trim current machine." + +The connection to fable_review (§8 cross-ref) is the philosophical mirror. Fable's persona framing asks the model to "be careful, watch yourself, never claim something you can't verify." The data-oriented response is to ask "what does the data say?" — the verification is empirical (measure on real input), not persona-based (be appropriately humble). The fable review's "watch-dogging" pattern is the anti-pattern; the data-oriented sampling pattern is the pattern. Both can co-exist (a humble persona + measured data), but the data is load-bearing and the persona is decoration. + +The Tier 0/1/2 framing in `data-oriented-design.md:18-39` is also load-bearing. Tier 0 (trivial — apply defaults silently) is the project's escape hatch for one-line fixes; Tier 1 (non-trivial change — required: framing + data + simplification + self-check) is the standard; Tier 2 (subsystem-scale — tier 1 + enforceable deliverables) is the heavy path. The user's tier is decided at task start; the agent declares which tier it's picking. Manual Slop's `conductor/workflow.md` "Mandatory Research-First Protocol" and "Per-Task Decision Protocol" already encode tier-style discipline; the project's `conductor/code_styleguides/data_oriented_design.md` would close the loop. + +A code-shape sketch using survey grammar: + +``` +simplify-pass { current_machine, data_shape } :: improvements {ssdl} [S] + q1 := "can we not do this at all?" + q2 := "can we do this only once?" + q3 := "can we do this fewer times?" + q4 := "can we approximate?" + q5 := "can we use a small lookup table?" + q6 := "can we use a large lookup table?" + q7 := "can we use a small buffer/FIFO?" + q8 := "can we constrain the problem further?" + q9 := "is there a different machine that fits the data better?" // NEW: a1f0680 + // Q1-Q8 trim; Q9 replaces. Q9 is the meta-question. + +sample { current_machine, hottest_stage } :: next-action + // per a1f0680: when a pass stalls or plateaus, re-sample, don't keep filing + if plateau detected: + shape := sample(hottest_stage) + if shape suggests different machine -> replace (Q9) + else -> trim (Q1-Q8) +``` + +The `{ssdl}` [S] markers note the abstractions: the simplification pass is a string of questions (S); the sampling decision is a deterministic string assembly (S) based on data on disk. + +The Q9 expansion generalizes v2.3 Pattern 1 ("durable work, disposable workers") — replacing the machine is a more radical form of "disposable" that the original pass did not surface. The project's `conductor/code_styleguides/data_oriented_design.md` should adopt Q9 to keep the operating rules current. ## §9 Case-study methodology