Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
136 commits
Select commit Hold shift + click to select a range
a278b26
Understanding check: the CLI (status, validate, grade, ci) and the sk…
tomeyer97 Nov 16, 2026
4374207
Understanding check skill: one point per question, a why when there i…
tomeyer97 Nov 16, 2026
95da915
Understanding check in VS Code: Check my understanding, questions as …
tomeyer97 Nov 16, 2026
1d4e2e6
Understanding check: README with CI recipes, changelog, design doc as…
tomeyer97 Nov 16, 2026
f40a654
Understanding check: make the skill's script executable when an insta…
tomeyer97 Nov 16, 2026
0d01aa9
Finding journeys: a Journeys view and a searchable home in the panel,…
tomeyer97 Nov 16, 2026
ab31ce7
Understanding check grader: short replies, claims checked against the…
tomeyer97 Nov 16, 2026
745790b
Understanding check CLI: lines follow the code, MR links to the diff,…
tomeyer97 Nov 16, 2026
d4cab8d
Understanding check: one rule and one state for every surface; restat…
tomeyer97 Nov 16, 2026
a426832
Understanding check: one rule and one state for every surface; restat…
tomeyer97 Nov 16, 2026
f3f3619
Understanding check CI: no size limit, code lines only, a comment tha…
tomeyer97 Nov 16, 2026
e80b5a8
Understanding check: drift is the branch's own change; "answered by" …
tomeyer97 Nov 16, 2026
43e48a4
Understanding check docs: no size limit, code lines, exempt globs, th…
tomeyer97 Nov 16, 2026
d7d0114
Understanding check comment: no "Right:" in front of the grader's not…
tomeyer97 Nov 16, 2026
59a3d99
Understanding check in VS Code: a Check view in the sidebar, one stat…
tomeyer97 Nov 16, 2026
f3e75d0
Understanding check: only the final answer stays in the file; `init` …
tomeyer97 Nov 16, 2026
f493d90
Merge fix/understanding-ci: CI messages, the MR comment, code lines, …
tomeyer97 Nov 16, 2026
ff4ffb5
Understanding check: accept optional code links on questions and atte…
tomeyer97 Nov 16, 2026
298d1b8
Merge branch 'fix/understanding-ci' into feat/understanding-check
tomeyer97 Nov 16, 2026
806a64e
Merge fix/understanding-ci (final); the first check sets up the repos…
tomeyer97 Nov 16, 2026
d7c42cc
Understanding check comment: @mentions in answers, notes, topics, con…
tomeyer97 Nov 16, 2026
e9a6fe4
Understanding check: code links instead of line numbers, as on journe…
tomeyer97 Nov 16, 2026
4423f65
Merge feat/understanding-check into fix/understanding-ci
tomeyer97 Nov 16, 2026
b07e2e8
Understanding check: opening a question moves the keyboard into its t…
tomeyer97 Nov 16, 2026
9d70a34
Journeys: steps are found again when their files change on disk or th…
tomeyer97 Nov 16, 2026
a2b7f76
Understanding check: threads follow the check file on disk; an answer…
tomeyer97 Nov 16, 2026
93d0972
Merge branch 'fix/understanding-ci' into feat/understanding-check
tomeyer97 Nov 16, 2026
b029fc7
Understanding check CI: flagged concerns as resolvable threads on the…
tomeyer97 Nov 16, 2026
a46e03c
Understanding check grader: a value written but never read is never p…
tomeyer97 Nov 16, 2026
36de732
Understanding check CI: advisory mode
tomeyer97 Nov 16, 2026
6cc164c
Check view harness: the new view (tones, notice, someone else's check…
tomeyer97 Nov 16, 2026
1aa0c85
Merge branch 'fix/understanding-ci' into feat/understanding-check
tomeyer97 Nov 16, 2026
ef82f3b
Journey lenses: one per function; questions written in the background…
tomeyer97 Nov 16, 2026
7489b74
Journey list: checks leave it; search falls back to any word; Continu…
tomeyer97 Nov 16, 2026
d1b73b1
Journeys panel: short title as heading; list keyboard, stale preview,…
tomeyer97 Nov 16, 2026
154bc45
Merge fix/journey-list: ranked In this file, actionable stale steps, …
tomeyer97 Nov 16, 2026
016f50e
Check threads: a code link only lights its lines; the keyboard stays …
tomeyer97 Nov 16, 2026
5800733
Understanding check: a tour of the change, written after the question…
tomeyer97 Nov 16, 2026
b6fd013
Opening a question waits for its editor to settle before moving the k…
tomeyer97 Nov 16, 2026
60e35ca
Notes: one temp file per write, so two saves of a note at once can't …
tomeyer97 Nov 16, 2026
c8d5c9f
The check's own files: no workspace settings, never counted, and Comm…
tomeyer97 Nov 16, 2026
5f15c90
Uncommitted work no longer gates the start: the Check view names ever…
tomeyer97 Nov 16, 2026
4baa20c
After a grade the editor stays on the question; 'Next question ›' und…
tomeyer97 Nov 16, 2026
12060bc
Opening background questions updates the status bar at once
tomeyer97 Nov 16, 2026
aa6b37d
Check questions are listed once: in the Check view, no longer also in…
tomeyer97 Nov 16, 2026
550d487
A question the writer thinks may be a bug says nothing about it until…
tomeyer97 Nov 16, 2026
d47d6aa
Add TODO and Flag for reviewer are independent; the TODO is one short…
tomeyer97 Nov 16, 2026
1662629
'Fix now' becomes 'Suggest a fix': one sentence and a suggestion bloc…
tomeyer97 Nov 16, 2026
6003caf
Understanding check: walk the tour of the change, the questions as st…
tomeyer97 Nov 16, 2026
ec8e7b9
Opening a question waits until VS Code has asked for the file's comme…
tomeyer97 Nov 16, 2026
ec1d074
Notes made from a check (Suggest a fix, Ask Claude on a question) bel…
tomeyer97 Nov 16, 2026
d315411
Check files collapse in GitLab merge request diffs too: gitlab-genera…
tomeyer97 Nov 16, 2026
e2c1a01
The merge request comment says 'about 5 min', and quoted text can't t…
tomeyer97 Nov 16, 2026
4040873
Grader: a pass answers what the answer said; a pass that corrects som…
tomeyer97 Nov 16, 2026
fd9b0f4
A flagged concern appears once where it can be acted on: its thread o…
tomeyer97 Nov 16, 2026
96bc7b2
An answer box in the Check view, with the keyboard in it
tomeyer97 Nov 16, 2026
bd8f1d1
Answer box: confirm the keyboard arrived, try once more if not; never…
tomeyer97 Nov 16, 2026
20f3e48
Merge fix/check-r2 and feat/check-journey: round-2 fixes, the answer …
tomeyer97 Nov 16, 2026
6baaf6e
Questions are written for the branch and commit they were started on,…
tomeyer97 Nov 16, 2026
7eedab0
Answers, notes and concerns are literal text in the merge request com…
tomeyer97 Nov 16, 2026
be773d8
Setup files are never written by themselves: the Check view offers th…
tomeyer97 Nov 16, 2026
6af00e3
A change that only removes code gets a check: questions at the remova…
tomeyer97 Nov 16, 2026
c1a4514
When writing the questions fails, the Check view says why in plain wo…
tomeyer97 Nov 16, 2026
9759d67
Stacked branches: the change starts after the parent branch's committ…
tomeyer97 Nov 16, 2026
478adc6
Journey lenses: one per function; In this file ranks by the whole fun…
tomeyer97 Nov 16, 2026
f54f72f
Journeys: Refresh runs the journey writer; the panel keeps the code ~…
tomeyer97 Nov 16, 2026
7f6b6f5
Renames are moves: no new lines; a move-only change gets one question…
tomeyer97 Nov 16, 2026
b53af59
A renamed branch keeps its check: the work it covers counts as checked
tomeyer97 Nov 16, 2026
a4b1cd6
On the default branch the Check view says one line: 'main: no check h…
tomeyer97 Nov 16, 2026
0a769ee
Question writer: no 'uncommitted lines' note when its branch is not c…
tomeyer97 Nov 16, 2026
6f24534
The merge request comment is short: status, one link per thread, then…
tomeyer97 Nov 16, 2026
40b3b04
CI wording: advisory says so first and never shows skip steps; a self…
tomeyer97 Nov 16, 2026
9f7a1e0
The honest size up front: '3 questions, ~2 min' before the start, '~1…
tomeyer97 Nov 16, 2026
32360ad
Grader: told the check's other open questions, it never states a fact…
tomeyer97 Nov 16, 2026
bd796db
A grade that says the change breaks something always raises a concern…
tomeyer97 Nov 16, 2026
bfd720a
At most one 'what does it return for <numbers>' question, and it says…
tomeyer97 Nov 16, 2026
bc6dc3e
A docs-only change gets one question about what a reader sees differe…
tomeyer97 Nov 16, 2026
0e77302
'Also read' names the file and links its lines, never 'worker.js:84-96'
tomeyer97 Nov 16, 2026
79965a9
Backticks in a question render as code in the Check view and the comm…
tomeyer97 Nov 16, 2026
f6dc73e
Opening a question with a long range shows its thread, not the top of…
tomeyer97 Nov 16, 2026
06ab23c
Integration test reads the code editor, not whichever editor has the …
tomeyer97 Nov 16, 2026
a1f3f77
The status item's accessible name is words ('Understanding check: 0 o…
tomeyer97 Nov 16, 2026
2f856e9
Done always offers Commit & push, also from the status item, and says…
tomeyer97 Nov 16, 2026
dfcbbaa
A merge conflict in the check file is said as one, with Keep both ans…
tomeyer97 Nov 16, 2026
bf88b91
A check that is in a git stash says so (git stash pop) instead of off…
tomeyer97 Nov 16, 2026
f171d43
CI recipe: the understanding job runs on its own, so a failing test n…
tomeyer97 Nov 16, 2026
e98c316
Grader: a pass is one sentence, two at most (it had drifted past 25 w…
tomeyer97 Nov 16, 2026
a748839
Answer box: keep trying to take the keyboard for a second while its q…
tomeyer97 Nov 16, 2026
88fbec1
Merge branch 'fix/check-r2b' into feat/understanding-check
tomeyer97 Nov 16, 2026
ee2461f
CI recipe: the job goes in the last stage with needs: [], so a missin…
tomeyer97 Nov 16, 2026
43d1b5e
Grader: a concern only for a defect in the code, saying what breaks a…
tomeyer97 Nov 16, 2026
a4475b0
MR comment and CI log: "about 2 min", never "~2 min" (GitLab turns ~2…
tomeyer97 Nov 16, 2026
f7275ba
Check view: the keyboard stays in the answer box through a grade; sho…
tomeyer97 Nov 16, 2026
a9c45c0
MR comment and threads: one problem, one line; the reviewer's decisio…
tomeyer97 Nov 16, 2026
9431e7d
CI judges a merge request by its target branch's settings; a settings…
tomeyer97 Nov 16, 2026
effd632
Check threads: a superseded answer goes with its retry grade; titles …
tomeyer97 Nov 16, 2026
881b580
CLI help and status: docs that exist, the same way without VS Code as…
tomeyer97 Nov 16, 2026
c61f60a
Journey panel: never leave the code under 80 visible columns
tomeyer97 Nov 16, 2026
95d9f3e
Step card code links only light their lines; typing next stays out of…
tomeyer97 Nov 16, 2026
269ec18
Steps follow the reader's own edits instead of going out of date
tomeyer97 Nov 16, 2026
db705fa
Journey panel after a reload: never closed while VS Code restores it
tomeyer97 Nov 16, 2026
2d677dd
Stacked branches: the parent's commits after its check are not the ch…
tomeyer97 Nov 16, 2026
da3d12f
Journey panel: its doc comment says 80 columns
tomeyer97 Nov 16, 2026
8c8b83d
Ask on a step: "1 asked ›", a short answer first, one hint line
tomeyer97 Nov 16, 2026
09c0113
Journey lenses step aside only in the function of an open check question
tomeyer97 Nov 16, 2026
1102329
Journey search: stop-words out, stems, "No journey about …", results …
tomeyer97 Nov 16, 2026
b985f18
Skill: riskiest question first; the tour's length and focus follow th…
tomeyer97 Nov 16, 2026
8a20764
Suggest a fix: one short sentence and a fix that fits the problem (no…
tomeyer97 Nov 16, 2026
36e96c2
Check suite at 1280 px: the secondary side bar closed, as in the repo…
tomeyer97 Nov 16, 2026
9a784f4
Docs: journeys round 3 (room for the code, code links, own edits, sea…
tomeyer97 Nov 16, 2026
a8f1d7e
Check view: Commit & push in every Done state; a tour survives a bran…
tomeyer97 Nov 16, 2026
6168631
Own edits: told from a reload by the document being dirty once typing…
tomeyer97 Nov 16, 2026
d1bd2d2
Dismiss: "I fixed it" when the concern's code changed or its fix was …
tomeyer97 Nov 16, 2026
630dc30
Merge branch 'fix/check-r3' into feat/understanding-check
tomeyer97 Nov 16, 2026
f6ec2a8
Merge branch 'fix/journey-r3' into feat/understanding-check
tomeyer97 Nov 16, 2026
0734809
Code links from a Claude Code chat light the lines they open, with Ba…
tomeyer97 Nov 17, 2026
2ce664e
journey.py: --steps A-B sets the step count check wants, for a short …
tomeyer97 Nov 17, 2026
8b19efb
Understanding check: size rules for docs, removals and small changes;…
tomeyer97 Nov 17, 2026
d036a3b
Check view: the first check commit folds check files in diffs; no sep…
tomeyer97 Nov 17, 2026
68310fe
Docs: size rules for docs, removals and small changes; the first chec…
tomeyer97 Nov 17, 2026
61086f1
questions.mjs cli: write a long output out before exiting
tomeyer97 Nov 17, 2026
2cdc8d6
tour-finish: check the tour's count itself and ignore journey.py's 6-…
tomeyer97 Nov 17, 2026
2078687
Merge branch 'feat/understanding-check' into feat/claude-links
tomeyer97 Nov 17, 2026
a40c207
Understanding check: read git on a worker thread, and only when somet…
tomeyer97 Nov 17, 2026
6135ce8
Find the claude CLI without blocking the extension host
tomeyer97 Nov 17, 2026
57a082b
Send context keys and decorations to the window only when they change
tomeyer97 Nov 17, 2026
7e321fa
Fewer waits on the window per action: code links, Back, steps, chat l…
tomeyer97 Nov 17, 2026
309563e
Check suite: refresh gate, coalescing, a refresh that never blocks, o…
tomeyer97 Nov 17, 2026
8e7334b
Changelog: faster over Remote-SSH and on big repositories
tomeyer97 Nov 17, 2026
1ce7fad
Chat links: detected on VS Code versions that report the selection as…
tomeyer97 Nov 17, 2026
f605b0e
Read and write the workspace's files with Node's fs, not through the …
tomeyer97 Nov 17, 2026
ef714f8
Journey steps: a quick Next never mixes steps; Back goes only where i…
tomeyer97 Nov 17, 2026
d321594
Notes and answers: once per Ctrl+Enter, shown at once
tomeyer97 Nov 17, 2026
01bd187
Code links in a step card break lines with <wbr>, not a zero-width space
tomeyer97 Nov 17, 2026
4eaa7f4
Tests: a quick Next ×3 ends on its step; no workspace.fs outside wfs.ts
tomeyer97 Nov 17, 2026
9fdc48e
Changelog: files read where they are, quick Next, double Ctrl+Enter, …
tomeyer97 Nov 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,10 @@ jobs:
- run: npm run build
- name: Unit tests
run: npm test
- name: Skill script
run: python3 skills/code-journey/scripts/journey.py help all > /dev/null
- name: Skill scripts
run: |
python3 skills/code-journey/scripts/journey.py help all > /dev/null
node skills/understanding-check/scripts/questions.mjs > /dev/null
- name: Tests in a real VS Code
run: npm run test:integration
- name: Package
Expand Down Expand Up @@ -58,3 +60,7 @@ jobs:
run: npm run test:panel
- name: Every beat of the sample animations, three widths
run: npm run test:scenes
- name: Understanding check panel, three widths
run: npm run test:checkpanel
- name: Journeys list in the panel, three widths
run: npm run test:journeylist
34 changes: 34 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,39 @@
# Changelog

## Unreleased

- **Understanding check: a tour of the change.** Right after the questions, Claude writes a short journey of the change
(6-10 steps through the changed code and the code it depends on), each question placed after the step that shows
its answer. Check my understanding (or **Walk the tour** in the Check view) walks it in the journey panel: the
questions are rows of the storyline, Next stops at each open one and opens its thread, a pass walks on. Rows of the
Check view say their step and go there. The tour is stored in the check file (`journey`); a top-up adds steps for
the new part. The grader may point at a step; the merge request comment gets one line about the tour. A question,
and the tour's last step, may say "See also" a journey of the repository that walks the same code.
- **Faster over Remote-SSH and on big repositories.** The understanding check reads git on a worker thread: the
extension host (shared with every other extension, and over Remote-SSH with the editor) never waits for git. It
reads again only when something it shows can have changed: another `git status` (the Git view, a terminal, an agent)
no longer makes it refresh, and a burst of triggers is one refresh. A code link, Back, the next or previous step, a
link from a chat and opening a question each wait for at most one call into the window (fixed waits and repeated
context keys, decorations and lens refreshes are gone), so they slow down less with the network's latency.
- **Remote-SSH: files are read where they are.** Notes, journeys and step files are read and written with Node's fs
instead of through the window (a round trip each): opening a folder with many notes and journeys no longer takes a
round trip per file. A quick Next, Next, Next ends on the last step asked for, with its file and card. A reply, a
note or an answer sent twice with a quick double Ctrl+Enter is saved once, and shows at once ("Checking…" for an
answer). Links from a Claude Code chat are recognised on newer VS Code versions too. A code link's Back names its
step and goes away once the walk moves on. Copied link text has no hidden zero-width spaces.

## 0.24.0

- **Understanding check:** **Check my understanding** has Claude Code ask a few questions about your branch's change,
each a thread on its lines. Answer in the thread; Claude grades it and replies with a short confirmation, a hint, or
(after a second miss) the explanation, naming the code as clickable links. The **Check** view in the sidebar lists
the questions; the status bar says where the check stands; **Commit & push** finishes it. Answers are saved in
`understanding/<branch>.json` for a merge request check that needs no model (`cli/understanding.mjs ci`, GitLab and
GitHub recipes in the README). The bundled `understanding-check` skill writes the questions.
- **Finding journeys:** journeys have their own **Journeys** view: In this file, Continue, Checks, then All by area,
with search and sort. The panel's Journeys list gets a search field, chips, the same sections and a preview of the
selected journey (its map, small, and its steps); a click selects, Enter or **Walk** starts it.

## 0.23.0

First release on the Visual Studio Marketplace.
Expand Down
129 changes: 125 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
# Code Notes

Two things for understanding code you did not write, in VS Code:
Three things for understanding code you did not write, in VS Code:

- **Notes**: leave a question or a remark on any lines of code. Your coding agent answers in the thread; replies show
up as unread.
- **Code Journeys**: an answer to "how does X work?" as a small map of the parts involved and a storyline of steps
through the real code. You walk it step by step; a step can play as a short animation.
- **Understanding check**: before you merge a change (yours, or your agent's), answer a few short questions about
it next to the code. A merge request check makes sure it was done.

![A journey: the storyline, a step's animation and the code it is about](docs/images/journey.png)

Expand All @@ -25,15 +27,23 @@ Two things for understanding code you did not write, in VS Code:
## Code Journeys

A journey is one JSON file in your repository (`journeys/` by default), reviewed in pull requests like code. Open one
from the Code Notes sidebar, or run **Ask a Question About the Code…** and have Claude Code write one.
from the **Journeys** view in the Code Notes sidebar, or run **Ask a Question About the Code…** and have Claude Code
write one.

- **Finding one:** the Journeys view groups them: **In this file** (journeys with a step in the file you are in),
**Continue**, **Checks**, then **All** by area (the top folder most steps visit). Search and sort are in its title
bar. The panel's **‹ Journeys** list has the same groups, a search field (it also searches step titles and file
paths), chips by kind and area, and a preview of the selected journey; Enter walks it.

- **The panel** shows the storyline (the numbered steps) beside a map of the systems, modules and functions involved.
It never leaves the code under 80 columns: in a narrower window the walk uses the step card alone (Ctrl+' V: the map).
- **In the editor**, a card above the step's lines says what happens there, with **Next**, **Ask** and **More**.
- **Code links:** tinted phrases in the card jump to the exact lines that do that part.
- **Value hints:** faint text above a line shows what a variable holds in an example run.
- **Show animation** plays the step beat by beat in place of the map. Each beat shows one thing happening, highlights
the line of code that does it, and shows that line with a few around it under the caption.
- **Steps follow the code** like notes do: moved code is followed, changed code is flagged.
- **Steps follow the code** like notes do: moved code is followed, changed code is flagged. Your own edits to a
step's lines (typing, an applied fix) are followed, not flagged.

![What a step's animation can draw](docs/images/objects.png)

Expand All @@ -48,6 +58,115 @@ a journey, so every step points at real lines. **Ask a Question About the Code
written in your repository, copy [skills/code-journey](skills/code-journey) to `.claude/skills/code-journey` there;
the repository's copy wins.

## Understanding check

**Code Notes: Check my understanding** (or **Understanding: start** in the status bar) has Claude Code read your
branch's change and ask a few questions about it (1 for a small change, documentation or a removal, up to 5 for a big one): how a part behaves, why
it is built this way, how it fails. The first question opens as a thread on its lines; the list is the **Check** view
in the Code Notes sidebar. Answer in 1-3 sentences and press Ctrl+Enter: Claude checks the answer against the code and
replies in the thread, naming the code it means as links you can click. A miss gets a hint and a second try; a second
miss gets the explanation, which you may say back in one sentence (a right one counts as passed). Ctrl+' D goes to
the next open question. You can also answer in the Check view: the selected question has a box there (Ctrl+Enter
sends, Esc goes back to the code).

Right after the questions, Claude writes a **tour of the change**: a short journey through the changed code and the code
it depends on, in the order things happen, with each question placed after the step that shows its answer (2-3 steps
for a few lines, documentation or a removal). The questions
can be answered while it is written (about 3 minutes). **Walk the tour** in the Check view (or Check my understanding)
opens it in the journey panel: Next walks the steps and stops at each open question, with its thread on the code. The
Check view's rows say which step a question belongs to and go straight there. Walking it is optional.

Questions and answers are saved in `understanding/<branch>.json`. The rule, shown the same way everywhere: answer all
questions, and enough must pass (60 % by default). Then **Commit & push** in the Check view commits the file and
pushes; the first check in a repository also adds the `.gitattributes` line that folds check files in GitLab and GitHub
diffs (the button's line says so). When the grader finds a problem in the code itself, the thread offers **Suggest a fix**, **Add TODO** and **Flag for
reviewer** (flagged ones go on the merge request). When you push a branch that has no check yet, its questions are written in the background
(the status bar says "3 questions ready"; setting `codeNotes.understanding.background`).

Everything runs on your machine. The merge request check only verifies the file: it belongs to this change, every
question is done, the recorded verdicts meet the threshold. It calls no model and needs no key. Once the check is done
it posts the questions and answers on the merge request for the reviewer (while it is in progress, only "2 of 4 done"). It is easy to cheat by editing the file; it is there to
make you look, not to police.

- **Every change with code** gets a check; only code lines count (not comments or blank lines). Files that should
never count go in `exempt` (none by default).
- **The change grew** by more than 40 code lines since the questions: run the command again; it adds 1-2 questions
about the new part only. Merging the target branch in doesn't count.
- **Skip it:** label the merge request `skip-understanding`. Any approval by someone other than the author waives the
check (re-run the job after the approval; on GitHub the review re-runs it).
- **Settings** for a repository (a merge request is judged by its target branch's): `understanding/config.json`, e.g.
`{ "exempt": ["docs/**", "*.md", "package-lock.json"], "passRatio": 0.6, "maxDrift": 40, "skipLabel": "skip-understanding", "mrComment": true }`.

Only the final answer to each question is kept in the file; earlier tries keep their verdict, not their text.

**Without VS Code**, teammates use [Claude Code](https://claude.com/claude-code): `/understanding-check` asks the
questions one at a time in the chat, grades each answer with the same rules, records it in the same file and commits
it. Run `node cli/understanding.mjs init` once and commit what it prints: it puts the skill in
`.claude/skills/understanding-check/`, adds `understanding/*.json gitlab-generated linguist-generated` to
`.gitattributes` (collapsed in GitLab and GitHub diffs; `understanding/config.json` stays visible) and `understanding/`
to `.ignore` (skipped by ripgrep and VS Code's search), never twice.

The command line, [cli/understanding.mjs](cli/understanding.mjs) (Node 18+, no dependencies): `status`, `validate`,
`grade` (local; Claude Code or `ANTHROPIC_API_KEY`), `next`, `flag`, `commit`, `init` and `ci`. Design: [docs/understanding-check.md](docs/understanding-check.md).

### In CI

GitLab (`.gitlab-ci.yml`). `GITLAB_TOKEN`: a project access token with `api` scope (CI/CD variable, masked), used to
read labels and approvals and to write the comment. Without it the check still runs, without the comment and the skip
label.

```yaml
understanding:
image: node:22
stage: .post # the last stage, so a missing check never skips lint or tests
needs: [] # but it starts at once: a failing test never skips it either
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
variables:
GIT_DEPTH: "0"
allow_failure:
exit_codes: [3] # advisory mode: "passed with warnings", never blocks
script:
- curl -fsSL https://raw.githubusercontent.com/tomeyer97/code-notes/v0.24.0/cli/understanding.mjs -o /tmp/understanding.mjs
- node /tmp/understanding.mjs ci
```

GitHub Actions (`.github/workflows/understanding.yml`); an approving review re-runs it by itself:

```yaml
name: Understanding check
on:
pull_request:
types: [opened, synchronize, reopened, labeled, unlabeled]
pull_request_review:
types: [submitted]
permissions:
contents: read
pull-requests: write
jobs:
understanding:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 22
- run: |
curl -fsSL https://raw.githubusercontent.com/tomeyer97/code-notes/v0.24.0/cli/understanding.mjs -o /tmp/understanding.mjs
node /tmp/understanding.mjs ci
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

**Advisory first.** Start with `"mode": "advisory"` in `understanding/config.json` for a month, then switch to
`"required"` (the default; `UNDERSTANDING_MODE` overrides the file). In advisory mode the job and the merge request
comment work as usual, but a failure doesn't block: on GitLab the job exits 3 and shows "passed with warnings" (the
`allow_failure` above); on GitHub, where a step can't allow one exit code, it adds a warning annotation and passes.

To review the script once and keep it, commit a copy (e.g. `tools/understanding.mjs`) and run that instead.

## Keys

One chord: **Ctrl+'** (or **Ctrl+<** on ISO keyboards), then a letter.
Expand All @@ -59,11 +178,13 @@ One chord: **Ctrl+'** (or **Ctrl+<** on ISO keyboards), then a letter.
| **D** / **A** | Next / previous: the journey step while walking one, else the unread note |
| **V** | The journey map |
| **P** | The current step's animation, on or off |
| **J** | Search journeys |

## Requirements

- VS Code 1.100 or newer.
- Optional: the [Claude Code](https://claude.com/claude-code) CLI, for **Ask Claude** and for writing journeys. Claude
- Optional: the [Claude Code](https://claude.com/claude-code) CLI, for **Ask Claude**, writing journeys and the
understanding check. Claude
never runs in an untrusted workspace, and it cannot edit your files: it answers in notes and writes journey files.
- Optional: Python 3, used by the journey skill's script.

Expand Down
Loading
Loading