Writing Plans That Work

Here's what works and here's what breaks.

Plan Structure

Every hardened plan has these mandatory sections. The plan-hardener agent adds them automatically during Step 2, but you should understand what each does and how to edit them:

Writing a Good Scope Contract

The scope contract is the most important section. It tells the AI exactly what files it can touch — and what's off-limits.

Good: Tight Scope

## Scope Contract
**In Scope**: src/services/UserService.cs, src/repositories/UserRepository.cs,
              tests/services/UserServiceTests.cs, tests/repositories/UserRepositoryTests.cs
**Out of Scope**: frontend/**, deployment/**, docs/** (except this plan)
**Forbidden Actions**:
- Do NOT modify src/database/migrations/ (migration is a separate phase)
- Do NOT change AppSettings.json connection strings
- Do NOT add NuGet packages without explicit approval

Bad: Loose Scope

## Scope Contract
**In Scope**: anything related to users
**Out of Scope**: nothing specific
**Forbidden Actions**: don't break things

"Anything related to users" gives the AI free rein to refactor 20 files. "Don't break things" isn't enforceable. Be specific about paths, and list forbidden actions as concrete file patterns. That's how you get lasagna code — clean layers, each with a purpose — instead of spaghetti where everything touches everything.

Slicing Strategy

Slices are 30–120 minute chunks of work. Each slice should produce a commit-worthy change — the "one PR" rule.

Rules of Thumb

• One layer per slice — don't mix database migration with API controller in the same slice
• Build on foundations — create the model/migration first, then the repository, then the service, then the controller
• Tests with the code — include tests in the same slice as the code they test (not a separate "add tests" slice at the end)
• 30 minutes minimum — slices shorter than this have too much gate overhead
• 120 minutes maximum — slices longer than this accumulate too much risk before the next checkpoint

Example: 6-Slice Plan

Slice 1 — Database migration + model           [30 min]
Slice 2 — Repository + unit tests               [45 min]
Slice 3 — Service layer + business logic tests   [60 min]
Slice 4 — API controller + integration tests     [45 min]
Slice 5 — Error handling + edge case tests       [30 min]
Slice 6 — Documentation + cleanup                [30 min]

Validation Gates

Gates are the quality checkpoints between slices. A gate must be a concrete, executable command — not a human judgment call.

Good Gates

**Gate**:
  dotnet build                              # zero errors
  dotnet test --filter "UserProfile"        # 6+ tests pass
  grep -rn "string interpolation" src/      # zero hits (security)

Bad Gates

**Gate**: "tests pass"           ← Which tests? How many?
**Gate**: "code looks clean"     ← Not executable
**Gate**: "review the changes"   ← Human-dependent, blocks automation

Parallel Execution

Mark slices that can run concurrently with the [P] tag. Add dependency declarations when slices must run in order:

### Slice 1 — Database Migration [30 min]
...

### Slice 2 — Repository Layer [P] [depends: Slice 1] [scope: src/repos/**]
...

### Slice 3 — Service Layer [P] [depends: Slice 1] [scope: src/services/**]
...

### Slice 4 — API Controller [depends: Slice 2, Slice 3]
...

Slices 2 and 3 both depend on Slice 1 (the migration) but are independent of each other — they run in parallel. Slice 4 waits for both to finish. The orchestrator builds a DAG (directed acyclic graph) and schedules accordingly.

Stop Conditions

Stop conditions tell the AI when to halt instead of trying to work around a failure:

**Stop if**: Build fails with compilation error
**Stop if**: Any existing test regresses (not just new tests)
**Stop if**: Migration produces data loss warning
**Stop if**: Security scan finds HIGH or CRITICAL vulnerability

Without stop conditions, the AI may try to "fix" a build failure by removing code, or skip a failing test by commenting it out. Stop conditions force it to report the problem instead of hiding it.

Context Files

Each slice can list which instruction files are relevant. Don't load all 18 — load only what's needed:

### Slice 1 — Database Migration
**Context**: database.instructions.md, security.instructions.md

### Slice 4 — API Controller
**Context**: api-patterns.instructions.md, auth.instructions.md, errorhandling.instructions.md

This keeps the AI's context window focused. A database slice doesn't need caching instructions; a controller slice doesn't need migration patterns.

Common Mistakes

Plan Templates

Eight language-specific plan examples ship with Plan Forge. Use them as starting points:

All examples live in docs/plans/examples/.

📄 Full reference: AI-Plan-Hardening-Runbook.md