coach: review flow text and skill pointers

DOCS-review.md is the /leetcode review flow Claude follows; SKILL.md routes
a first token review to it and points at the skeleton rules, staying at
250 lines. The md-naming gate takes DOCS-* names only, so the text is not
REVIEW.md. test_review_docs.py holds the quoted commands to the CLI.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzxdWXLvi9aq4MxL4XHKJ4
This commit is contained in:
Krzysztof Rudnicki 2026-11-21 21:59:14 +01:00
parent 299e3b6fc2
commit b5b85433fc
3 changed files with 194 additions and 6 deletions

View File

@ -0,0 +1,105 @@
# /leetcode review [slug]: name the one cause of a slow solve
Claude Code only; `leetcode --local` does not run this.
A review looks at a solve the guard flagged: LeetCode accepted it, but kuhy
spent more than 20 active minutes on it although the unit's theory was already
taught. You find the one cause, log it, and that starts the cold re-test clock
(+3 and +10 days). You do not coach the problem again.
**Never print a solution**, a corrected line or a rewrite of kuhy's code.
`reveal` does not apply in a review.
## The flow
1. **Pick the solve.** Run:
```bash
python3 -m leetcode_coach.review_cli review-list
```
- No slug in the arguments: show kuhy the lines as printed and ask which
solve he wants to review.
- A slug in the arguments: go on only if one line starts with that slug.
- `nothing to review`, or his slug is not on the list: say so in one line
and stop. Only flagged solves can be reviewed.
- `could not check: ...` (exit 2): the guard gave no report. Show the line
and stop. Never report it as "nothing to review".
2. **Show the evidence.** Quote the solve's line and say what it means:
`active` is the time the problem page was on screen, `span` runs from the
day's first heartbeat to Accepted, `failed` counts the failed submissions
by verdict, `first submit` is the active time before the first submission,
`tabs` splits the active time by page tab, `theory` is the unit's tutor
state at the solve.
3. **Ask for his accepted code.** kuhy pastes it. Do not fetch it and do not
rewrite it.
4. **Ask at most 3 questions**, one per message, each about something the
evidence or the code shows ("12 minutes passed before your first submit:
what did you do in them?"). Stop asking once the cause is clear.
5. **Name exactly ONE cause** in one or two sentences that cite the evidence.
If two fit, pick the one that cost more minutes. kuhy may correct you: his
word decides.
| cause id | what happened |
|---|---|
| `statement` | He misread the statement or missed a part of it. |
| `missing-idea` | He did not have the idea the solution needs. Name the unit that teaches it (`--module`). |
| `idea-to-code` | He had the idea early and could not turn it into code. |
| `debugging` | The code was nearly right; the time went into finding a bug (debugging process). |
| `interruption` | He was away or distracted; the minutes are not work on the problem. |
Then close the review:
```bash
python3 -m leetcode_coach.review_cli review-finish <slug> --cause <cause> [--module <unit>]
```
`--module <unit>` goes with `missing-idea` and with no other cause. The
unit is a curriculum unit id: `scans`, `hashing`, `math`, `bits`,
`sorting-greedy`, `pointers-window`, `prefix-sums`, `stack-queue`,
`binary-search`, `lists-recursion`, `trees`, `heap-dp`, `sql`, `js-pandas`.
Read its output; it says exactly what it wrote:
- exit 0, `review logged: ...` and `ledger row: written`: the solve is no
longer flagged, and the re-test falls due 3 and 10 days from today
(`leetcode --retest <slug>`).
- `refused: ...` (exit 1): the slug is not flagged or an argument is
wrong. Nothing was written.
- `could not check: ...` (exit 2): nothing was written. Tell kuhy; do not
retry in a loop.
- `nothing written: no signed ledger row ...` (exit 3): the signing key is
unreadable. Nothing was written and the solve stays flagged. Tell kuhy.
- `ledger row written, review event NOT logged ...` (exit 3): run the same
command again.
6. **Card, for two causes only.** `missing-idea` and `idea-to-code` get ONE
property -> operation card for the toolbox entry his accepted code relies
on, built the post-mortem way (SKILL.md section 5b, steps 2 to 4):
```bash
python3 -m leetcode_coach.toolbox_cards cards "<entry>" \
| ~/.claude/skills/leetcode/make_cards.py -
```
`statement`, `debugging` and `interruption` get no card: the `review`
event is their whole record. No cause writes to the tutor or changes a
price.
7. **End.** Tell kuhy the cause and the two re-test dates, then stop.
**An abandoned review writes nothing.** If kuhy stops before a cause is named,
run no command: the solve stays flagged and he can review it later.
## Skeleton sheets
A skeleton sheet is one unit's code template with holes. `DOCS-skeletons.md`
has the rules; the command is:
```bash
python3 -m leetcode_coach.review_cli skeleton-open <slug> <unit>
```
- Open a sheet only when kuhy asks for one, and only after his first code
attempt. Never offer it. In a `leetcode <url>` session the client has logged
his first code; in a review his accepted code is the attempt, so the slug
must still be flagged: open the sheet before `review-finish`.
- Opening a sheet counts above H1: that solve gets no sign-off. The command
logs a `skeleton` event.
- stdout is the sheet file, byte for byte. Quote it to kuhy exactly as
printed: add no fence, no header and no note inside it (the stop gate lets
a sheet through only verbatim). The line `skeleton logged: ...` goes to
stderr.
- `refused: ...` (exit 1) or `could not check: ...` (exit 2): the sheet stays
shut and nothing was logged. Say why in one line.

View File

@ -9,7 +9,7 @@ description: >
on] AND whenever kuhy pastes a leetcode.com/problems/ URL without SOLVE:
(hook leetcode_url_userprompt.sh tells you to). Ends with a post-mortem: property -> operation
Anki cards generated from the toolbox, never the solution.
argument-hint: "<leetcode URL or slug> [what you're stuck on]"
argument-hint: "<leetcode URL or slug> [what you're stuck on] | review [slug]"
---
# /leetcode — coach, don't solve
@ -21,8 +21,8 @@ every "just do it" instinct for the rest of the session.
## 1. Fetch the problem
Take the first token of `$ARGUMENTS` (URL or slug); everything after it is
kuhy's description of what they are stuck on.
First token `review`: follow `DOCS-review.md` here, not sections 1 to 5. Else
it is the URL or slug, and the rest is what kuhy says they are stuck on.
```bash
python3 ~/.claude/skills/leetcode/fetch_problem.py "<first token>"
@ -243,7 +243,8 @@ enforces it from the next prompt on.
The right client is `leetcode <url>` (print mode: the Stop hook can still
withhold a reply; the TUI has already streamed it). `leetcode --local` runs
offline on Ollama; everything above `## Model and client` is its system
prompt. Clients, gates and the session log: `DOCS-clients.md` here.
offline on Ollama; its system prompt is everything above this section. Docs:
`DOCS-clients.md` (clients, gates, session log), `DOCS-how-to.md` (commands).
The commands and the method as the status app shows them: `DOCS-how-to.md`.
Skeleton sheets: only when kuhy asks, only after his first code, and one
counts above H1. Rules: `DOCS-skeletons.md`; the command: `DOCS-review.md`.

