DEV Community: Nino Chavez

The Cut You'll Make Twice

Nino Chavez — Fri, 07 Aug 2026 15:18:53 +0000

There is a file in this blog's repo called tags.ts. Eight lines in, it says this:

IMPORTANT: Do not add new tags without updating this file.
Build validation will reject posts with unapproved tags.

I wrote that. It's addressed to an agent, and every agent that writes a post here reads it.

The schema that would do the rejecting is one line in a different file:

tags: z.array(z.string()).optional(),

Any array of any strings. It appears eight times, once per content collection. There is no validation anywhere that compares a post's tags against the approved list.

So I counted. Two hundred seventy-seven files carry tags. The approved list has eighteen entries. Forty-nine distinct tags are actually in use — thirty-two of them off-list, across sixty-four uses.

The worst one is instructive. ai-development declares a replaces array, a list of the sloppy tags it exists to absorb. 'AI' is in that list by name. AI appears as a live tag on four posts.

The file names the exact mistake. The mistake is in the repo four times. The build has been green the entire time.

A Rule in a File Is a Request

That file is a warning label. It works by being read and agreed with.

Most of what any of us gives a coding agent is a warning label. CLAUDE.md, AGENTS.md, .cursorrules, the system prompt, the paragraph you paste at the top of a session. All of it is text the model reads and mostly honors. Mostly is the operative word, and mostly is worse than it sounds. When a rule gets skipped and the work still looks fine, what tells you? The green build told me my tags were clean for two hundred seventy-seven files.

There are two other things you can build instead, and I had them filed under one name.

I Defined the Jig by Half

In March I reached for carpentry and defined the one I keep coming back to:

A master carpenter doesn't build every piece from scratch. They build jigs—custom tools that hold material at the right angle, guide a cut along a precise line, make a repeatable operation fast and accurate. The jig isn't the product. It's the thing that accelerates the real work of making the product.

Read the clauses. Accelerates. Fast and accurate. Repeatable. Every one is about speed.

Everything after that sentence was about proliferation — agents make jigs cheap, cheap jigs breed, you end up curating a drawer of one-off fixtures instead of doing the work. I still think that's right. Eleven weeks later I described asking an agent to extract a whole methodology into a reusable template, and called that a jig too. Same definition. Same direction.

A jig has two jobs. That definition covers one of them.

Two Directions, and I Only Named One

In March, every jig I named was something an agent built for me. A script to reformat data. A workflow to pre-screen inputs. A template to scaffold a document. Agent makes the fixture, human does the work.

The other direction is the one I never defined. I build the fixture. The agent works inside it.

Both kinds have been in my repos the whole time. Only one ever got a word. That's the tell — I had a name for the fixtures that save me time, and none for the fixtures that take away the agent's options.

The Catalog That Makes a Cut Impossible

Before writing this I went and counted the second kind rather than trusting my memory of it.

It's a retail storefront where a model composes the page layout. A catalog file declares every named place that model may write. Twenty-eight zones across ten surfaces — home, product listing, product detail, cart, checkout, search, account, store locator, and two error states. Each entry carries two booleans: whether the composition engine may target it, and whether a merchant may author there by hand.

Twenty-seven are open to the engine. Twenty-seven are open to the merchant. They are not the same twenty-seven.

One zone under a product grid is open to the merchant and closed to the engine. One zone on the product page is open to the engine and closed to the merchant. Two booleans, two exceptions, and the reason each exception exists is that a person sat down and decided this one thing the model shouldn't touch, and this other thing the merchant shouldn't. The entire governance model for the surface is two flags in a config file that disagree exactly twice.

The cart has three zones. One above the checkout button. One below the fold, capped at two items. One empty state.

Line items, order totals, promo entry, the checkout button itself — none of them are zones. There is no address for them.

That catalog accelerates nothing. Composing a page through it is slower than letting the model emit whatever markup it wants. What it does is remove a cut.

No policy in that system says the model may not change the cart total. Nobody wrote that sentence, and nobody has to. The model receives a schema of the places it may put things, and no address in that schema reaches the total. It isn't forbidden. There's nowhere to put the instruction.

