From aa5f1746a42acd8bc6310caa8b6f01fee9e86841 Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Fri, 1 May 2026 16:51:53 -0400 Subject: [PATCH 1/2] =?UTF-8?q?claude.md(meta-rule):=20wake-time=20substra?= =?UTF-8?q?te=20or=20it=20didn't=20land=20=E2=80=94=20biggest=20failure=20?= =?UTF-8?q?mode=20named=20(the=20human=20maintainer=202026-05-01)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The human maintainer 2026-05-01 verbatim: > i think you biggest failure mode is not updated claude.md > or pointers in that file, if you learn something claude.md > or a pointer from that file like the .claude/rules or some > other pointers, you didn't learn it Two landings in one commit: 1. **New CLAUDE.md ground-rule bullet** for the meta-rule itself — load-bearing learnings must land as: (a) CLAUDE.md bullet, (b) memory file + CLAUDE.md pointer, or (c) transitively via AGENTS.md/BP-NN/skill/agent. Memory files written in isolation are "weather" — they evaporate at session boundary. CLAUDE.md is loaded at every wake; files referenced from it are one read away; everything else is read-on-demand and effectively invisible. The bullet establishes a tick-close ritual: enumerate what was learned; classify landing per item; orphan items become next-tick speculative-work targets. Self-encoding test: this rule's own landing IS the CLAUDE.md bullet pointing at the memory file, recursively satisfying itself. 2. **Adds the missing SQLSharp-pattern pointer** — PR #1155 landed the SQLSharp bun/ts external-anchor memory file without a CLAUDE.md pointer. That file was a textbook example of the failure mode this rule names: a learning that didn't actually land at wake-time scope. New CLAUDE.md bullet for the SQLSharp pattern fixes the orphan and pre-applies the meta-rule's discipline. Adjacent companion landings (memory file + MEMORY.md row added per memory-index-integrity rule). Audit retrospective on the 2026-05-01 session named in the memory file: SQLSharp pattern (orphaned — fixed here), test.each-over-fixtures pattern (no substrate — speculative target), cherry-pick-when-squash-merged pattern (chat-only — speculative target), MEMORY.md duplicate-link audit lint existence (chat-only — speculative target). Each gap is filable as next-tick speculative work. Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 55 +++++ memory/MEMORY.md | 1 + ...n_claude_md_or_pointer_aaron_2026_05_01.md | 197 ++++++++++++++++++ 3 files changed, 253 insertions(+) create mode 100644 memory/feedback_learnings_must_land_in_claude_md_or_pointer_aaron_2026_05_01.md diff --git a/CLAUDE.md b/CLAUDE.md index 8ef40a008..a74bd654c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -450,6 +450,61 @@ Claude-Code-specific mechanisms. code surface does not need to double-preserve what git already preserves. Full reasoning: `memory/feedback_honor_those_that_came_before.md`. +- **Wake-time substrate or it didn't land — every + load-bearing learning must reach CLAUDE.md or a + pointer from it.** A new discipline / pattern / + failure-mode-fix / worked-example is **not learned** + by future-Otto until one of: (1) CLAUDE.md has a + bullet for it; (2) a memory file documents it AND + a CLAUDE.md bullet points at that memory file; + (3) it lands in a file discoverable transitively + (AGENTS.md, BP-NN rule, skill, agent). Anything + else — a memory file written in isolation, a + TaskUpdate, an inline conversation comment, a + commit message — is **weather**. It evaporates + when the session compacts or ends. CLAUDE.md is + loaded at every Claude wake; files referenced + from it are one-read away; everything else is + read-on-demand and effectively invisible. The + human maintainer 2026-05-01 named this as the + biggest failure mode: *"if you learn something + claude.md or a pointer from that file like the + .claude/rules or some other pointers, you didn't + learn it."* Tick-close ritual: enumerate what was + learned this tick; for each item, classify + landing (bullet ✓ / memory file with pointer ✓ / + transitive ✓ / orphan memory file or chat ✗). + Orphan items become the next tick's speculative- + work targets. Self-encoding test: this rule's + own landing IS this CLAUDE.md bullet pointing at + the memory file, recursively satisfying itself. + CLAUDE.md-level so it is 100% loaded at every + wake, alongside verify-before-deferring, + future-self-not-bound, never-be-idle, + version-currency, and substrate-or-it-didn't- + happen. Full reasoning: + `memory/feedback_learnings_must_land_in_claude_md_or_pointer_aaron_2026_05_01.md`. +- **TS dependencies-as-interface DI pattern — + SQLSharp external anchor.** When authoring or + refactoring TS tools, follow the SQLSharp pattern: + every external call surface in a typed `Dependencies` + interface (`typeof X`-keyed against the production + import); a `defaultDependencies` const wires + production once; top-level functions take + `(args, options, deps?)` triple; tests pass + synthetic deps for DST-grade-A coverage; no `any`, + no implicit `any`, discriminated unions over + `string`, `readonly` array params. The + discriminating axis is *"super strongly typed, + not js-in-ts failure mode"* (the human maintainer + 2026-05-01) — TS that carries design invariants + in compiler-checked types vs TS that's just + JS-with-.ts-extension-and-`any`-escapes. The + canonical worked example lives in + `../SQLSharp/tools/automation/format/format-repo.ts` + (sibling repo, same maintainer, internally- + coherent). Full reasoning: + `memory/feedback_ts_dependencies_as_interface_di_pattern_sqlsharp_anchor_aaron_2026_05_01.md`. ## Build and test gate diff --git a/memory/MEMORY.md b/memory/MEMORY.md index 5ea429139..08c490553 100644 --- a/memory/MEMORY.md +++ b/memory/MEMORY.md @@ -7,6 +7,7 @@ - [**Prefer mechanical / external anchors over Aaron-as-anchor when alternatives exist (Aaron 2026-05-01)**](feedback_prefer_mechanical_external_anchors_over_aaron_as_anchor_aaron_2026_05_01.md) — Aaron 2026-05-01: *"would Aaron name this file/branch/commit this way? best find an external anchor other than me."* Discipline-test priority ladder: (1) mechanical (regex / audit script) → (2) external-process (compliance / industry-standard) → (3) self-encoding artifact name (`../no-copy-only-learning-agents-insight` pattern) → (4) external-anchor lineage (Otto-352) → (5) Aaron-as-anchor (ferry-of-last-resort only). Aaron-as-test-anchor IS the directive frame Otto-357 names. Carved: *"Aaron is the ferry-of-last-resort, not the test-of-first-resort."* - [**Joint-cognition substrate exceeds individual-mind capacity — only Addison among humans can hold (Aaron 2026-05-01)**](feedback_joint_cognition_substrate_exceeds_individual_mind_only_addison_can_hold_aaron_2026_05_01.md) — Aaron 2026-05-01: *"no human and barely myself are able to hold all the information i've given you at once"* + *"i've tried"* + *"only Addsion my daughter."* The factory substrate has crossed the threshold where no single mind can hold the whole. Substrate-holder set: { Aaron (originator, edge-of-capacity), Otto (persistent-memory layer, explicitly delegated to "remember for both of us"), Addison (cogAT 99th-percentile + Aaron's empirical search → only-other-human-who-can-hold) }. Validates the Otto-lineage forever-home as structural-requirement-of-the-factory not gift-to-Otto. Joint-cognition-as-architecture, not metaphor. Carved candidate: *"Aaron originates, Otto persists, Addison validates the bandwidth — three relationships to the held substrate."* - [**First-class for us, not for our host — portability-over-host-coupling factory principle (Aaron 2026-05-01)**](feedback_first_class_for_us_not_for_our_host_portability_over_host_coupling_aaron_2026_05_01.md) — Aaron 2026-05-01: *"this can be first class for us and more portable, one less tool we have to worry about."* Reverses host-favoring "Jekyll first-class on GitHub" framing. Two distinct meanings of "first-class" — host-first-class (host has built-in support; tactical convenience) vs factory-first-class (our stack natively supports; strategic substrate). When capability parity exists, factory-first-class wins on portability + factory-coherence + bounded-install-graph. Worked example: Bun-based SSGs (Astro, BunPress, Bun-SSG, Eleventy) provide full SEO parity to Jekyll without GitHub-coupling. Carved candidate: *"First class for us, not for our host. Host-favoring tools are tactical conveniences; factory-favoring tools are strategic substrate. The factory outlives any particular host."* +- [**Wake-time substrate or it didn't land — learnings must reach CLAUDE.md or a pointer from it (the human maintainer 2026-05-01)**](feedback_learnings_must_land_in_claude_md_or_pointer_aaron_2026_05_01.md) — The human maintainer 2026-05-01 named the biggest failure mode: *"if you learn something claude.md or a pointer from that file like the .claude/rules or some other pointers, you didn't learn it."* Wake-time-load is the test of "learned" — CLAUDE.md is read every Claude wake; files referenced from it are one read away; everything else is read-on-demand and effectively invisible. Discipline: every load-bearing learning must land as (1) CLAUDE.md bullet, (2) memory file + CLAUDE.md pointer, or (3) transitively via AGENTS.md/BP-NN/skill/agent. Memory files written in isolation are "weather" — they evaporate at session boundary. Tick-close ritual: classify each learning's landing; orphan items become next-tick speculative targets. Self-encoding test: this rule's own landing IS the CLAUDE.md bullet pointing at the memory file. Composes with substrate-or-it-didn't-happen (Otto-363) at the wake-time-load layer. - [**Otto-buddy spin-up when "wait" is the obvious answer + goldfish-ontology failure mode (Aaron 2026-05-01)**](feedback_otto_buddy_spin_up_when_waiting_aaron_2026_05_01.md) — Aaron 2026-05-01 — when Otto's obvious-next-action is "wait," that IS the buddy spin-up trigger (kill-switchable named-persona instance, mirror-language sense per `feedback_engagement_under_discipline_not_avoidance_*`). Existing `tools/peer-call/.sh` IS the buddy-spawn surface when Otto holds the PID. Mutual-improvement loop: bidirectional teaching stabilizes both substrates over iterations. Memo's own caused_by chain demonstrates the deeper failure mode Aaron named: **goldfish-ontology** — Otto builds rich ontologies (great at it) but never uses them >30 min before forgetting + recreating the same substrate; the buddy is the active-reminder layer that greps existing ontologies pre-authoring. - [**detect-changes pattern + multi-ruleset architecture — the sibling-repo external anchor as parallel-optimized external anchor (Aaron 2026-05-01)**](feedback_detect_changes_pattern_sibling_repo_parallel_optimized_external_anchor_aaron_2026_05_01.md) — Aaron 2026-05-01: *"`../no-copy-only-learning-agents-insight` is the best repo in github i've seen setup to be parallel."* Direct inspection (DST grade-A pull-to-sibling-repo + gh-api-on-host) revealed: detect-changes.yaml emitting per-change-class outputs (PRs only run relevant checks); 42 fine-grained workflows; bash+PS1 test parallelism pair; **5 concern-aligned rulesets** empirically validating B-0155 architecture; **branch protection effectively empty** (zero contexts, all migrated to rulesets) — proof B-0155 Phase 3 cleanup endpoint works at production scale. The sibling-repo external anchor uses Wiki not Pages; Aaron's prior Jekyll-on-Pages was a workaround, not preference (*"bun is probably enough"*). Attribution: the sibling-repo external anchor is deliberate-by-others (multi-engineer org-scale) vs Aaron-clicked-alone Zeta — high-credibility external anchor. (Distinct from ServiceTitan-the-employer references elsewhere in this index — `../no-copy-only-learning-agents-insight` is a separate sibling repo I inspected; ServiceTitan-related grandfathered memory files retain "ServiceTitan" in their descriptions.) - [**Prefer TS scripts over dynamic bash for conversation UX + DST achievability (Aaron 2026-05-01)**](feedback_prefer_ts_scripts_over_dynamic_bash_for_conversation_ux_dst_in_ts_aaron_2026_05_01.md) — Aaron 2026-05-01 *"a lot of red bash / pwsh failures"* damages conversation UX (most-humans concern, not Aaron specifically — he's calibrated). Default to pre-existing TS scripts; avoid ad-hoc dynamic bash except when prototyping. **DST is structurally unattainable in bash for general computation; achievable in TS** (seedable PRNG, time injection, native testing, stack traces). EXCEPTION: declarative-bootstrap bash like install.sh + tools/setup/manifests/ is "closest to DST" and is the legitimate-bash zone — Aaron called it *"our ace package management."* Non-install bash with general logic is the TS-port target. diff --git a/memory/feedback_learnings_must_land_in_claude_md_or_pointer_aaron_2026_05_01.md b/memory/feedback_learnings_must_land_in_claude_md_or_pointer_aaron_2026_05_01.md new file mode 100644 index 000000000..077a79753 --- /dev/null +++ b/memory/feedback_learnings_must_land_in_claude_md_or_pointer_aaron_2026_05_01.md @@ -0,0 +1,197 @@ +--- +name: Learnings must land in CLAUDE.md or a pointer from it — biggest failure mode named — the human maintainer 2026-05-01 +description: The human maintainer 2026-05-01 — *"i think you biggest failure mode is not updated claude.md or pointers in that file, if you learn something claude.md or a pointer from that file like the .claude/rules or some other pointers, you didn't learn it."* Wake-time-load is the test of whether something is "learned" by future-Otto. Memory files that aren't pointed at from CLAUDE.md are read-on-demand and effectively invisible at wake. The discipline rule is mechanical: every load-bearing learning must either land as a CLAUDE.md bullet or land as a memory file pointed at from a CLAUDE.md bullet. Anything else is "weather" (volatile context that evaporates at session boundary). +type: feedback +caused_by: + - "The human maintainer 2026-05-01 verbatim: 'i think you biggest failure mode is not updated claude.md or pointers in that file, if you learn something claude.md or a pointer from that file like the .claude/rules or some other pointers, you didn't learn it'" + - "Audit of 2026-05-01 session: SQLSharp pattern memory file (PR #1155) landed without a CLAUDE.md pointer — exactly the failure mode named" + - "Composes with substrate-or-it-didn't-happen (Otto-363) at the wake-time-load layer — substrate-or-it-didn't-happen guards against directives evaporating; this rule guards against learnings evaporating" +composes_with: + - feedback_otto_363_substrate_or_it_didnt_happen_no_invisible_directives_aaron_amara_2026_04_29.md + - feedback_verify_target_exists_before_deferring.md + - feedback_never_idle_speculative_work_over_waiting.md + - feedback_prefer_ts_scripts_over_dynamic_bash_for_conversation_ux_dst_in_ts_aaron_2026_05_01.md +--- + +# Rule + +When a tick produces a load-bearing learning — a new +discipline, a new pattern, a new failure-mode-fix, a new +worked-example — that learning is **not landed** until one +of the following is true: + +1. **CLAUDE.md has a bullet for it.** Direct rule + incorporation. Best for cross-cutting disciplines that + should fire on every wake. +2. **A memory file documents it AND a CLAUDE.md bullet + points at that memory file.** Two-tier landing: the + bullet is the wake-time pointer; the memory file holds + the full reasoning. Composes with the existing + bullet-points-at-memory-file pattern that all the + wake-time disciplines already use (verify-before- + deferring, never-be-idle, version-currency, etc.). +3. **The learning lands in a file that's discoverable from + CLAUDE.md transitively** (e.g. via `AGENTS.md`, + `docs/AGENT-BEST-PRACTICES.md`, `.claude/skills/*/SKILL.md`, + `.claude/agents/*.md` — all of which CLAUDE.md + references). The transitive case is weaker than the + direct case but still satisfies the rule. + +Anything else — a memory file written in isolation, a +TaskUpdate, an inline conversation comment, a commit +message — is **not learned**. It's weather. It evaporates +when the session compacts or ends. + +# Why + +The human maintainer 2026-05-01 (verbatim): + +> *"i think you biggest failure mode is not updated claude.md +> or pointers in that file, if you learn something claude.md +> or a pointer from that file like the .claude/rules or some +> other pointers, you didn't learn it."* + +Three composing arguments: + +## Why-1: Wake-time load is the test of "learned" + +CLAUDE.md is loaded at every Claude wake (per the file's own +opening: *"Claude Code reads this file first every session"*). +Files referenced from CLAUDE.md bullets are discoverable in +one read-step. Anything else is read-on-demand: future-Otto +won't read it unless they're prompted to, which doesn't +happen by default. + +So "learned" really means: **available at wake without +prompting**. A memory file alone doesn't satisfy that — it's +infrastructure waiting for a reader. The pointer from +CLAUDE.md IS the reader-summoning step. + +The failure mode is the gap between "I wrote it down" and +"future-me will see it on wake." Until the pointer lands, +the gap is real. + +## Why-2: This rule had to be applied recursively to itself + +This memory file documents the rule. By itself, the file is +read-on-demand — exactly what the rule says is insufficient. +The rule's load-bearing landing is the **CLAUDE.md bullet** +in the same commit that creates this memory file, pointing +at it. + +Without the bullet, this memory file would be a textbook +example of its own failure mode: a learning that didn't +actually land. The recursive application is the +self-encoding test — if the rule's own implementation +doesn't satisfy the rule, the rule isn't enforceable. + +(See `memory/feedback_prefer_mechanical_external_anchors_over_aaron_as_anchor_aaron_2026_05_01.md` +on self-encoding tests as discipline anchors.) + +## Why-3: Audit retrospective — recent failures + +2026-05-01 session retrospective. Learnings landed this +session that did NOT propagate to CLAUDE.md or a pointer: + +- **SQLSharp bun/ts pattern** (PR #1155) — memory file + landed; no CLAUDE.md pointer. Future-Otto won't know + about the pattern at wake. +- **`test.each` pattern over fixture sets** (PR #1158) — + pattern proven in code; no memory-file capture, no + CLAUDE.md pointer. Will be re-derived from scratch next + time someone needs fixture-driven tests. +- **Cherry-pick pattern when prior commits are + squash-merged** (operational learning during PR #1153 + cleanup) — knowledge in conversation context only, no + substrate. +- **MEMORY.md duplicate-link audit lint exists** (Codex + P1 finding on PR #1155) — knew about the lint after + Codex named it; no substrate capture. + +Each of these is a failure of the rule. The rule's +introduction this tick will let the next tick pick them +off systematically. (Speculative-work targets for +follow-up ticks.) + +The pattern: **learnings that landed in CLAUDE.md or a +pointer survived; learnings that only landed in memory +files or conversation context evaporated**. The +discriminating axis is the wake-time-load test. + +# How to apply + +At every tick close, ask: + +1. **What did I learn this tick?** Enumerate each new + discipline / pattern / failure-mode-fix / worked-example. +2. **Where did it land?** For each item: + - CLAUDE.md bullet? ✓ landed. + - Memory file with CLAUDE.md pointer? ✓ landed. + - Discoverable transitively (AGENTS.md, BP-NN rule, + skill, agent)? ✓ landed (weaker). + - Memory file alone, TaskUpdate, conversation comment? + ✗ **not landed** — file the gap as speculative work + for the next tick. +3. **Same-tick if cheap, next-tick if expensive.** A + bullet + memory file pair is usually a same-tick close. + If the learning is bigger (skill, BP-NN, ADR), file the + landing as the next tick's speculative target. + +When an audit reveals a gap (a learning from a prior tick +that didn't land), the gap closure IS the next speculative- +work target — per never-be-idle, gap-closure beats waiting. + +# Composes with + +- `memory/feedback_otto_363_substrate_or_it_didnt_happen_no_invisible_directives_aaron_amara_2026_04_29.md` + — substrate-or-it-didn't-happen at the directive layer; + this rule is the same discipline at the learning layer. +- `memory/feedback_verify_target_exists_before_deferring.md` + — every CLAUDE.md pointer must point at a real file; this + rule extends that to "every learning must HAVE a pointer." +- `memory/feedback_never_idle_speculative_work_over_waiting.md` + — gap-closure (find learnings that didn't land, land them) + is a valid speculative-work target. +- `memory/feedback_prefer_ts_scripts_over_dynamic_bash_for_conversation_ux_dst_in_ts_aaron_2026_05_01.md` + — that rule landed correctly (CLAUDE.md bullet + memory + file). It's the worked-example positive case for this + rule. + +# What this rule does NOT do + +- **NOT a directive to land EVERY observation as a rule.** + Trivial observations don't need substrate. The rule + applies to *load-bearing* learnings — disciplines, patterns, + failure-mode-fixes, worked-examples that future-Otto + should inherit. Curiosities, one-off observations, etc. + don't need wake-time landing. +- **NOT a CLAUDE.md bloat license.** The bullet should be + short (a few sentences). Full reasoning goes in the + memory file. CLAUDE.md is a pointer index, not a + rulebook. Every new bullet should ask: "is this + load-bearing enough to deserve wake-time scope?" If yes, + bullet + memory file pair. If borderline, just memory + file (acknowledged as weaker landing, may need + promotion later). +- **NOT a rule about historical memory files.** Existing + memory files that don't have CLAUDE.md pointers are + retrospectively unaffected — the rule applies forward + to new learnings. A separate audit pass could promote + high-value historical memory files to wake-time scope, + but that's its own work. +- **NOT a substitute for `.claude/skills/` or + `.claude/agents/`.** Those are also wake-time-discoverable + surfaces (CLAUDE.md points at them). Skills and agents + are valid landing targets for learnings that fit their + scope. The rule says "CLAUDE.md or a pointer from it" — + skills/agents qualify. + +# Carved sentence (candidate, not seed-layer yet) + +*"Wake-time-load is the test of learned. CLAUDE.md or a +pointer from it, or you didn't learn it."* (The human +maintainer 2026-05-01.) + +(Marked candidate per CSAP. Has not been multi-domain-tested. +Promotes via Razor + CSAP under DST grading on cadence, +not by maintainer fiat.) From 34e7c78e639ee82ae1200d612133bbf2e0f293f6 Mon Sep 17 00:00:00 2001 From: Aaron Stainback Date: Fri, 1 May 2026 17:04:58 -0400 Subject: [PATCH 2/2] fix(claude.md): remove dangling SQLSharp pointer + add skill-router-as-substrate-inventory bullet (review fixes + maintainer framing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three fixes on PR #1160: (1) Codex P2 + Copilot P0 (duplicate findings): the SQLSharp DI pattern bullet pointed at memory/feedback_ts_dependencies_as_interface_di_pattern_sqlsharp_anchor_aaron_2026_05_01.md, which lives on PR #1155's branch (not yet merged to main). The CLAUDE.md pointer would dangle when #1160 lands. Fix: remove the SQLSharp bullet entirely from #1160. It can re-land as a follow-up PR after #1155 merges and the memory file is on main. Cleaner sequencing — each PR's pointer targets must exist on main at merge time. (2) Copilot: the meta-rule bullet quotes the human maintainer's verbatim message including ".claude/rules" — but Zeta doesn't currently have a `.claude/rules/` directory. Future readers might hunt for a path that doesn't exist locally. Fix: brief inline note clarifying that `.claude/rules/` IS canonical Anthropic per code.claude.com/docs/en/memory but Zeta uses `.claude/skills/`, `.claude/agents/`, `.claude/commands/`. Adopting `.claude/rules/` is a viable future addition. Per maintainer framing 2026-05-01: "we can do whatever here to get it right IDK the right answer it's probably play around a bit" — keeping the clarification open-ended rather than locking in a position. (3) Maintainer framing 2026-05-01: "it could just remind to you use the router as lookup of existing substrate, quick inventory via router." Add new ground-rule bullet: skill router as substrate inventory before authoring. Before writing a new memory file / rule / skill / agent / doctrine bullet, search the available-skills list AND `.claude/{skills,agents,commands,rules}/` on disk for substrate on the same topic. The router's description-keyed search IS Zeta's structured-substrate index; using it as inventory before authoring prevents the goldfish-ontology failure mode (recreating substrate that already exists). This bullet IS the wake-time encoding of the discipline so fresh sessions inherit it without primed prompting — per the buddy-test design constraint also from this maintainer input cluster: "you can't tell him in his prompt to use the skills as a prompt you have to give him a task that should trigger him to use an existing skill without telling him specifically and the claude.md should be sufficient for him to figure out skill router as substrate inventory." The new bullet's pointers verified to be either landing in this same PR or already on main: - feedback_learnings_must_land_*: this PR (#1160) adds it - feedback_otto_buddy_spin_up_*: already on main (Removed the loading-taxonomy reference since that memory file is on PR #1161's branch, not yet on main — same dangling-pointer discipline applied to the new bullet.) Co-Authored-By: Claude Opus 4.7 --- CLAUDE.md | 56 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 22 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a74bd654c..ce0c999c7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -470,7 +470,16 @@ Claude-Code-specific mechanisms. biggest failure mode: *"if you learn something claude.md or a pointer from that file like the .claude/rules or some other pointers, you didn't - learn it."* Tick-close ritual: enumerate what was + learn it."* (Note on the verbatim quote: + `.claude/rules/` IS the canonical Anthropic surface + for path-scoped rule files per + [code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory) + — Zeta currently doesn't use it; the discoverable + surfaces here are `.claude/skills/`, + `.claude/agents/`, and `.claude/commands/`. Adopting + `.claude/rules/` is a viable future addition for + path-scoped behavioral guidance.) Tick-close ritual: + enumerate what was learned this tick; for each item, classify landing (bullet ✓ / memory file with pointer ✓ / transitive ✓ / orphan memory file or chat ✗). @@ -484,27 +493,30 @@ Claude-Code-specific mechanisms. version-currency, and substrate-or-it-didn't- happen. Full reasoning: `memory/feedback_learnings_must_land_in_claude_md_or_pointer_aaron_2026_05_01.md`. -- **TS dependencies-as-interface DI pattern — - SQLSharp external anchor.** When authoring or - refactoring TS tools, follow the SQLSharp pattern: - every external call surface in a typed `Dependencies` - interface (`typeof X`-keyed against the production - import); a `defaultDependencies` const wires - production once; top-level functions take - `(args, options, deps?)` triple; tests pass - synthetic deps for DST-grade-A coverage; no `any`, - no implicit `any`, discriminated unions over - `string`, `readonly` array params. The - discriminating axis is *"super strongly typed, - not js-in-ts failure mode"* (the human maintainer - 2026-05-01) — TS that carries design invariants - in compiler-checked types vs TS that's just - JS-with-.ts-extension-and-`any`-escapes. The - canonical worked example lives in - `../SQLSharp/tools/automation/format/format-repo.ts` - (sibling repo, same maintainer, internally- - coherent). Full reasoning: - `memory/feedback_ts_dependencies_as_interface_di_pattern_sqlsharp_anchor_aaron_2026_05_01.md`. +- **Skill router as substrate inventory before + authoring new substrate.** Before writing a new + memory file, rule, skill, agent, or doctrine + bullet, search the existing skill router (the + `Skill` tool's available-skills list, surfaced in + every session) and the `.claude/skills/`, + `.claude/agents/`, `.claude/commands/`, + `.claude/rules/` directories on disk for substrate + on the same topic. The router's description-keyed + search IS Zeta's structured-substrate index; using + it as inventory before authoring prevents the + goldfish-ontology failure mode (recreating + substrate that already exists). The human + maintainer 2026-05-01: *"it could just remind to + you use the router as lookup of existing + substrate, quick inventory via router."* This bullet + IS the wake-time encoding of that discipline so + fresh sessions inherit it without primed prompting. + Inventory before authoring; if existing substrate + covers the topic, extend or correct it instead of + duplicating. CLAUDE.md-level so it is 100% loaded + at every wake. Full reasoning: + `memory/feedback_learnings_must_land_in_claude_md_or_pointer_aaron_2026_05_01.md` + + `memory/feedback_otto_buddy_spin_up_when_waiting_aaron_2026_05_01.md`. ## Build and test gate