WAYS OF WORKING · DEMO 03 NINO CHAVEZ

Taught once,
enforced forever.

Corrections you give an agent in chat decay the moment the session ends. The fix isn't repetition — it's changing the agent's environment: helpers that make the cheap path the default, hooks that deny the bad path, and CI gates that make the rule law.

PreToolUse — read-guardDENIED
Read-cost guard: oversized image.
  v-log.png is 3258x3346 (~5,000 image tokens at this size).
  A 1000px downscaled copy has been written to: ~/.claude/cache/read-guard/1d3f…png
  Read that copy instead.

→ or scroll to advance · ← to go back

02 THE DECAY PROBLEM

Rules in prose leak. Sessions forget.

A correction typed into chat lives exactly one session. A rule written into the project instructions survives — but it's still prose an agent reads and chooses to apply, and adherence drifts under pressure. Every guard in this deck exists because a written rule wasn't enough. The escalation ladder:

Level 1 · Default

Helpers

Make the cheap, correct path the easiest one to take. Wrappers that collapse noisy commands to one line of signal. The agent complies because it's the path of least resistance.

Level 2 · Gate

Hooks

Deny the bad path at the tool boundary, before it executes. The agent physically can't take the wasteful or dangerous action — and the denial message teaches it what to do instead.

Level 3 · Law

CI ratchets

Conventions the whole project must hold become build gates. No agent — and no human — ships a violation, in any session, ever.

The pattern behind all three: a rule is only as durable as the mechanism that carries it.

03 LEVEL 1 · HELPERS

Exhibit A

122 pkills nobody remembers typing

The auditA mining pass over the full session corpus found 122 pkill invocations across 16 projects — most of them hunting stray preview servers that some earlier turn had started and lost track of.
The insightNobody decided to spend context on process janitoring. It's what agents do by default when the environment gives them no cheaper move.
The mechanismSmall wrappers on PATH: preview manages the server with a pidfile, q collapses any build/test run to one line, waitfor replaces hand-written polling loops.
before — mined from real sessions
$ pkill -f "http.server 8765" 2>/dev/null; echo "server stopped…"
# × 122, across 16 projects
$ npm run build
… 240 lines of webpack output for one bit of signal …

the mined example is verbatim — port 8765 and all

after — helpers on PATH
$ preview dist/
http://localhost:8765/
$ preview --stop
$ q npm run build
ok (14s) ✓ built in 13.2s

one line on success; on failure: last 30 lines + a log path

Instrument first, build second. Every helper was born from a counted waste pattern, not from speculation about what might be useful.

04 LEVEL 2 · HOOKS

Exhibit B

Two sessions, one checkout, wrong branch

The incidentTwo parallel agent sessions shared a working directory and switched branches under each other's feet — commits landed on the wrong branch. The worktree rule existed in prose; it didn't hold.
The mechanismEach session writes a heartbeat lock inside the repo's git dir. When another session's lock is live, contended git operations from the shared checkout are denied before they run.
The careThe guard walks the actual shell command — tracking cd and git -C — so a commit in an uncontended repo is never blocked just because the session lives in a busy one.
PreToolUse — worktree-guardDENIED
$ git commit -m "fix: registration guard"
1 other live Claude session(s) are ALREADY working here:
  - session 3f9a12c4 on 'main' at ~/Workspace/dev/apps/rally-hq
Per working-style.md, parallel sessions MUST isolate in worktrees — sharing this
checkout will overwrite each other's edits and land commits on the wrong branch.
Before doing any work, create your own worktree:

  git -C ~/Workspace/dev/apps/rally-hq worktree add ../rally-hq-wt -b fix && cd ../rally-hq-wt

message text from the hook itself; session id illustrative. Note what the denial does: it hands the agent the exact command that fixes the situation.

05 LEVEL 2 · HOOKS

Exhibit C

Half of all file reads were re-reads

The auditA 60-day session-log audit found 50% of Reads re-read a file already in context (worst case: one file, 184 times in a session), and full-resolution screenshots cost ~4,800 image tokens where a 1000px copy carries the same information for ~900.
The compoundingEvery wasted token is then re-read on each subsequent turn through the prompt cache — an observed ~41× multiplier. Trimming at the Read boundary compounds.
The mechanismA hook on the Read tool: oversized images get denied once with a downscaled copy already written; recent re-reads get denied once with a cite-from-context reminder. The immediate retry always passes — post-compaction re-reads are legitimate.
PreToolUse — read-guardDENIED
Read-cost guard: oversized image.
  v-log.png is 3258x3346 (~5,000 image tokens at this size).
  A 1000px downscaled copy has been written to:
    ~/.claude/cache/read-guard/1d3f40967356b765.png
  Read that copy instead — for screenshots and layout/design review it carries
  the same information at a fraction of the token cost.
  If full-resolution detail is genuinely required, re-run this exact Read —
  the retry will be allowed.