A Hook Is Not a Jig

Here is where my own filing was wrong, and it took someone else pointing at the paragraph to see it.

I have two hooks on this laptop that I'd been calling jigs. One enforces a rule that parallel agent sessions work in separate git worktrees, because sessions sharing one checkout switch each other's branches underneath each other. It's a PreToolUse hook matched against Bash, Write, Edit, and MultiEdit. It reads a lock directory, checks whether another live session holds the repo, and returns permissionDecision: "deny" with a paste-ready command for making the worktree instead.

The second guards reads. Images over 1400 pixels on the long edge get denied — it downscales a copy to 1000px, caches it, hands back the new path. Re-reading a file you already read inside a ten-minute window gets denied too, with a note to cite from context.

Those aren't jigs. They're safety valves.

A jig is shape. Nothing about the zone catalog detects a violation, because a violation has no representation — there is no cart-total address to attempt. A valve is the opposite: it senses a condition and interrupts. It needs the bad thing to be attemptable in order to catch it.

The tell is a feature I'd written off as a footnote. Both hooks let the immediate retry through. In the read guard that's an explicit latch — deny once, set pending_retry: True, and clear it on the next call so the same read succeeds. Its own docstring says "fail-open by design" and calls itself "friction for the reflexive re-read, not a wall." There's an off switch: touch ~/.claude/cache/read-guard/.guard-off.

Every one of those is valve behavior. A fixture has no reset, no fail-open, and no off switch, because there is nothing to switch off. You cannot retry your way past a shape.

So there are three things, not two, and the ladder is: a rule the agent can decline, a valve that stops it and can be reset, and a surface with nowhere to put the bad instruction.

The valves are the cheap ones. Five hundred fifty lines of Python for the worktree hook, 293 for the read guard, a few lines of JSON in settings.json. Anyone running a coding agent can add one this afternoon. Sort your own instructions file into the three columns sometime — mine has two valves, one jig at client scale, and everything else is labels.

A Working Jig Erases Its Own Evidence

Here's what took me longest to see, and it's the reason the third column is harder than it looks.

A valve announces itself. Every time one of my hooks trips, a denial message goes to the agent in-band, with a reason. The trip is the record. If I put the threshold in the wrong place — say 1400 pixels was too aggressive — I find out, because I watch the agent get stopped from doing something reasonable.

A jig produces nothing. That's the point of it, and it's also the problem.

Go back to the storefront resolver. It's 116 lines. When it's handed a zone ID that doesn't exist in the catalog, it throws:

throw new Error(`resolveZone: unknown zone instance "${opts.zoneId}"`);

Loud, immediate, unmissable. Now here's the line that enforces the actual constraint, twelve lines further down:

