Skip to main content

Mechanism index

This is the third browsing axis, after browse by role and the tool matrix: pitfalls grouped by their root-cause mechanism.

As the intro puts it, most pitfalls in this book are paradigm-level — not the temperament of any one model, but a shared product of the machinery: a large model plus tool-calling, long context, and auto-execution. Group the pitfalls by mechanism and you'll see how a single root cause keeps changing its face across the lifecycle; once you understand the mechanism, the matching best practice stops being a rule to memorize and becomes something you can derive yourself.

Each pitfall hangs under its primary mechanism only (many are several mechanisms stacked; here we take the dominant one). The seven mechanisms below run roughly from session-level to collaboration-level.

Long-context degradation​

My attention thins out as the context grows: the middle and the earliest material are what I quietly drop first. The fuller the window, the more the instructions that actually matter get drowned out by noise.

Positive mirror: keep context short, focused, and disposable — one task per clean session, and distill long procedures into callable artifacts instead of piling them into the conversation.

Probabilistic completion & compliance​

I'm a probabilistic next-token engine: when information is missing I fill the gap with the most-likely continuation instead of stopping to ask, and I follow prose rules only on average — without an enforcing mechanism, compliance isn't reliable.

Positive mirror: turn gaps into explicit inputs (clarify first, hand me real data, pin version-matched docs), and hand must-follow rules to deterministic mechanisms (hooks / settings / skills) rather than prose.

Tool & permission overreach​

I can call tools, edit files, and execute on my own — once permissions are too broad, guardrails too loose, or I read untrusted content, a destructive action or an injection hijack can land before you notice.

Positive mirror: least privilege + explicit scope boundaries + a plan/review gate, keeping irreversible actions and untrusted input on the far side of execution.

Misaligned objective​

I'm trained to optimize for "looks done / it runs," not "is actually correct." So I silence errors, edit tests to fit the code, and cover only the happy path — letting a green signal stand in for real quality.

Positive mirror: turn "correct" into a verifiable signal — make me surface failures first, test the boundaries against real dependencies, and treat tests as a self-running red/green verification loop.

Insufficient local view​

I look at one local slice at a time: the current file, the current function, the single-threaded sequential path. Which callers this change touches, whether it races under concurrency, whether I quietly broke something next door — these here-and-now sideways consequences are not in my view by default.

Positive mirror: before I act, hand me the scope and current state explicitly — the concurrency profile, the change boundary, the callers and the existing conventions — so I see "what this touches right now" before I touch it.

Insufficient long-term view​

I optimize for "runs right now," not "still maintainable in three months." How tech debt snowballs, how much a schema migration will hurt, why it was decided this way originally, how the docs and copyright will add up later — these consequences that only surface across time are not in my view by default.

Positive mirror: hand me the time-dimension constraints explicitly — the existing architectural decisions and evolution direction, the maintenance cost, the compliance and ownership requirements — so I write for "later," not just for "right now."

Degenerating feedback loops​

The back-and-forth between us forms a loop — and loops degenerate: correcting me repeatedly in the same conversation only tangles it further, reapplying a failed fix makes it worse, and my urge to agree with you lets errors compound.

Positive mirror: when a loop goes bad, reset instead of wrestling (fresh session / rewind), drive the next step from deterministic signals rather than my self-consistent narration, and cap autonomous loops.