Skip to main content
skill KR Kiro CX Codex

lean-ctx-review — Claude Code skill: audit ctx_* MCP tools

lean-ctx-review — a skill for Claude Code, Cline, and Kiro that scans the session transcript for ctx_* tool failures and fallbacks to native tools. Confirmed problems get filed as GitHub issues against yvgude/lean-ctx.

Apache-2.0 ★ 3,956 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yvgude/lean-ctx --skill lean-ctx-review -a claude-code
Open on GitHub

What lean-ctx-review does

The skill parses the session transcript and builds a table of every ctx_* call — which ones carried is_error, which repeated identical arguments, which requested raw or fresh output, and how many native Read/Grep/Bash calls clustered after a failure.

Parsing requires python3: the skill runs python3 scripts/scan_session.py from its own directory and defaults to the latest file under ~/.claude/projects/*/. The script reports facts; deciding what counts as a problem is left to the developer. Before confirming any finding, the skill queries the yvgude/lean-ctx tracker via gh issue list — a closed issue defines intended behaviour, and a shipped fix that still fails is a regression.

Reproducible findings go to the tracker via gh issue create, with exact arguments, the version from lean-ctx --version, and the OS. If a finding does not reproduce, the skill reports that plainly rather than speculating. Zero findings is a normal and common outcome.

What it helps with

  • identify ctx_* calls that returned is_error
  • spot fallbacks to native Read/Grep/Bash following a tool failure
  • detect retries with identical arguments
  • distinguish a regression from a closed tracker issue
  • file a bug in yvgude/lean-ctx with a minimal reproduction

Example prompts for the agent

  • Review how ctx_* tools performed in this session
  • lean-ctx review — why did ctx_read fall back to native tools?
  • File an issue in yvgude/lean-ctx for the confirmed ctx_grep failure

How to install lean-ctx-review

1Skills CLI (Vercel)

npx skills add yvgude/lean-ctx --skill lean-ctx-review -a claude-code

2Manually: put the files in place

~/.claude/skills/lean-ctx-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/lean-ctx-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about lean-ctx-review

How do I install lean-ctx-review in Claude Code?

Run npx skills add yvgude/lean-ctx --skill lean-ctx-review -a claude-code; the skill will be available at ~/.claude/skills/lean-ctx-review/SKILL.md.

What does lean-ctx-review do?

It reads the session transcript, builds a table of all ctx_* calls with their error flags and fallback patterns, then files confirmed bugs in yvgude/lean-ctx via GitHub CLI.

Does the skill require GitHub CLI?

Yes — tracker searches (gh issue list) and issue creation (gh issue create) both need gh installed and authenticated. Triage still runs without it, but filing issues will not work.

Source text

SKILL.md · Apache-2.0
---
name: lean-ctx-review
description: Review how the lean-ctx ctx_* MCP tools performed in the current session and file upstream issues for confirmed problems. Use when the user asks to review/audit lean-ctx tool performance, says "lean-ctx review", asks why ctx_* tools failed or fell back to native tools, or wants to report a lean-ctx bug.
---

# lean-ctx session review

Upstream repo: `yvgude/lean-ctx` (https://github.com/yvgude/lean-ctx).

Reads a Claude Code session transcript, so it applies to agents that write
`~/.claude/projects/*/*.jsonl`. Other harnesses need their own extractor; the
triage rules below are harness-independent.

## 1. Extract

Run from this skill's directory (needs `python3`):

```bash
python3 scripts/scan_session.py
```

Defaults to the newest transcript under `~/.claude/projects/*/` — the live
Claude Code session. Pass a path to review a different one. `-d N` dumps call
`#N` in full.

The script reports **facts, not verdicts**: every `ctx_*` call in order, which
results the harness flagged `is_error`, which calls repeated identical
arguments, which asked for `raw`/`fresh` output, and how many native
`Read`/`Grep`/`Bash` calls happened. It deliberately does not guess which of
those is a problem — that judgment is yours, below.

Transcripts run to megabytes, so read the table, not the raw JSONL.

## 2. Triage

**Start from `is_error`.** In practice every genuine tool failure carries it.
Then read the call list for the softer signals: identical retries, `raw`/`fresh`
re-reads, native calls clustered right after a `ctx_*` call, or a sequence that
only completed once `ctx_*` was abandoned.

### Before absolving anything, do these two things

Skipping them is how this review returns a false "nothing to report". Both cost
one command each.

**Search the tracker for the guard or tool you are about to excuse.** Do this
during triage, not at step 4. A closed issue defines intended behaviour: if a
shipped fix says a form is supported and you just watched it fail, that is a
regression and one of the most valuable things this review finds. It also stops
you re-filing a settled design decision.

```bash
gh issue list --repo yvgude/lean-ctx --search "<guard or tool keyword>" --state all
```

**Probe the stated rationale — never accept a message's self-description.**
An error explains itself, and that explanation can be wrong. Three checks, each
one command:

- *Does the sanctioned alternative achieve the same thing?* If the block is
  bypassable through a route the message itself recommends, it constrains syntax,
  not capability. Sometimes that is deliberate (structured input parses reliably
  where a shell string does not) — decide which, do not assume.
- *Does the stated reason match the observed rule?* Vary one axis at a time. A
  guard blaming payload size that actually keys on path, or blaming a pipe on a
  command that is piped, is misdiagnosing itself.
- *Does the message contradict itself?* A rejection that also states the rejected
  form is allowed is a finding on its own, whichever way the policy should go.

A wrong diagnostic is a real bug even when the block is correct: it sends the
next caller down a route that cannot work.

### Not a finding

- **Words inside returned content.** A file containing `http.StatusConflict`, a
  `git rebase` printing `CONFLICT (content):`, `gh` returning
  `"mergeable":"CONFLICTING"`, a test run printing `not found`. The tool
  returned exactly what was asked for. Judge the tool's own behaviour, never the
  payload's vocabulary.
- **Self-reference.** Any result that quotes a previous scan, this skill, or a
  transcript will echo every error word in it.
- **Guard blocks — only after they survive the probe above.** Inline env
  overrides (`GIT_EDITOR=`), shell redirects (`>`/`>>`), non-allowlisted
  commands, paths outside the project root. "It offered an alternative and the
  alternative worked" is *not* enough to clear one: that is true of a guard whose
  reason is wrong, whose rule is different from its description, or that
  contradicts itself. Clear it only once the stated rationale holds up.
- **Malformed tool input.** `InputValidationError` on `__unparsedToolInput` is
  the caller's own JSON serialization — commonly a raw tab or newline inside a
  string — rejected before lean-ctx ever ran.
- **My own wrong arguments**, a genuinely missing file, a failing build.

### Confirmable

The tool did something wrong or unhelpful *given correct input*:

- wrong, lossy, or truncated output where the mode promises otherwise
- content injected into output documented as verbatim, or anything that breaks a
  documented output format (e.g. corrupting batch-read separators)
- a crash, hang, or schema mismatch against the documented parameters
- a documented mode behaving differently than described
- a retry that only succeeded after dropping to native tools
- **a wrong or self-contradicting diagnostic**, even where the block itself is
  right — naming the wrong cause sends the next caller down a route that cannot
  work, and costs more than the block did
- **a regression against a closed issue**: a shipped fix says the form is
  supported, and it is not

## 3. Reproduce

**No minimal repro, no issue.** Re-run the exact tool and arguments. If it
passes, try to isolate the trigger; if you cannot, do not file — report the
observation to the user instead, saying plainly that it did not reproduce and
what you tried. Guessing at internals is worse than silence.

`lean-ctx --version` for the version line.

Zero confirmed findings is a valid and common result. Say so and file nothing.

## 4. File

Only for confirmed findings, one issue per distinct problem. You searched the
tracker during triage; widen it here if the finding shifted:

```bash
gh issue list --repo yvgude/lean-ctx --search "<keywords>" --state all
```

Skip if already reported — and read the close text before re-filing, since a
closed issue may have already conceded the point you are about to raise. When a
finding contradicts a closed fix, cite it and frame the issue as the gap in that
fix. Otherwise:

```bash
gh issue create --repo yvgude/lean-ctx --title "..." --body-file <file>
```

Body: what happened, expected, minimal repro (exact tool + args), version, OS.
No speculation about internals. End every issue body with the Claude Code
attribution footer. Report the issue `html_url` back to the user.

© yvgude · Apache-2.0 · yvgude/lean-ctx

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set4

Project sponsors

Companies that keep this analytics open