Conversation
Curated library of canonical .kcad.ts pattern snippets, indexed for in-prompt retrieval. Distinct from corpus expansion (cookbook is for agents to reference, corpus is for evaluation). Continuous. v1 scope: - 12 starter pattern snippets seeded from eval expert solutions and the documented kernel surface - Markdown frontmatter file format (id, title, tags, keywords, when_to_use, fenced TS body) - BM25 retrieval over title/tags/keywords/when_to_use; score floor 0.5; ~40 LoC pure TS, no external deps - Hybrid agent surface: build-generated SKILL.md cookbook index + MCP tool lookup_cookbook(query, k) - Eval --cookbook flag with pre-injection (separate cache_control block); A/B golden test on bracket-holes - CI gates: validate frontmatter, evaluate every body clean, diff-check generated SKILL.md section - Continuous growth contract: same-PR additions, eval-driven additions, snapshot-test gate on ranking shifts Native-framed per the no-competitor-refs rule. Lineage captured in ~/.claude/projects/-home-andrii/memory/kernelcad_design_lineage.md under '#22 cookbook with retrieval (2026-05-03) — design-time lineage'.
19 tasks (102 bite-sized steps) covering: - yaml dep + tags whitelist + 12 starter snippets - Pure BM25 retrieval module (~60 LoC, no deps) - Snippet loader with frontmatter + tag-whitelist validation - search() composition with score floor + k clamping - 3 CI gates (validate, evaluate, build) wired into qc - SKILL.md cookbook index generator + diff-check - MCP tool lookup_cookbook - TranscriptEvent kind cookbook_inject + renderer - AgentClient systemAddendum (separate cache_control block) - Eval --cookbook flag + per-task pre-injection - A/B golden test on bracket-holes - npm run eval:ab convenience script - CHANGELOG entry TDD throughout (test before implementation). Frequent commits (one per task). Ready for subagent-driven-development execution. Spec lineage: docs/superpowers/specs/2026-05-03-cookbook-with-retrieval-design.md (2ab8190).
…nto qc - Add cookbook:validate, cookbook:evaluate, and cookbook:build to qc script - Add git diff --exit-code check on src/skill/SKILL.md to catch drift - Fix lint error: remove unused import of loadSnippets (re-exported via export statement)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Workstream #22 from the v0.2-to-v1.0 gap-closure roadmap (§I4). Adds a self-growing pattern library that the agent can search at runtime.
.kcad.tssnippets undercookbook/snippets/(edge features, booleans, holes, sketches, symmetry, parameters). Markdown + YAML frontmatter + fenced TS body. Tag whitelist atcookbook/tags.json.src/cookbook/—search(query, snippets, k=3)over title + tags + keywords + when_to_use. Score floor 0.5, k clamped to [1, 5]. ~60 LoC, no external deps. Snapshot test locks ranking on 5 queries.lookup_cookbook(query, k?)registered alongside the existing 14 tools. Empty-hits is a valid success.<!-- COOKBOOK:START/END -->markers. CI gate via diff-check.--cookbookflag — pre-injects top-3 hits into a separatecache_controlblock on the system prompt. A/B golden test (eval/cookbook.test.ts) locks deterministic ranking.npm run eval:ab— runs the suite twice (off/on) and prints score / token delta.npm run qc:cookbook:validate+cookbook:evaluate+cookbook:build+ SKILL.md diff-check.Test Plan
npm test— 959 passing, 25 skipped (rebased on develop @ c3de52d after feat(v0.21): synchronized live-build demo automation + 3 demo sets #58 landed)lookup_cookbookvia MCP returns top-3 BM25 hitsnpm run eval:absmoke run shows the cookbook injection diff