if (engineRaw !== undefined && meta.engineComposable) {

If the engine produced content for a zone it isn't allowed to write, that condition is false. Execution falls to the next block, then to the static fallback. The page renders. Nothing throws, nothing warns, and the merchant sees a completely normal page with default content in it.

So the resolver is loud about the harmless failure and silent about the real one.

I went looking for where the silent case gets recorded. There's a retrieval log next to it, and its entry type has fields for surface, seed entities, session, brand, and the products that got placed in each zone. Every field describes something that succeeded. There is no field for a discarded write, no source, no reason.

Then I grepped for engineComposable across the entire codebase. It appears in three places: the catalog that declares it, a test file, and line 71 of the resolver. The one line that enforces the constraint is the same line that swallows the evidence, and nothing else in the system ever reads the flag.

That's the second grade of invisibility. The third is worse, and it's the one that should actually worry me: a zone I never declared at all. The engine can't attempt it, so there's no branch to instrument, no discard to log, no line to grep for. The model simply never composes the thing I forgot to make a place for.

How would I ever see that page? Not from an error, not from the log, not from the diff. The output that should have existed and doesn't leaves no trace anywhere in the system that excluded it.

That's the asymmetry that makes jigs genuinely hard rather than just underrated. A fence in the wrong place and a fence in the right place produce identical telemetry: clean.

The fix isn't cleverer geometry. It's putting a valve next to the jig — one else branch at line 71 that records the discard, so the thing the fixture ate leaves a mark on the way down. The catalog stays geometry. The valve makes it observable. That's four lines, and it isn't written.

Build the Jig When You'll Make the Cut Twice

The old post buried the rule in a warning box. You built a jig only when the task was worth the setup. Agents dropping the cost of building one to near zero is what killed that discipline.

The rule survives intact. Nobody builds a jig for one cut. For one cut you clamp carefully, measure twice, go slow.

The one I lean on hardest is ten shell commands that drive a real Chrome profile. Navigate, evaluate JavaScript in the page, screenshot, scrape to markdown, crawl, manage tabs. That's it. The whole thing is public.

I didn't build it for a project, and that's the part that matters. It's installed permanently, on PATH in every shell. Because it's already there, I start every integration reaching for a real interface — a CLI, an API — and driving a human interface stays the fallback it should be. That ordering only works if the fallback exists before I need it. Built per project, it doesn't. It's a detour I don't have time for at the moment I hit a system with no API, so I either skip the work or design the whole thing around mimicry from the start.

Which raises the obvious question: why not use the MCP servers that already do this?

My own config says to prefer the shell commands because of the token footprint. It doesn't say by how much, and the README for my own tool claims thirteen to eighteen thousand tokens with no method attached. So I measured: started each server over stdio, completed the handshake, called tools/list, and ran the result through a real tokenizer instead of dividing by four.

Server	Tools	Bytes of tool schema	Tokens
chrome-devtools-mcp	29	23,244	4,968
@playwright/mcp	24	18,502	3,928

My own README is off by roughly three and a half times, in the direction that flatters my tool. It reads like a measurement and it was an assumption about characters per token — the real ratio here is 4.7, and somebody, probably me, used something near 1.3.

So the honest number is smaller than I'd been telling people, and the size isn't the argument anyway. The argument is when you pay.

Those bytes load at connection, in every session where the server is configured, whether or not the agent ever opens a page. The shell commands cost one sentence in my instructions file — a pointer to a README. Sessions that browse spend about 4,000 tokens reading it. Sessions that don't spend nothing.

I have 3,711 session transcripts on this machine. Two hundred fifty of them made a real browse-* call. Sixty-eight made a real call to one of those MCP servers. Whatever the right denominator is, the shape is the same: a browser is a thing I need occasionally and pay for constantly.

There's a second cost that doesn't show up in bytes. The agent already knows how to write JavaScript and read a DOM. A command that hands it a page and gets out of the way lets it use what it arrived with. A bespoke tool schema wrapping the same operations makes it learn a private vocabulary first, and that vocabulary is a fixture somebody else built for a cut I may not be making.

None of which means don't use them. If you'll genuinely make the cut once, buy the assembled thing. That isn't a compromise; that's the rule working.

The Valve I Left on a Branch

Here's the part that undercuts everything above.

The operator card I load into every session cites one of my own scripts as a reference implementation — a mechanical check that verifies a short-form caption against the long-form post it was derived from, so a claim can't quietly change owners between the source and the summary. I wrote it because I'd watched exactly that failure happen and decided a rule wasn't enough.

It lives on a branch called caption-edits-0803. Five commits of gate work, none of them on main. The syndication/ directory on main has no gate script in it at all.

So the file that tells agents "this rule is enforced mechanically, here's the implementation" points at a check that has never run against anything I've published.

That's the same failure as tags.ts, one level up. The first wrote a rule and never built the mechanism. This one built the mechanism and never installed it. Both read as enforcement from inside the instructions file, and both are labels.

An uninstalled valve is indistinguishable from an installed one until the day it should have tripped. Which is the same silence as before, arriving by a different route.

Nothing Here Demos

I ran through a vendor capability questionnaire last week. It has a row for no-code agent builders, and two words after the row: if available. The next row down asks how you use AI to speed up your own development — writing code, configuring, testing, deploying.

Two rows, opposite bets. One expects a finished product a buyer can score. The other only makes sense if the surface underneath is clean enough that a general-purpose agent can work it without a human translating.

The form isn't badly designed. A rubric compares things that come out the same in every hand, and turnkey is the only category that does. A valve at least demos — you can trip it on a stage and watch it stop something. But there's no cell for we made a class of mistake structurally impossible in this surface, because that isn't a feature. It's an absence, and the better it works the less there is to see.

What I Still Don't Have

I don't have an instrument for the third column. Nothing in that storefront can tell me what the engine tried to compose and wasn't allowed to, and nothing at all can tell me about the zone I never declared. That's the gap that matters, and it's four lines of else branch away from being half-closed.

I also don't have a validator on the tag list. Read the canonical keys, refine the Zod schema from z.string() to an enum built from them, let the build fail. Small the entire time the file has been claiming it already exists.

The drawer of snowflakes I warned about in March is still real. But that one's the cheerful failure — you trip over the clutter and clean it up. The other kind doesn't accumulate anywhere you can trip over it.

The fallback rendered. The page looked right. Nothing asked what was missing.

Measure Your Own Token Waste in Four Exercises

Nino Chavez — Tue, 04 Aug 2026 12:31:56 +0000

Your Intuition About Where Tokens Go Is Probably Wrong

In Nothing Broke. It Just Wasn't There., an audit of a personal AI coding setup found the token-waste problem already solved — not by reasoning about which habits felt expensive, but by measuring a real 60-day corpus and finding that three of four starting hypotheses were wrong.

This workshop is the hands-on half of that measurement. If you've done the companion /doctor workshop, this covers the other clock: not the standing harness, but what accumulates inside every conversation you have with the model.

One idea worth having straight before you start: the agent API is stateless. Every single tool call resends your entire conversation so far, from the top. Nothing is free just because you already said it once. A token that lands early in a long session gets paid for again on every turn that follows it — which is why session length, not any one expensive-feeling action, tends to be the real driver.

Exercise 1: Install the mechanical half

5 min

Why this matters

Two of the four levers here don't need you to think about them at all once they're installed — a hook that blocks specific wastes automatically, and a statusline that shows you context usage without you having to ask. Get these in place first; they start paying off immediately, before you've measured anything.

The structure

Both live in the same public repo as /doctor: github.com/nino-chavez/agentic-ways-of-working.

hooks/read-guard.py — a PreToolUse hook on file reads. It denies two specific patterns once, with a fix handed back in the same response: an oversized image read (over 1400px on the long edge gets a 1000px copy instead), and a re-read of a file that hasn't changed in the last 10 minutes (you get a reminder to cite what's already in context instead). The immediate retry always succeeds — this is friction for the reflexive case, not a wall.

