jonhill90 Close the Loop
A loop closes when the work is implemented, verified, and reported against the rules that govern it. Most failures are missing inputs, not missing effort: the test that was never specified, the constraint nobody read, the "done" that named no evidence.
Run this before starting. It costs minutes and it is the difference between finishing and reopening.
The three questions
- Do I have everything to implement it? The change is specified to the point another agent could execute it — files, order, and what must not change.
- Do I have everything to test it? Every requirement names the check that proves it, and every check names the command that runs it. A requirement with no test is a requirement you cannot finish.
- Do I know the rules that govern it? Repository instructions, the spec sections this touches, and the verification the project requires before a change counts as complete. Read them before planning, not after review.
If any answer is no, the missing input is the first task — not the work.
When to Use
- Before implementing any non-trivial change (3+ files, new features, policy work)
- When creating or reviewing implementation plans in plan mode
- When preparing PR bodies that need structured planning evidence
- Skip for trivial changes (< 3 files, docs-only, single-line fixes)
The sections below are how those three questions get answered on paper.
Required Plan Sections
Every non-trivial plan must include all 9 sections. Order is flexible; names accept alternatives.
1. Goal / Signal
What does success look like? What observable signal confirms this work landed correctly?
## Goal / Signal
After this lands:
- Observable signal: <what changes in the system>
- User-facing impact: <what users see differently>
Alternatives: Objective
2. Scope
What is in scope and what is explicitly out of scope for this change?
## Scope
**In scope:**
- Item A
- Item B
**Out of scope:**
- Item C (future PR)
3. TDD Matrix
Map each requirement to its test. This is the contract between what we build and how we verify it.
## TDD Matrix
| Requirement | Test | Type |
|---|---|---|
| Feature X works | `test_feature_x` | unit |
| API returns 200 | `test_api_returns_200` | integration |
Alternatives: Test Matrix
4. Implementation Steps
Ordered steps with enough detail that another agent could execute them. Group by TDD phase (Red/Green/Refactor) when applicable.
## Implementation Steps
### Phase 1: Red
1. Write failing test for X
### Phase 2: Green
2. Implement X to pass test
### Phase 3: Refactor
3. Clean up implementation
Alternatives: Approach
5. Verification Matrix
Concrete commands and expected results. Every claim in the plan maps to a verification step.
## Verification Matrix
| Check | Command | Expected Result |
|---|---|---|
| Tests pass | `pytest tests/ -v` | All green |
| Lint clean | `shellcheck scripts/*.sh` | No errors |
Alternatives: Verification Checklist
Manual workaround rule: Treat undocumented manual workarounds as blockers by default. Identify the root cause and durable fix, then state one disposition:
patch first;split follow-uponly when the current change is independently safe, does not weaken security, and survives redeploy; ormerge nowonly when the workaround was unnecessary or the durable fix is already included.
6. CI / Drift Gates
What CI checks enforce this change? What drift could occur and how is it caught?
## CI / Drift Gates
- **New gate:** `check_foo.py` runs on PRs
- **Existing gates preserved:** bats, compose, shellcheck
- **Drift risk:** If X changes, Y catches it
Alternatives: CI Gates, Drift Gates
7. Risks & Mitigations
What could go wrong and how do we prevent or handle it?
## Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| X breaks Y | Low | High | Guard with Z |
8. Definition of Done
Checkbox list of all conditions that must be true before this work is complete.
## Definition of Done
- [ ] All tests pass
- [ ] CI green
- [ ] Docs updated
- [ ] Line count constraints met
Alternatives: Done Criteria
9. Stop Conditions / Out-of-Scope
When should work stop? What explicit boundaries prevent scope creep?
## Stop Conditions
**Stop if:**
- X exceeds threshold Y
- Approach Z proves unviable
**Out of scope:**
- Future enhancement A
- Unrelated refactor B
Alternatives: Out of Scope, Out-of-Scope
Plan Checklist
Copy into your plan and check off as you complete each section:
- [ ] Goal / Signal
- [ ] Scope
- [ ] TDD Matrix
- [ ] Implementation Steps
- [ ] Verification Matrix
- [ ] CI / Drift Gates
- [ ] Risks & Mitigations
- [ ] Definition of Done
- [ ] Stop Conditions
Anti-Patterns
| Anti-Pattern | Why It Fails | Fix |
|---|---|---|
| Vague goal ("improve things") | No observable signal to verify | State concrete before/after |
| TDD matrix without test names | Can't verify tests were written | Name every test function |
| Steps without phase grouping | Unclear when to test vs. implement | Group by Red/Green/Refactor |
| Missing stop conditions | Scope creep goes unchecked | Define explicit boundaries |
| Verification without commands | "It works" isn't evidence | Include exact commands + expected output |
| Risks without mitigations | Identified but unaddressed | Every risk needs a mitigation |
| DoD without checkboxes | Can't track completion | Use - [ ] for each condition |
| Scope without "out of scope" | Boundaries are implicit | Explicitly list what you won't do |
| CI section says "existing" only | Doesn't explain new enforcement | Document new gates + drift risks |
| Verification via ad-hoc manual workaround | Root cause unknown, fix isn't durable, breaks on redeploy | Identify root cause, determine least-privilege fix, state merge recommendation: patch first (default), split follow-up (only if safe to ship independently, no security regression, no redeploy breakage), or merge now (only if no real workaround needed or durable fix already in PR) |
Integration
Use primer before planning unfamiliar work. For implementation that
changes behavior, follow red-green-refactor: write the failing test from
the TDD matrix first. Execute the commands from the verification matrix
before reporting completion.