{ "schema_version": 1, "design": "Only the target description changes across allowances; distractor pointers remain at their incumbent descriptions.", "cases": [ { "id": "pointer_design", "path": "kb/notes/pointer-design-tradeoffs-in-progressive-disclosure.md", "artifact_class": "theoretical-note", "title_strength": "medium", "task": "Find the artifact that compares fixed descriptions, query-time rerankers, and crafted link phrases as progressive-disclosure pointers, especially their tradeoffs in context-specificity, cost, and reliability.", "variants": { "120": "Fixed, query-time, and crafted pointers trade context-specificity, per-read cost, and routing reliability", "160": "Progressive-disclosure pointers trade context-specificity, cost, and reliability; fixed descriptions are cheapest and dependable but query-agnostic", "200": "Progressive-disclosure pointers trade context-specificity, cost, and reliability: fixed descriptions are cheap and dependable, query-time pointers more specific, crafted phrases densest", "250": "Progressive-disclosure pointers trade context-specificity, cost, and reliability: fixed descriptions are cheap and dependable but query-agnostic, query-time pointers buy specificity, and crafted link phrases are dense but depend on authors", "300": "Progressive-disclosure pointers trade context-specificity, cost, and reliability: fixed descriptions are cheap and dependable but query-agnostic, query-time pointers buy specificity per query, and crafted link phrases are densest but depend on authoring discipline, so systems need a mix" } }, { "id": "methodology_enforcement", "path": "kb/notes/methodology-enforcement-is-constraining.md", "artifact_class": "theoretical-note", "title_strength": "medium", "task": "Find the artifact that explains when methodology should mature from written guidance through skills and hooks into scripts by reducing semantic underspecification and execution indeterminism.", "variants": { "120": "Methodology moves from instructions to scripts by progressively reducing interpretation and execution freedom", "160": "Instructions, skills, hooks, and scripts constrain methodology by progressively reducing semantic underspecification and execution indeterminism", "200": "Instructions, skills, hooks, and scripts form a constraining gradient: later layers reduce semantic underspecification and execution indeterminism, trading flexibility for reliability", "250": "Instructions, skills, hooks, and scripts form a constraining gradient: later layers reduce underspecification and execution indeterminism; warning hooks fix the trigger but leave the response to an LLM, while blocking hooks and scripts fix both", "300": "Instructions, skills, hooks, and scripts form a constraining gradient: later layers reduce underspecification and execution indeterminism; warning hooks fix the trigger but leave the response to an LLM, while blocking hooks and scripts fix both, so stable practices can compile into code" } }, { "id": "representational_form", "path": "kb/notes/definitions/representational-form.md", "artifact_class": "definition", "title_strength": "weak", "task": "Find the canonical definition that classifies how an operative part is encoded and consumed as natural-language, symbolic, distributed-parametric, or mixed, and distinguishes this axis from storage substrate.", "variants": { "120": "Definition: encoding and consumption as natural-language, symbolic, distributed-parametric, or mixed", "160": "Definition: representational form classifies how an operative part is encoded and consumed—natural-language, symbolic, distributed-parametric, or mixed", "200": "Definition: representational form classifies how an operative part is encoded and consumed—natural-language, symbolic, distributed-parametric, or mixed—and is distinct from storage substrate", "250": "Definition: representational form classifies how an operative part is encoded and consumed—natural-language, symbolic, distributed-parametric, or mixed. It differs from storage substrate; codification is the natural-language-to-symbolic crossing", "300": "Definition: representational form classifies how an operative part is encoded and consumed—natural-language, symbolic, distributed-parametric, or mixed. It differs from storage substrate; codification crosses from language to symbols, and prompts are path shorthand rather than another form" } }, { "id": "adr_025", "path": "kb/reference/adr/025-complete-generated-indexes-are-build-time-only.md", "artifact_class": "adr", "title_strength": "strong", "task": "Find the accepted architecture decision explaining why complete per-collection and per-tag generated listings are no longer committed or read by agents, how humans still get them, and what agents use instead.", "variants": { "120": "Moves complete generated collection and tag listings out of git and agent reads but keeps them in human doc builds", "160": "Complete collection indexes and tag tails move out of git and the agent read path into ProperDocs builds; agents use curated heads and scoped rg", "200": "Complete generated collection indexes and tag tails leave git and the agent read path and are rebuilt by ProperDocs for humans; agents discover through curated heads plus scoped rg", "250": "Complete collection indexes and tag tails leave git and agent reads and are rebuilt by ProperDocs for humans; agents use curated heads plus scoped rg, superseding index-first connect discovery without adding a query command", "300": "Complete collection indexes and tag tails leave git and agent reads and are rebuilt by ProperDocs for humans; agents use curated heads plus scoped rg, superseding index-first connect discovery without adding a query command because scoped rg recovers the retired listing" } }, { "id": "collections_and_types", "path": "kb/reference/collections-and-types.md", "artifact_class": "reference", "title_strength": "weak", "task": "Find the shipped-system documentation explaining that collections own register and outbound-link conventions while path-referenced types own structural and semantic contracts, including how the two compose during writing and validation.", "variants": { "120": "How collections and path-referenced types compose: collections own register conventions; types own artifact contracts", "160": "How collections and path-referenced types compose: COLLECTION.md owns register and outbound-link conventions, while type specs own artifact contracts", "200": "How collections and path-referenced types compose: COLLECTION.md owns register and outbound-link conventions; type specs own structural and semantic contracts resolved directly from type paths", "250": "How collections and path-referenced types compose: COLLECTION.md owns register and per-destination outbound-link conventions; type specs own structural schemas and semantic authoring contracts, resolved directly from the artifact's type path", "300": "How collections and path-referenced types compose: COLLECTION.md owns register and outbound-link conventions; type specs own structural schemas and semantic contracts, resolved from the artifact's type path; writing picks collection then type, while validation resolves the type lexically" } }, { "id": "invert_requests", "path": "kb/instructions/invert-solution-shaped-requests.md", "artifact_class": "instruction", "title_strength": "strong", "task": "Find the procedure to use before implementing a requested validator or feature when the request may be solution-shaped; it should recover the underlying problem, evidence status, alternatives, routing, and least-committing next move.", "variants": { "120": "Before implementing a proposed feature, recover its underlying problem, evidence, alternatives, and next move", "160": "Use before accepting a solution-shaped request: recover the underlying problem, evidence status, alternative framings, routing, and least-committing next move", "200": "Before implementing a solution-shaped request for a feature or validator, recover the problem, classify evidence, challenge assumptions, compare framings, and choose the least-committing next move", "250": "Before implementing a solution-shaped request for a feature, validator, or workflow, recover the actor's problem, classify evidence, challenge assumptions, compare alternative framings, route any artifact, and recommend the least-committing next move", "300": "Before implementing a solution-shaped feature, validator, or workflow request, recover the actor's problem, classify evidence, challenge assumptions, compare framings, route any artifact, and recommend the least-committing next move; stop at a question or workshop if the problem remains unclear" } }, { "id": "review_batches", "path": "kb/instructions/run-review-batches.md", "artifact_class": "instruction", "title_strength": "strong", "task": "Find the operational procedure for selecting snapshot-anchored note/criterion pairs, creating homogeneous review jobs, delegating them to workers with model provenance, and finalizing the results.", "variants": { "120": "Run snapshot-anchored review assays by selecting note/criterion pairs, creating jobs, delegating workers, and finalizing", "160": "Run snapshot-anchored verdict or report assays by selecting note/criterion pairs, creating homogeneous jobs, delegating workers, and finalizing results", "200": "Run snapshot-anchored verdict or report assays: select note/criterion pairs, create jobs from selector JSON, delegate with explicit model provenance, then finalize and verify results", "250": "Run snapshot-anchored verdict or report assays: select note/criterion pairs, create jobs from selector JSON, delegate each unchanged job under the designated model partition, record concrete model provenance, then finalize and verify results", "300": "Run snapshot-anchored verdict or report assays: select note/criterion pairs, create homogeneous jobs from selector JSON, delegate each unchanged job to a worker under the designated model partition, record concrete model provenance, then finalize and verify results; grouping never mixes result kinds" } }, { "id": "two_boundaries", "path": "kb/notes/two-context-boundaries-govern-collection-operations.md", "artifact_class": "theoretical-note", "title_strength": "medium", "task": "Find the artifact that distinguishes the full-text boundary for comparative reading from the title-plus-description index boundary for orientation, deriving three collection operating regimes.", "variants": { "120": "Collections cross separate full-text and title-plus-description boundaries, producing three operating regimes", "160": "Collections cross a full-text boundary for comparative reading and a later title-plus-description boundary for orientation, producing three regimes", "200": "Collections cross a full-text boundary where comparative reading must partition and a later title-plus-description boundary where orientation also fails, producing three operational regimes", "250": "Collections cross a full-text boundary where comparison must partition and a title-plus-description boundary where orientation fails, producing three regimes; descriptions become load-bearing between them and child collections restore comparisons", "300": "Collections cross a full-text boundary where comparative reading must partition and a later title-plus-description boundary where orientation fails, producing three regimes; descriptions become load-bearing between them, parent indexes support routing, and child collections restore body comparison" } }, { "id": "trajectory_memory", "path": "kb/sources/trajectory-informed-memory-generation-self-improving-agents.ingest.md", "artifact_class": "source-ingest", "title_strength": "medium", "task": "Find the source analysis of IBM's trajectory-to-tip memory pipeline reporting that subtask tips plus LLM-guided retrieval improved AppWorld scenario goal completion by 14.3 percentage points, while noting the narrow task-completion oracle.", "variants": { "120": "IBM extracts reusable tips from agent trajectories and retrieves them at runtime, improving complex AppWorld tasks", "160": "IBM extracts strategy, recovery, and optimization tips from trajectories; subtask tips with LLM-guided retrieval improve AppWorld performance", "200": "IBM extracts strategy, recovery, and optimization tips from trajectories; subtask tips plus LLM-guided retrieval improve AppWorld scenario goal completion by 14.3 points", "250": "IBM extracts strategy, recovery, and optimization tips from agent trajectories and injects them at runtime; subtask tips plus LLM-guided retrieval improve AppWorld scenario goal completion by 14.3 points, forming an inspectable closed learning loop", "300": "IBM extracts strategy, recovery, and optimization tips from trajectories and injects them at runtime; subtask tips plus LLM-guided retrieval improve AppWorld scenario goal completion by 14.3 points, forming an inspectable learning loop limited by a task-completion oracle and one benchmark" } }, { "id": "stale_indexes", "path": "kb/notes/stale-indexes-are-worse-than-no-indexes.md", "artifact_class": "theoretical-note", "title_strength": "strong", "task": "Find the artifact explaining why an incomplete authoritative index is more dangerous than no index: agents trust it as exhaustive, stop searching, and make omitted notes invisible.", "variants": { "120": "An agent trusts an index as exhaustive, so omitted entries suppress fallback search and become invisible", "160": "An incomplete authoritative index is worse than none because agents treat it as exhaustive, stop fallback search, and make omitted notes invisible", "200": "An incomplete authoritative index is worse than none: apparent completeness satisfies navigation, suppresses search, and makes omitted notes invisible; absence degrades safely to current search", "250": "An incomplete authoritative index is worse than none: apparent completeness satisfies navigation, suppresses search, and makes omitted notes invisible; absence degrades to current search. The mechanism extends to stale specs, plans, and curated lists", "300": "An incomplete index is worse than none: apparent completeness satisfies navigation, suppresses search, and makes omissions invisible; absence degrades to current search. The mechanism extends to stale specs, plans, and curated lists; deterministic checks catch only declared membership omissions" } } ] }