Comprehende

Local review assistant for git diffs. Groups changes by review concern and shows them in a fixed UI. Diffs always come from git in the repo you run the CLI in — never from the model, never stored in the review document.

Install the skill

npx skills add matemolnar8/comprehende

From this checkout:

npx skills add ./ --skill comprehende

Why

Usage of AI agents to write code has given us previously unseen ability to write code. A lot of code.

Three concepts are important to understand:

• Cognitive offloading: when we use tools by handing off the how but keeping the why and the what - like a calculator adding numbers, we know why we need the sum, we tell it the two numbers to add together, it doesn't invent them
• Cognitive surrender: when we stop constructing an answer and adopt the answer from the tool instead, without having our own view to compare against - like letting the calculator add two numbers together, letting it make up the numbers and accepting the answer.
• Comprehension debt: the gap between the amount of code in the system and the amount of understanding the humans developing, maintaining or operating the system has.
  • Comprehension debt compares to technical debt in a way, but there are very important differences
  • Technical debt is a conscious tradeoff, meanwhile comprehension debt builds up without human decision
  • Unlike tech debt, dragging us down (slow builds, dependencies etc.), comprehension debt is invisible, everything seems good until it doesn't - tests green, codebase looks clean, but nobody really understands what's going on
  • Until something breaks, no-one knows where these debts are located.

Cognitive surrender is the means to increase the comprehension debt in the project. In terms of AI coding agents, every time we are blindly accepting code generated by the agents, we increase this debt. This debt eventually bites back, and it does so where it hurts the most: during an incident, during a debug session, while struggling with trying to keep the AI bills down so that we don't run out of tokens after a day of work.

This tool is for preventing this cognitive surrender while trying to maintain momentum created by the AI agents. By moving the balance from cognitive surrender to cognitive offloading, we want to keep ourselves in the loop while still allowing us to make advantage of the efficiency gains provided by AI coding agents.

Develop

pnpm.

pnpm build emits dist/cli and dist/ui. prepack runs that build, so pnpm pack / pnpm publish always ship the UI.

pnpm sync:skill copies the JSON Schema into skills-next/comprehende/, pins npx comprehende@<version> there, and mirrors that tree into .agents/skills/comprehende so agents in this checkout use the next skill. It does not touch skills/comprehende/.

comprehende serve and comprehende export share one UI and one git payload. Serve resolves refs to commit SHAs when it starts, then computes those payloads from the objects on each request. Export writes the same JSON (and image bytes) next to the UI so any static file server can host the review.

pnpm dev and pnpm exec run with this package as cwd, so they only make sense when this repo is the one under review. To review a different project from a checkout, cd into it and run npx [email protected] (or node /path/to/comprehende/dist/cli/main.js after pnpm build).

Release

Edit the skill in skills-next/comprehende/. npx skills add reads skills/comprehende/ only.

Bump version in package.json when the CLI or UI changes, then run pnpm sync:skill so the next skill pin matches. Pre-commit and pnpm test fail if the staged package version and next skill pin differ. Do not bump for skill-only edits.

When that next skill should ship with npx skills add, run pnpm release:skill. That copies skills-next/comprehende/ onto skills/comprehende/. Run it in the same change that publishes a new CLI. Then npx skills add installs instructions that match the package they pin.

Push to main. CI packs and tests the tarball on every change. If the version is not on npm yet, CI publishes it. Skill-only commits keep the same version, so they do not publish.

The first publish is manual (pnpm publish --access public) so you can claim the name. After that, add a GitHub Actions trusted publisher on npmjs.com for workflow ci.yml.

Fixture

pnpm fixture
cd fixtures/repo
node ../../dist/cli/main.js serve --data ../example/review.json

Export a static copy (cwd still fixtures/repo):

node ../../dist/cli/main.js export --data ../example/review.json --out ../../fixtures/site

The folder has the UI plus frozen api/*.json payloads and image bytes. There is no git in that folder. Host it with any static file server:

python3 -m http.server --directory ../../fixtures/site 8080

pnpm fixture writes a tiny git repo to fixtures/repo (gitignored) and a refs-only fixtures/example/review.json. Serve or export with cwd set to fixtures/repo.