# debug-plan-cache-misses

Finds Chalk plan cache misses by analyzing engine logs and diffing query payloads. Useful when repeated plan generation increases response latency.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 836 installs
- Author: chalk-ai
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/chalk-ai/chalk-ai-plugins/tree/HEAD/plugins/chalk-plan-cache/skills/debug-plan-cache-misses/SKILL.md
- Updated: 2026-09-15
- HTML: https://affpapa.org/en/nevibecode/skills/debug-plan-cache-misses

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/debug-plan-cache-misses/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/debug-plan-cache-misses/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/debug-plan-cache-misses/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/debug-plan-cache-misses/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install chalk-ai/chalk-ai-plugins debug-plan-cache-misses
```

2. **Manually: put the files in place**
- File: `.github/skills/debug-plan-cache-misses/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/chalk-ai/chalk-ai-plugins --path plugins/chalk-plan-cache/skills/debug-plan-cache-misses
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/debug-plan-cache-misses/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add chalk-ai/chalk-ai-plugins --skill debug-plan-cache-misses -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/chalk-ai/chalk-ai-plugins/tree/HEAD/plugins/chalk-plan-cache/skills/debug-plan-cache-misses/SKILL.md

## When to use it
- 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
- 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

## Similar
- [mcp-builder](https://affpapa.org/en/nevibecode/skills/mcp-builder.md) — skill · 130949 installs
- [claude-api](https://affpapa.org/en/nevibecode/skills/claude-api.md) — skill · 74198 installs
- [lark-im](https://affpapa.org/en/nevibecode/skills/lark-im.md) — skill · 472900 installs
- [lark-event](https://affpapa.org/en/nevibecode/skills/lark-event.md) — skill · 466800 installs
- [caveman-discover](https://affpapa.org/en/nevibecode/skills/caveman-discover.md) — skill · 104400 installs
- [migration](https://affpapa.org/en/nevibecode/skills/migration.md) — skill · 103900 installs

From the same set: [chalk-ai/chalk-ai-plugins](https://affpapa.org/en/nevibecode/by/chalk-ai/chalk-ai-plugins.md) — 4 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md