Problem
Round-2 review of the agent-memory spec removed four Ledger rows by hand (PR #10). The removals expose two guide-level rules that mis-promote decisions:
1. contradicted over-promotes low-stakes levers
The guide (§5.5) says a course self-contradiction becomes a Ledger row "even if the stakes look low," and §12.9 calls burying a contradicted decision in prose a defect. But three contradicted rows — vector distance strategy (cosine vs euclidean), index type (HNSW vs IVF), toolbox k (3 vs 5) — are tweakable levers, not architectural decisions: near-equivalent (distance, for normalized embeddings), a scaling-only concern (index, moot at fixture scale), or trivial (k). Forcing them to build-start gate questions is noise. The distance row's own trade-off cell even conceded "near-equivalent."
Proposed: a contradiction elevates provenance surfacing (record it in CTX-C) but does not override the stakes test. A near-equivalent / tunable contradiction becomes a body default (pick one, note the contradiction, mark it a post-build lever); only a contradiction where the options are materially different stays a Ledger row. The consistency invariant (e.g. "one distance strategy across all stores") stays a business rule + AC regardless — separate from the lever of which value.
2. design-argued rows shouldn't offer a taught best-practice as a neutral choice
The tool-exposure row presented semantic tool retrieval vs "pass all tools" as equal options. But Lesson 4 teaches semantic retrieval as the way to scale tool use — "pass all tools" is the anti-pattern it warns against. Presenting them neutrally invites the wrong choice.
Proposed: when a design-argued row's "argument" is really "the course teaches X as best practice," default X as baked-in behavior (a business rule), not a neutral-options Ledger row. Optionally, let the build agent judge relevance from the learner's build (e.g. tool count) rather than asking. The anti-pattern belongs in the Trade-off/CTX narrative, not as an equal Option.
Concrete signal
After PR #10, the agent-memory spec has zero contradicted rows and no tool-exposure row, yet loses no behavior — every invariant moved to a rule/AC/§2 default. That's the evidence these rows were mis-promoted.
Sequencing
PR #10 hand-edited the spec ahead of the guide. Until this issue is implemented, regenerating the agent-memory spec will re-introduce the four rows. The durable fix is here; then regenerate and confirm the rows stay gone.
Relates to #8 (guide residuals).
🤖 Generated with Claude Code
Problem
Round-2 review of the agent-memory spec removed four Ledger rows by hand (PR #10). The removals expose two guide-level rules that mis-promote decisions:
1.
contradictedover-promotes low-stakes leversThe guide (§5.5) says a course self-contradiction becomes a Ledger row "even if the stakes look low," and §12.9 calls burying a contradicted decision in prose a defect. But three contradicted rows — vector distance strategy (cosine vs euclidean), index type (HNSW vs IVF), toolbox k (3 vs 5) — are tweakable levers, not architectural decisions: near-equivalent (distance, for normalized embeddings), a scaling-only concern (index, moot at fixture scale), or trivial (k). Forcing them to build-start gate questions is noise. The distance row's own trade-off cell even conceded "near-equivalent."
Proposed: a contradiction elevates provenance surfacing (record it in CTX-C) but does not override the stakes test. A near-equivalent / tunable contradiction becomes a body default (pick one, note the contradiction, mark it a post-build lever); only a contradiction where the options are materially different stays a Ledger row. The consistency invariant (e.g. "one distance strategy across all stores") stays a business rule + AC regardless — separate from the lever of which value.
2.
design-arguedrows shouldn't offer a taught best-practice as a neutral choiceThe tool-exposure row presented semantic tool retrieval vs "pass all tools" as equal options. But Lesson 4 teaches semantic retrieval as the way to scale tool use — "pass all tools" is the anti-pattern it warns against. Presenting them neutrally invites the wrong choice.
Proposed: when a
design-arguedrow's "argument" is really "the course teaches X as best practice," default X as baked-in behavior (a business rule), not a neutral-options Ledger row. Optionally, let the build agent judge relevance from the learner's build (e.g. tool count) rather than asking. The anti-pattern belongs in the Trade-off/CTX narrative, not as an equal Option.Concrete signal
After PR #10, the agent-memory spec has zero contradicted rows and no tool-exposure row, yet loses no behavior — every invariant moved to a rule/AC/§2 default. That's the evidence these rows were mis-promoted.
Sequencing
PR #10 hand-edited the spec ahead of the guide. Until this issue is implemented, regenerating the agent-memory spec will re-introduce the four rows. The durable fix is here; then regenerate and confirm the rows stay gone.
Relates to #8 (guide residuals).
🤖 Generated with Claude Code