From b5b85433fcb575e96f0dca76021a7215f73d4057 Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Sat, 21 Nov 2026 21:59:14 +0100 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01WzxdWXLvi9aq4MxL4XHKJ4 --- leetcode_coach/leetcode_coach/DOCS-review.md | 105 ++++++++++++++++++ leetcode_coach/leetcode_coach/SKILL.md | 13 ++- .../leetcode_coach/tests/test_review_docs.py | 82 ++++++++++++++ 3 files changed, 194 insertions(+), 6 deletions(-) create mode 100644 leetcode_coach/leetcode_coach/DOCS-review.md create mode 100644 leetcode_coach/leetcode_coach/tests/test_review_docs.py diff --git a/leetcode_coach/leetcode_coach/DOCS-review.md b/leetcode_coach/leetcode_coach/DOCS-review.md new file mode 100644 index 0000000..c504814 --- /dev/null +++ b/leetcode_coach/leetcode_coach/DOCS-review.md @@ -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 --cause [--module ] + ``` + `--module ` 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 `). + - `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 "" \ + | ~/.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 +``` + +- Open a sheet only when kuhy asks for one, and only after his first code + attempt. Never offer it. In a `leetcode ` 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. diff --git a/leetcode_coach/leetcode_coach/SKILL.md b/leetcode_coach/leetcode_coach/SKILL.md index 2a1f601..63a0e98 100644 --- a/leetcode_coach/leetcode_coach/SKILL.md +++ b/leetcode_coach/leetcode_coach/SKILL.md @@ -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: " [what you're stuck on]" +argument-hint: " [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 "" @@ -243,7 +243,8 @@ enforces it from the next prompt on. The right client is `leetcode ` (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`. diff --git a/leetcode_coach/leetcode_coach/tests/test_review_docs.py b/leetcode_coach/leetcode_coach/tests/test_review_docs.py new file mode 100644 index 0000000..aec32d7 --- /dev/null +++ b/leetcode_coach/leetcode_coach/tests/test_review_docs.py @@ -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 --cause [--module ]" in text + assert PREFIX + "skeleton-open " 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"