Skip to content

Commit abcec8b

Browse files
nTEG-devClaudeclaude
authored
fix: use sub-headings for takeaway sections in examples (OD-741) (#12)
Switch from bold-lead paragraphs to ### headings so each takeaway property stands out visually in the rendered docs. Co-authored-by: Claude <claude@nteg.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent e552410 commit abcec8b

File tree

3 files changed

+27
-9
lines changed

3 files changed

+27
-9
lines changed

apps/docs/content/docs/examples/committed-never-pushed.mdx

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -99,8 +99,14 @@ Before marking the task done, the agent pushed, verified the commit on the remot
9999

100100
This example demonstrates three properties of effective institutional memory:
101101

102-
**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.
102+
### The most dangerous bugs are state mismatches, not crashes
103103

104-
**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.
104+
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.
105105

106-
**"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.
106+
### Process scars earn their keep through frequency
107+
108+
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.
109+
110+
### "Done" is a loaded word
111+
112+
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.

apps/docs/content/docs/examples/credential-exposure-near-miss.mdx

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,8 +100,14 @@ Instead of `echo $API_KEY`, the agent ran safe existence checks. The credentials
100100

101101
This example demonstrates three properties of effective institutional memory:
102102

103-
**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.
103+
### Critical scars justify infrastructure investment
104104

105-
**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.
105+
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.
106106

107-
**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.
107+
### Counter-arguments address rationalizations, not just facts
108+
109+
"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.
110+
111+
### Incident scars have built-in expiration
112+
113+
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.

apps/docs/content/docs/examples/silent-migration-wrong-directory.mdx

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -107,8 +107,14 @@ The agent explicitly checked its working directory, confirmed the right migratio
107107

108108
This example shows three properties of effective institutional memory:
109109

110-
**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."
110+
### Silent failures are the most valuable scars
111111

112-
**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."
112+
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."
113113

114-
**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.
114+
### Counter-arguments encode the debugging dead ends
115+
116+
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."
117+
118+
### The confirm protocol forces verification
119+
120+
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.

0 commit comments

Comments
 (0)