debug-plan-cache-misses — Claude Code skill: setup & debug
Finds Chalk plan cache misses by analyzing engine logs and diffing query payloads. Useful when repeated plan generation increases response latency.
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a claude-codeWhat debug-plan-cache-misses does
Chalk caches execution plans using the normalized BatchQuery as a key. When incoming requests force recalculations on the hot path, query latency spikes. This skill queries engine logs via the Chalk CLI, filters for cache miss lines, and pulls plan computation events.
It compares consecutive plan events field by field. Upstream callers frequently vary the given_features array between calls. That changes the cache key and triggers a full replan. The skill isolates mismatches across input features and planner options so you can spot why keys diverge.
Diagnosing issues requires access to the chalk CLI tool configured for the target environment. The skill only inspects logs and highlights differences; fixing the problem requires stabilizing payload structures in the calling service.
What it helps with
- locate plan cache miss events inside Chalk engine logs
- diff BatchQuery payloads to find mismatched given_features
- investigate latency spikes caused by query replanning
- filter log warnings via chalk logs CLI queries
Example prompts for the agent
- Check chalk logs for plan cache misses on sv5_idplus_features_parallel over the past 24 hours
- Diff the last two plan computations for my query and show which fields caused the miss
- Show the volume of missed the plan cache log warnings over the last 6 hours
How to install debug-plan-cache-misses
1Skills CLI (Vercel)
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a claude-code2Manually: put the files in place
~/.claude/skills/debug-plan-cache-misses/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/debug-plan-cache-misses/
1Skills CLI (Vercel)
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a codex2Manually: put the files in place
.agents/skills/debug-plan-cache-misses/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a cursor2Manually: put the files in place
.cursor/skills/debug-plan-cache-misses/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install chalk-ai/chalk-ai-plugins debug-plan-cache-misses2Manually: put the files in place
.github/skills/debug-plan-cache-misses/SKILL.md1Skills CLI (Vercel)
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a gemini-cli2Platform CLI
gemini skills install https://github.com/chalk-ai/chalk-ai-plugins --path plugins/chalk-plan-cache/skills/debug-plan-cache-missesManually: put the files in place
.devin/skills/debug-plan-cache-misses/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about debug-plan-cache-misses
How to install debug-plan-cache-misses in Claude Code?
Run npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a claude-code in your terminal. The configuration is stored at ~/.claude/skills/debug-plan-cache-misses/SKILL.md.
What does debug-plan-cache-misses do?
It automates searching Chalk engine logs to diagnose why queries miss cached plans. By inspecting computation log lines, it isolates which query fields change between requests.
What is the most frequent cause of cache misses in Chalk?
Inconsistent input payloads in given_features trigger most misses. When an upstream caller alternates between sending raw or derived inputs, Chalk treats each shape as a distinct query needing a separate plan.