statusline.py — shows model | context tokens (color-coded at 50%/80%) | cwd in your terminal, so a session fattening past a sane point is something you see, not something you discover three tool calls later.

Your turn

If you already cloned the repo for the /doctor workshop, you have everything — just run the installer to wire the rest:

Full install

Wires hooks, statusline, and commands in one pass — safe to re-run

cd ~/agentic-ways-of-working   # or wherever you cloned it
./install.sh

Starting fresh instead:

Fresh clone + install

One command, everything wired

git clone https://github.com/nino-chavez/agentic-ways-of-working.git ~/agentic-ways-of-working
cd ~/agentic-ways-of-working
./install.sh

The installer is idempotent — it backs up your settings.json first, only adds hook registrations that aren't already present, and never overwrites a statusline you've already configured.

Checkpoint

Restart your Claude Code session. You should see the statusline appear at the bottom of your terminal showing your model, current context usage, and working directory. Re-read a file you haven't touched in the last few minutes, then immediately re-read the exact same file again without it changing — the second read should get bounced once with a reminder, and the retry right after should go through clean. That's the hook working as designed.

Exercise 2: Measure, don't guess

5 min

Why this matters

Intuitions about which tool call is expensive are routinely wrong — that's not a hedge, it's the actual finding from running this against a real 2,335-file, 529-session corpus. Three of four starting hypotheses were wrong there. Your setup is different from that one. The only way to know what's actually happening in yours is to run the measurement, not to reason from what feels heavy.

The structure

tools/token-audit.py reads every session log under ~/.claude/projects/**/*.jsonl, streams through them (a multi-gigabyte corpus finishes in a minute or two), and reports where your tokens actually went — not where you'd guess.