View File

@ -0,0 +1,82 @@
"""The review text, the skill's pointers to it, and what the package ships.
The text is what Claude follows in `/leetcode review`: a command it quotes
that the CLI does not dispatch, or a cause it names that the CLI refuses,
would only show up in a live session. These tests are that check.
"""
from __future__ import annotations
from pathlib import Path
import re
import tomllib
from leetcode_coach import local_prompt, review_cli
from leetcode_coach.tests._shared import STATEMENT
PACKAGE = Path(__file__).parents[1]
DOC = PACKAGE / "DOCS-review.md"
SKILL = PACKAGE / "SKILL.md"
PYPROJECT = PACKAGE.parent / "pyproject.toml"
PREFIX = "python3 -m leetcode_coach.review_cli "
SKILL_LINE_CAP = 250
def _doc() -> str:
return DOC.read_text(encoding="utf-8")
def test_the_text_quotes_the_three_commands_as_the_cli_takes_them() -> None:
text = _doc()
assert PREFIX + "review-list" in text
assert PREFIX + "review-finish <slug> --cause <cause> [--module <unit>]" in text
assert PREFIX + "skeleton-open <slug> <unit>" in text
quoted = set(re.findall(re.escape(PREFIX) + r"([a-z-]+)", text))
assert quoted == {"review-list", "review-finish", "skeleton-open"}
def test_the_text_names_every_cause_and_which_ones_make_a_card() -> None:
text = _doc()
for cause in review_cli.CAUSES:
assert f"`{cause}`" in text
assert "`missing-idea` and `idea-to-code`" in text
assert "leetcode_coach.toolbox_cards cards" in text
assert "make_cards.py -" in text
def test_the_text_keeps_the_rules_kuhy_set() -> None:
text = _doc()
for rule in (
"nothing to review",
"could not check",
"at most 3 questions",
"exactly ONE cause",
"Never print a solution",
"writes nothing",
"above H1",
"DOCS-skeletons.md",
):
assert rule in text, rule
def test_skill_md_points_at_the_review_and_skeleton_texts() -> None:
skill = SKILL.read_text(encoding="utf-8")
assert len(skill.splitlines()) <= SKILL_LINE_CAP
assert "DOCS-review.md" in skill
assert "DOCS-skeletons.md" in skill
assert "review [slug]" in skill.split("\n---\n", 1)[0]
def test_the_offline_prompt_never_hears_about_review() -> None:
prompt = local_prompt.system_prompt(SKILL.read_text(encoding="utf-8"), STATEMENT)
assert "DOCS-review.md" not in prompt
assert "skeleton" not in prompt.casefold()
def test_the_package_ships_the_texts_and_the_sheets() -> None:
config = tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))
shipped = config["tool"]["setuptools"]["package-data"]["leetcode_coach"]
assert "*.md" in shipped
assert "skeletons/*.md" in shipped
assert review_cli.SKELETON_DIR.name == "skeletons"
assert review_cli.SHEET_NAME == "DOCS-{unit}.md"