Lessons Learned

Seven principles behind Plan Forge's architecture, what each one prevents, where it is enforced.

Lesson 1 — Agents Don't Drift Maliciously; They Drift Because No Rule Said Stop

Principle: Define what should not be built, not just what should. Explicit prohibitions cut scope drift by, to quote the source, "an order of magnitude" (guardrails-lessons-learned blog).

Failure mode it addresses: An agent asked to "build a login page" produces a login page plus a password reset flow, an admin panel, a user profile system, and refactored database migrations. The agent is not being creative, it is being thorough with zero scope constraints.

Where it is enforced: Every hardened plan ships a Forbidden Actions section in the Scope Contract. The PreToolUse lifecycle hook (see How It Works → Building Blocks) blocks file edits to paths listed in the active plan's Forbidden Actions. The pattern is enforced by the plan-hardening prompt, not left to the executing agent's discretion.

"The most powerful guardrail isn't 'do this.' It's 'don't do that.'"

Lesson 2 — Auto-Loading Beats Manual Attachment Every Time

Principle: Guardrails that require manual activation are guardrails that go unused. File-pattern-scoped auto-loading drives compliance from optional to default.

Failure mode it addresses: Early Plan Forge required developers to manually attach instruction files to each chat session. Adoption sat at roughly 20%, "whoever remembered." After the breakthrough of applyTo frontmatter, adoption climbed to 100% because activation became automatic on file edits.

Where it is enforced: Each instruction file in .github/instructions/ declares which file patterns it cares about via YAML frontmatter:

---
description: Security guardrails for auth and middleware
applyTo: '**/auth/**,**/middleware/**'
---

When a file matching the pattern is edited, the instruction file loads automatically into the agent's context. See Customization → Custom Instructions for the full pattern reference.

Lesson 3 — The Builder Must Never Review Its Own Work

Principle: The session that wrote the code cannot evaluate it objectively. Sunk-cost bias is a property of the context window, not the model. A fresh review session catches what the build session is structurally unable to see.

Failure mode it addresses: In a single long chat session, the agent that wrote the code will always believe its code is correct. The blind spots that produced the bug live in the same token sequence as the proposed fix. Self-review fails silently, the agent gives itself a passing grade and moves on.

Where it is enforced: Plan Forge mandates session isolation. Builder works in Session 2; reviewer works in Session 3 with fresh context, the same guardrails, and independent judgment. See How It Works → Why Session Isolation Works for the deeper psychological breakdown, and How It Works → The 4-Session Model for the structural reference.

The analogy from the source essay: would a developer be allowed to merge their own PR without review? Same question, same answer for AI agents.

Lesson 4 — Slice Boundaries Are the Only Real Validation Points

Principle: Testing "at the end" does not work. Failures cascade across files faster than the agent can debug them. Validation must happen at every slice boundary, the agent cannot proceed to slice N+1 until slice N passes its gate.

Failure mode it addresses: Building 15 files before running tests guarantees that failures compound. The agent burns its context window chasing regressions that span files it has long since stopped reasoning about.

Where it is enforced: Every hardened plan decomposes a feature into 3–7 execution slices, each with its own Validation Gate. The orchestrator runs the gate after each slice and refuses to advance on failure. See Writing Plans → Slicing Strategy for the slice contract and How It Works → Building Blocks for the gate enforcement model.

Slice gates produce three observable benefits:

• Failures are caught when they are small (1–3 files, not 15)
• The agent fixes the problem with full context of what it just wrote
• Green-to-green progression means a safe rollback point always exists

Lesson 5 — Focused Instruction Files Beat One Giant Guardrails Document

Principle: One concern per file. Each file under ~150 lines. Auto-loaded only when relevant. Long monolithic instruction documents process worse than short focused ones, agents cherry-pick what's convenient and ignore the rest.

Failure mode it addresses: The first version of Plan Forge had a single copilot-instructions.md at roughly 2,000 lines covering security, testing, architecture, database patterns, error handling, and deployment. Key rules buried, contradictions crept in, and the agent applied rules selectively.

Where it is enforced: The .github/instructions/ directory contains 18+ focused files, each with a single concern. See Customization → Custom Instructions for the inventory.

v2.18 extension: Temper Guards and Warning Signs: Each instruction file now ends with two named sections, Temper Guards documents the specific shortcuts agents take that produce compiling but architecturally broken code (e.g. "this is just a DTO, no logic to test", "N+1 won't matter at our scale"); Warning Signs lists observable anti-patterns that reviewers can grep for. Each file teaches not just what to do but why not to skip it.

Lesson 6 — Tech Stack Presets Are Not Optional

Principle: Every stack has different conventions. Guardrails that say "use PascalCase" to a Python developer get the entire system distrusted. Stack-aware presets eliminate the customization tax.

Failure mode it addresses: A stack-agnostic guardrail document either contradicts the project's conventions in places (loss of trust) or stays so generic that it fails to enforce anything specific (loss of value). The middle ground does not exist.

Where it is enforced: Nine first-party presets ship with Plan Forge, .NET, TypeScript, Python, Java, Go, Swift, Rust, PHP, and Azure IaC, selectable via setup.ps1 -Preset <name> at install time. Multi-preset combinations are supported (e.g. -Preset typescript,azure-iac) for full-stack projects. See Stack-Specific Notes for what each preset adjusts.

Lesson 7 — Enterprise Quality Must Be the Default, Not an Upgrade

Principle: Treating quality as optional ("add tests later", "we'll refactor", "security can wait") guarantees that the optional steps never happen. Quality must be structural, the path of least resistance must produce tested, validated, architecturally compliant code.

Failure mode it addresses: Every "we'll fix it later" trains the next agent session to copy the same shortcut. The codebase accumulates technical debt that nobody is responsible for paying down.

Where it is enforced: Hardened plans include test expectations per slice. Architecture guardrails load on every file change. Security guardrails load on every auth file. Testing guardrails load on every test file. There is no "opt in to quality" path, bypassing the defaults requires actively working around them.

v2.19 extension: Exit Proof: Every skill now ends with a verifiable checklist, not "it seems right" but "paste the test output, show the migration file, prove coverage didn't drop." Evidence over assumption. See Customization → Skills for the Exit Proof contract.

"The best developer tools don't make quality easier. They make it unavoidable."

See Also

• Original blog post, first-person narrative version with the failure stories behind each lesson
• How It Works → Why Session Isolation Works, deeper treatment of Lesson 3
• Customization, where Forbidden Actions, Instruction Files, and Skills are configured
• Project History, the version timeline showing when each lesson was codified

📄 Reference adaptation of guardrails-lessons-learned.html. Reference voice; first-person voice preserved only inside cited blockquotes.