Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
12 changes: 9 additions & 3 deletions apps/docs/content/docs/examples/committed-never-pushed.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -99,8 +99,14 @@ Before marking the task done, the agent pushed, verified the commit on the remot

This example demonstrates three properties of effective institutional memory:

**The most dangerous bugs are state mismatches, not crashes.** The agent's local environment was perfectly correct — tests passed, files existed, `git status` was clean. The bug was the gap between local state and remote state. Scars are particularly valuable for state-mismatch bugs because they can't be caught by local testing alone.
### The most dangerous bugs are state mismatches, not crashes

**Process scars earn their keep through frequency.** This scar fires on nearly every task completion. That sounds noisy, but the confirmation takes seconds ("Verified push to remote"), and the downside of missing it is days of wasted work. High-frequency, low-cost scars are the backbone of institutional memory.
The agent's local environment was perfectly correct — tests passed, files existed, `git status` was clean. The bug was the gap between local state and remote state. Scars are particularly valuable for state-mismatch bugs because they can't be caught by local testing alone.

**"Done" is a loaded word.** In solo development, "committed" might mean "done." In distributed systems with multiple agents, "done" requires proof that the work is accessible to others. This scar redefines "done" from a local assertion to a distributed verification — and the `confirm_scars` protocol makes that redefinition actionable, not just philosophical.
### Process scars earn their keep through frequency

This scar fires on nearly every task completion. That sounds noisy, but the confirmation takes seconds ("Verified push to remote"), and the downside of missing it is days of wasted work. High-frequency, low-cost scars are the backbone of institutional memory.

### "Done" is a loaded word

In solo development, "committed" might mean "done." In distributed systems with multiple agents, "done" requires proof that the work is accessible to others. This scar redefines "done" from a local assertion to a distributed verification — and the `confirm_scars` protocol makes that redefinition actionable, not just philosophical.
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,14 @@ Instead of `echo $API_KEY`, the agent ran safe existence checks. The credentials

This example demonstrates three properties of effective institutional memory:

**Critical scars justify infrastructure investment.** This scar was so important that it eventually led to a `PreToolUse` hook — an automated gate that blocks commands matching credential-exposure patterns before they execute. The scar came first, proved the risk was real, and justified building the permanent fix. Scars can be the evidence that earns engineering investment.
### Critical scars justify infrastructure investment

**Counter-arguments address rationalizations, not just facts.** "Partial keys are safe" and "containers are isolated" aren't factual errors — they're reasonable-sounding arguments that happen to be wrong in this context. By documenting them explicitly, the scar prevents the agent from independently re-deriving the same flawed reasoning.
This scar was so important that it eventually led to a `PreToolUse` hook — an automated gate that blocks commands matching credential-exposure patterns before they execute. The scar came first, proved the risk was real, and justified building the permanent fix. Scars can be the evidence that earns engineering investment.

**Incident scars have built-in expiration.** Unlike process scars (which never decay), this incident scar fades over 180 days. If the team ships a hook that structurally prevents credential exposure, the scar becomes redundant — and the system knows it. This prevents scar accumulation from becoming a burden.
### Counter-arguments address rationalizations, not just facts

"Partial keys are safe" and "containers are isolated" aren't factual errors — they're reasonable-sounding arguments that happen to be wrong in this context. By documenting them explicitly, the scar prevents the agent from independently re-deriving the same flawed reasoning.

### Incident scars have built-in expiration

Unlike process scars (which never decay), this incident scar fades over 180 days. If the team ships a hook that structurally prevents credential exposure, the scar becomes redundant — and the system knows it. This prevents scar accumulation from becoming a burden.
Original file line number Diff line number Diff line change
Expand Up @@ -107,8 +107,14 @@ The agent explicitly checked its working directory, confirmed the right migratio

This example shows three properties of effective institutional memory:

**Silent failures are the most valuable scars.** The migration CLI didn't crash — it ran successfully against the wrong data. These bugs don't leave stack traces. They leave corrupted databases. A scar is the only thing standing between "it worked" and "it worked on the wrong thing."
### Silent failures are the most valuable scars

**Counter-arguments encode the debugging dead ends.** The two counter-arguments in this scar document the exact wrong mental models that led to the 20-minute investigation. Future agents skip those dead ends entirely because the scar says "you might think X — but actually Y."
The migration CLI didn't crash — it ran successfully against the wrong data. These bugs don't leave stack traces. They leave corrupted databases. A scar is the only thing standing between "it worked" and "it worked on the wrong thing."

**The confirm protocol forces verification.** The agent didn't just see the scar and move on. The `APPLYING` decision required past-tense evidence: "Verified CWD is `/workspace/my-project/backend`." This turns a warning into a checklist item with proof of compliance.
### Counter-arguments encode the debugging dead ends

The two counter-arguments in this scar document the exact wrong mental models that led to the 20-minute investigation. Future agents skip those dead ends entirely because the scar says "you might think X — but actually Y."

### The confirm protocol forces verification

The agent didn't just see the scar and move on. The `APPLYING` decision required past-tense evidence: "Verified CWD is `/workspace/my-project/backend`." This turns a warning into a checklist item with proof of compliance.