verbatim, and recursive: this denial fired on the agent while it was building this demo series — reviewing a screenshot of demo 01. The guard was right, and the downscaled copy was used.

06 LEVEL 2 · HOOKS

Exhibit D

553 questions that were always answered "go"

Mining the corpus for correction patterns found 553 exchanges with the same shape: the agent ends its turn on a permission-seeking question — "want me to continue?", "should I proceed with #1?" — and the human answers with one word. The question wasn't a decision point; it was a reflex. So the reflex got a hook.

1 · declarative ruleA "decision bias" section in the standing instructions: when the next step is the obvious continuation, take it. Durable, but still prose.
2 · predictive contextA prompt-submit hook injects the user's known override patterns before the agent responds — the question-shapes historically answered "go."
3 · corrective stop hookIf the agent still ends its turn on a hesitation question, a Stop hook blocks the turn with a corrective reason and forces a rewrite. Every fire is logged, so the detection patterns are tuned from data — not from re-arguing in chat.

The three layers share one classifier, fire at different lifecycle points, and exist because each layer alone leaks. That's not redundancy — that's how you retire a correction permanently.

07 LEVEL 3 · LAW

Conventions that fail the build

Session-level guards protect one machine. Conventions the whole project must hold graduate to CI — where no session, agent or human, can ship a violation.

Design-system linter

Raw color values that break in dark mode, component-level theme overrides, states borrowing another state's color family — each violation class is a lint rule that blocks the build.

The standing rule: when a new violation class appears, add a RULE — never run a manual sweep. Sweeps fix instances; rules fix the class.

Doc-coverage ratchet

A baseline file records current documentation coverage. CI fails if coverage drops below it — and the baseline only ever ratchets toward better. Drift is structurally impossible; improvement is one-way.

Invariants in CI

Load-bearing facts that grep can't surface — a column written but never read, a flag the runtime can't distinguish — are declared in a catalog that derives live COMPLIANT/NON-COMPLIANT status and runs as a test.

08 ANATOMY

Why these guards survive

Most guardrails get ripped out within a month, because they block legitimate work once and lose the operator's trust. The ones in this deck share five properties — all quoted or paraphrased from their own docstrings:

1 · Born from an audit

Every guard cites the counted waste or the real incident that created it. No speculative rules — speculation is how you get guards that fight the work.

2 · Fail-open by design

Anything uncertain — unparseable command, missing file, tool error — resolves to allow. In the hooks' own words: "a guard that blocks legitimate solo work gets ripped out; this one only blocks when it is certain."

3 · Deny once, allow the retry

The denial is friction for the reflexive action, not a wall. If the agent re-runs the exact call, it passes — because sometimes full resolution really is needed.

4 · The message teaches

A good denial contains the fix: the downscaled copy already written, the exact worktree command to run. The agent's next action is in the error text.

And fifth: an escape hatch, always — one touch .guard-off away. A guard you can't turn off is a guard you'll delete.

09 HONEST LIMITS

What the guards don't catch

Fail-open is an admission

Choosing to allow on uncertainty means real violations pass when the guard can't be sure. That's the price of keeping the guard installed at all — a strict guard protects nothing after it's deleted.

Guards see tools, not intent

In demo 01's session, a wildcard delete during cleanup destroyed a file no safety net covered — the command was legitimate, the target selection was the error. No tool-boundary guard catches a correctly-formed mistake.

Portability is real work

The image guard shells out to a macOS-native tool; on other platforms that branch simply fails open. Owning small sharp tools means owning their edges — same trade as demo 02.

10 YOUR VERSION OF THIS

Count your corrections, then promote them

If you never touch code

Notice what you keep telling your AI twice. Anything you've corrected three times is not a conversation — it's a missing rule. Write it down where the agent reads it every session.

If you're technical

Audit before you build: count the waste in your own session logs first. Then climb the ladder — wrapper, then hook, then CI gate — and stop at the lowest level that holds.

If you build systems

Design denials as teaching moments: fail open on uncertainty, allow the retry, put the fix in the message, ship an escape hatch. Guards earn permanence by never blocking legitimate work.

PreToolUse / Stop hooks · pure stdlib helpers on PATH: q · gs · preview · waitfor · with-secret lint + coverage ratchets in CI
Colophon. Every number on this page was re-derived from source for this deck — the 122 pkills from a fresh mining run, the audit figures from the guards' own docstrings, the deny messages verbatim (one of them fired on the agent building this page). Demo 03 in the ways-of-working series — the delegation split is demo 01, the tool economics are demo 02.