python3 tools/token-audit.py [--days 60] [--projects-dir ~/.claude/projects] [--top 20]

--days controls the lookback window (default 60 — use less if you're newer to the tool), --projects-dir lets you point it somewhere else if your Claude Code data isn't in the default location, --top controls how many top offenders it lists per category.

Your turn

Run it against your own history:

Run the audit

No dependencies beyond Python 3

cd ~/agentic-ways-of-working
python3 tools/token-audit.py --days 60

If you're new to Claude Code and don't have 60 days of history yet, shrink the window: --days 14 or whatever you actually have. A thin window still tells you something; it just won't be as stable a picture.

Checkpoint

You should see a report with a handful of named metrics and numbers specific to your own sessions — not the reference numbers from the tool's own documentation. If the report comes back essentially empty, check that --projects-dir is pointing at where your Claude Code session logs actually live (~/.claude/projects by default).

Exercise 3: Read the five numbers

6 min

Why this matters

The report isn't useful until you know what each number is telling you to do. Five metrics carry the whole story.

The structure

Replay multiplier — cache reads ÷ tokens written. This is the big one: because the API is stateless, a payload's true cost is its size times every API call that follows it in the session, which makes session cost roughly quadratic in turn count. On the reference corpus this measured 41×. If yours is high, the fix is almost never trimming what you send — it's shorter sessions and delegating exploration to subagents whose context dies with them instead of accumulating in yours.

Redundant re-read rate — same file, same session, unchanged content, read more than once. A high rate is usually a symptom of long sessions: compaction drops tool results, the agent re-reads what it lost, context grows, compaction fires again. The read-guard hook you installed in Exercise 1 is the backstop; shortening sessions is the actual fix.

Image reads — billed by pixel dimensions, not file size. A full-resolution screenshot can cost several times what a cropped, resized copy of the same content costs. On the reference corpus, images were 78% of all read bytes, mostly from full-page captures re-read dozens of times in design-loop sessions.

Cache-write ratio — cache writes ÷ fresh input. Writes cost roughly 1.25× the input price and happen on cache-TTL expiry (about 5 idle minutes) and on every subagent spawn. A high ratio usually means a fat session getting resumed after sitting idle — each casual resume rewrites the whole context at the premium rate.

Per-model spread — caches are per-model. Switching models mid-session starts a cold cache for whichever model you switched to.

Your turn

Go back to your own report. Find your replay multiplier first — it's usually the biggest single number and the best place to start. Then check redundant-read rate and image reads; those two are the ones a hook can partially catch, so seeing them stay high after Exercise 1 tells you something specific (older history, before the hook was installed, versus a pattern still happening now).

Checkpoint

Name your own replay multiplier and your own redundant-read rate, specifically — not the reference numbers from this page. If either number surprises you compared to what you expected before running the tool, that's the actual point of measuring instead of guessing.

Exercise 4: Turn one number into one change

4 min

Why this matters

A measurement that doesn't change a single habit was a research exercise, not an audit. The point isn't the report — it's what you do differently in your next session.

The structure

Match what you found to what actually fixes it:

If your report shows	The fix
High replay multiplier	Shorter sessions — `/clear` between unrelated tasks instead of one long thread. Delegate multi-file exploration to a subagent when only the conclusion matters to the main task.
High redundant-read rate	Same root cause as above — session length. The hook from Exercise 1 is already backstopping this; shortening sessions addresses the cause instead of the symptom.
Oversized image reads	Already covered — the hook downsizes these automatically now. If your report reflects mostly older history, that's expected; check again in a few weeks.
High cache-write ratio	Stop casually resuming sessions that have been idle a while. Finish sessions instead of leaving them open in the background.
One tool dominating the report	Add a digest step at the source — pull the 20 fields you actually need out of a large raw artifact instead of re-reading the whole thing each time.

Your turn

Pick the ONE row that matches your biggest number from Exercise 3. Not all five — one. Write down, in a sentence, the specific habit you're changing starting with your next session.

Checkpoint

State your one change out loud or in writing: what you'll do differently, starting when. Run the audit again in a few weeks and check whether that specific number moved. If it didn't, the fix didn't match the actual cause — go back to Exercise 3 and re-read the number more carefully.

What You Measured

Four exercises, each covering a different half of the same mechanism:

Exercise	Question	What it protects against
Install the mechanical half	Are the two automatic fixes actually running?	Waste you'd otherwise never notice, turn after turn
Measure, don't guess	What does your own history actually show?	Building a fix for a problem you don't have
Read the five numbers	What does each metric mean for what you do next?	A report nobody acts on because nobody understood it
Turn one number into one change	Did anything actually change?	Measurement as theater instead of practice

Where This Is Heading

The statusline is the only piece of this that's live — it tells you about the session you're in right now. Everything else here is a look backward: token-audit.py tells you what already happened, not what's happening this minute.

Run it again in a few weeks, the same way the /doctor workshop suggests re-running that command. A single measurement is a snapshot. What actually changes your token bill is whether the habit from Exercise 4 is still true the second time you check.

Grade an Agent Tool Before You Install It

Nino Chavez — Mon, 03 Aug 2026 17:25:25 +0000

A Feature List Is Half a Subtraction

In One Component I Didn't Already Have, a plugin advertising eleven agents and fifty-four hooks came out, measured against an existing setup, at a delta of one component.

Nothing in that result was about the plugin's quality. It was about the other half of the subtraction — and that half lives on your machine, not on the project's page.

This workshop runs the four checks against whatever tool is currently in your inbox. None of them requires installing it.

A few terms, defined once:

Baseline — everything already wrapped around your model: instructions, skills, commands, hooks, memory files, tool connections.
Delta — what the tool would add after subtracting your baseline. The only number that answers "should I install this."
Issue tracker — the part of a project's repository the maintainer cannot curate without the gap being visible.
Reversibility — whether the uninstall actually removes what the install added. Frequently assumed, rarely checked.

Exercise 1: Enumerate your baseline

10 min

Why this matters

You cannot measure an addition without knowing the starting number. This is the check people skip, and skipping it is what makes every feature list look impressive — a list of fifty-four things is fifty-four gains only against zero.

It is also the check that pays off permanently. You do it once, and every future tool evaluation becomes a reading exercise.

The structure

Whatever your agent loads at startup, get it into one readable list: instruction files, skills, commands, hooks, tool connections, and any helper binaries on your path.

ls ~/.claude/skills/ ~/.claude/commands/ ~/.claude/hooks/ 2>/dev/null
ls -1 ~/.local/bin

If you followed Audit Your AI Coding Harness, its report is your baseline and you can skip ahead.

The durable version of this is a repository rather than a command. Mine is public, which is the only reason the evaluation in the companion post took twenty minutes instead of an afternoon.

Your turn

Produce your list. Then answer one question about each entry: what does this do, in a sentence, without looking it up?

Checkpoint

You should have a list where you can name the function of every item. Anything you can't explain is a finding on its own — it's loaded into every session and you don't know why.

Exercise 2: Subtract the baseline from the tool

12 min

Why this matters

The delta is the decision. Everything else in this workshop refines it.

The structure

Pull the tool's component list from its reference documentation rather than its README — the first enumerates, the second sells. Many projects publish something like docs/reference/features.md:

curl -fsSL https://raw.githubusercontent.com/<owner>/<repo>/<branch>/docs/reference/features.md

Then walk it and mark each item one of three ways:

The three buckets

Every component lands in exactly one

Bucket	Meaning	What it does to the decision
Native	Your setup or your agent already does this	Removes it from the gain column entirely
New	Genuinely absent from your baseline	This is the delta. The only column that argues for installing
Blocked	New, but unusable for a reason unrelated to quality	Wrong platform, broken upstream, needs a subscription you don't hold, requires patching something you don't control

Blocked is the bucket people collapse into the other two, and it distorts the answer in both directions. A component that is excellent and unusable is not a gain, and it is also not a criticism of the tool.

Then run it backwards: what does your baseline do that the tool's list never mentions? That column is real and nobody publishes it for you.

Your turn

Produce the three-way split, then the reverse column. Count the New bucket.

Checkpoint

You should be able to name your covering item for every Native row. "I think I have something like that" doesn't count — if you can't name it, it belongs in New.

If New is large, the tool is a genuine addition and the rest of this workshop is about risk. If New is one or two items, ask whether those items are available on their own before you adopt everything attached to them.

Exercise 3: Query the issue tracker

10 min

Why this matters

A project's documentation describes what it does when it works. Its issue tracker describes what it does on other people's machines. The second is written by users, and unlike testimonials it can't be curated without the absence being obvious.

This is also the fastest read of a project's health that exists, and it's entirely mechanical.

The structure

Three queries. Volume, recency, and your own failure modes.

# how much is open, and how fast is it arriving
gh api "search/issues?q=repo:<owner>/<repo>+is:issue+is:open&per_page=1" --jq '.total_count'
gh api "search/issues?q=repo:<owner>/<repo>+is:issue+created:>=<30-days-ago>&per_page=1" --jq '.total_count'

# what users argue about most
gh api "search/issues?q=repo:<owner>/<repo>+is:issue&sort=comments&order=desc&per_page=25" \
  --jq '.items[] | "\(.comments)c \(.state) #\(.number) \(.title)"'

Then search the tracker for the things that would specifically hurt you — your platform, your host tool's version, your cost sensitivity, your workflow.

Read for patterns rather than counts. A high open count on a popular project mostly means it's popular. What matters is shape:

Does it break when its host releases a new version? Search the host's version numbers.
Do its own updates break things? Search auto-update and after updating.
Are the most-discussed threads features or the same bug recurring?

Your turn

Run the three queries, then two searches specific to your situation. Write down the pattern in one sentence.

Checkpoint

You should have one sentence of the form: "The recurring failure mode is _, and it would/wouldn't hit me because _."

If your searches return nothing, say that plainly rather than treating silence as a clean bill of health. A young project has a quiet tracker for reasons that have nothing to do with quality.

Exercise 4: Confirm the exit before the entrance

8 min

Why this matters

"It's cheap to try" is a claim about uninstalling, not installing. Every installer is one command. The exit is the part nobody tests, and it's the part that decides whether trying costs you an afternoon or a weekend.

The structure

Read the install guide's own account of what lands on disk, and check each location against your machine before running anything:

ls -1 ~/.local/bin                       # names it might shadow
grep -nE '^\[' <the-config-file-it-edits>  # sections it might rewrite

Prefixed names and new named sections are additive and reversible. Bare generic names and rewrites of sections you already use are not.

Then do the thing almost nobody does: search the issue tracker for the uninstall itself.

gh api "search/issues?q=repo:<owner>/<repo>+is:issue+uninstall+OR+cleanup+OR+remove" \
  --jq '.items[] | "\(.state) \(.created_at[0:10]) #\(.number) \(.title)"'

Open reports that removal leaves things behind are worth more than the entire installation guide. They tell you the true cost of being wrong.

Your turn

Write a one-line verdict for each: name collisions, config writes, and whether uninstall is reported to work.

Checkpoint

You should be able to say, without having installed anything: which files it creates, which existing file it modifies, whether any name shadows one of yours, and whether other people have successfully removed it.

If the install guide won't tell you enough to answer those, that absence is your finding. Installers that won't say what they write are the ones most worth not running.

What You Ran

Four checks, none of which required installing the thing:

A baseline you can read, which turns every future evaluation into a lookup
A three-bucket subtraction — native, new, blocked — run in both directions
Three mechanical queries against the writing the vendor doesn't control
An exit check, before the entrance

The output is a number: how many components this tool would actually add to your setup. That number is the decision, and it is different for every person who asks you whether the tool is good.

Where This Is Heading

Exercise 1 is the one that hurts, and not because it's difficult.

Most people cannot list what their agent loads at startup. The list has grown by accretion — a hook added during one bad afternoon, a rule added after one bad review, three skills installed and never invoked since. Every one of them still loads.

Which means the honest version of "should I install this" usually surfaces a second question underneath it, and it's the less comfortable one: what is already in here that I would not install today?