What if the intended behavior is unclear?

It documents what the code actually does and flags the ambiguity for a human, rather than guessing at intent.

DocsLow risk

Documentation Loop

Keep docs in sync with the code: update affected docs when behavior changes, verified against the source.

What this Loop Engineering template does

Update the documentation so it matches the current code behavior, changing only the docs affected by the change and verifying examples against the source.

Read the code before editing docs. Only touch docs affected by the change. Do not document behavior that does not exist.

When to use it

Updating docs after a code change

Filling documentation gaps

Keeping examples runnable

When not to use it

Inventing undocumented behavior

Rewriting product positioning

Validation checks

validation

✓Docs match current code behavior

✓Code examples run or compile

✓Links and references resolve

✓No undocumented behavior is invented

Boundaries & stop rule

!Do not change code to match the docs

!Do not invent behavior or APIs

!Do not rewrite unrelated docs

!Do not change brand or product positioning

Stop rule — Stop when the affected docs match the code and examples pass, or after 3 failed verification attempts. If the intended behavior is ambiguous, document what the code actually does and flag the ambiguity for a human.

Copy the loop prompt

claude-goal.txt

/goal Update the documentation so it matches the current code behavior, changing only the docs affected by the change and verifying examples against the source.
Work toward this goal until all validation checks pass or the stop rule is reached.
Loop cycle:
1. Discovery — Read the latest signal for this template before acting: CI output, issue detail, review comment, dataset report, or content brief.
2. Handoff — Hand the work to one agent in an isolated branch, worktree, or clearly scoped session. Keep final approval with a human.
3. Verification — Use an independent review pass to confirm the result, inspect the diff or artifact, and reject shortcut work.
4. Persistence — Save a short run note with the signal reviewed, actions taken, validation result, and next recommended step.
5. Scheduling — Run manually until the loop is reliable; only then consider a scheduled or event-triggered run.
Context:
Read the code before editing docs. Only touch docs affected by the change. Do not document behavior that does not exist.
Validation:
Docs match current code behavior
Code examples run or compile
Links and references resolve
No undocumented behavior is invented
Independent checker:
Use an independent review pass to confirm the result, inspect the diff or artifact, and reject shortcut work.
Boundaries:
Do not change code to match the docs
Do not invent behavior or APIs
Do not rewrite unrelated docs
Do not change brand or product positioning
Stop rule:
Stop when the affected docs match the code and examples pass, or after 3 failed verification attempts.
Maximum iterations: 3
Budget:
Stop before exceeding the agreed per-run token budget.
Human approval:
Required before merge, deploy, delete, purchase, or external communication.
Fallback:
If the intended behavior is ambiguous, document what the code actually does and flag the ambiguity for a human.
Do not delete tests, bypass checks, or modify unrelated files just to satisfy the validation condition. If blocked, stop and summarize the blocker, attempted fixes, and recommended next action.

Failure modes to watch

Documenting behavior the code does not have

Editing code to match stale docs

Broken example snippets

Scope creep into unrelated docs

Loop Engineering FAQ

No. When code and docs disagree, the docs follow the code. Changing behavior to match stale documentation is a forbidden action.