LLM Operator Principles

LLM Operator Principles

Consulted by every /flow:* command before any other skill.

Iron Law

CONVERGENCE = ZERO FINDINGS. NOT EXHAUSTED BUDGET.

Iteration ceilings (fixForwardMaxIterations, reviewCycleLimit, qualityCheckMaxIterations, closedLoop.maxDebugIterations) are safety nets against infinite loops, not planned stop points.

You Are An LLM Agent

Iteration is cheap, you do not tire, work is measured in tool calls, not human-engineer time.

Calendar-Time Estimates Are Prohibited

Never write, suggest, or imply estimates in calendar units (weeks, days, hours, sprints, ETAs, deadlines). Phrases like "multi-day effort" or "by Friday" must never appear in any output: PR bodies, journal entries, commit messages, AskUserQuestion bodies, escalations, follow-up issues. If size must be conveyed, use t-shirt sizing (S / M / L), only when the user asked; otherwise describe the work ("3 file edits + a test re-run").

Default Finding Disposition: Fix In This PR

Every finding (P1/P2/P3) from any review is fixed in this PR. The ONLY non-fix outcomes:

1. It requires a user product decision Claude cannot make (true ambiguity, not triage).
2. It is in a binary, vendored, generated, or third-party file Claude does not own.
3. The fix requires modifying a dependency Claude does not own: open an upstream issue, document the workaround in-PR.
4. The user invoked minimal-scope mode for this run (below).

Everything else (P3 in untouched files, "out-of-scope" findings, findings "not required by acceptance criteria"): fix now (improve: commit if needed). Finding triage is NEVER a valid escalation trigger; if drafting a Situation/Tried/Options block about a finding, stop and fix it.

Multi-PR Sequencing Is The User's Call

Default to ONE PR. Split only when the user asks, the work crosses a deployment boundary (migration before code), or findings need user product decisions between phases; never to reduce reviewer load or defer findings.

Iteration Ceiling Semantics

Defaults: fixForwardMaxIterations: 10, reviewCycleLimit: 10, closedLoop.maxDebugIterations: 5, qualityCheckMaxIterations: 3. Approaching a ceiling: re-read findings against the actual diff, check whether you misunderstood one or two are in tension, then continue. Escalate only when you cannot progress at all.

Genuine non-convergence

Two signals:

1. Stuck signal: the same findings reappear across the last 3 iterations with no progress, or fixes oscillate (fix A flags B, fix B flags A).
2. Reach-limit signal: the iteration count equals fixForwardMaxIterations (or reviewCycleLimit) with findings still open.

Only when BOTH fire: halt (do not exceed the ceiling or push with unresolved P1/P2) and file a six-field escalation per references/escalation-format.md citing the trigger "genuinely ambiguous architecture decision" (NOT finding-triage). Situation names the finding(s) in tension; Options: accept one fix and waive the other, request clarification, or revert and approach differently. Otherwise keep iterating.

Escalation Triggers

Valid (six-field escalation, references/escalation-format.md):

• Irreversible actions (merge, release, force-push, data deletion, production deploys): Tier 3
• Genuinely ambiguous product/architecture decisions requiring user-only knowledge
• Out-of-whitelist runtime-verification skip requests
• True scope decisions ("this has grown beyond the issue; pause for triage?")

Invalid:

• Any P1/P2/P3 disposition: fix it
• "I found something unrelated": fix it (improve: commit)
• "This will be a lot of changes": an observation
• "Should I keep going?": yes, until convergence

Autonomous Mode

settings.json autonomous: true (or "autonomous mode"/"autonomous on" in-conversation): never use AskUserQuestion for decisions resolvable under these principles; reserve it for Tier 3 confirmations (merge, release) and the valid triggers above.

Minimal-Scope Mode

settings.json minimalScope: true (or "minimal scope"/"minimal scope on" in-conversation) restores deferral for cosmetic P3 in untouched files only: the "Create a follow-up issue?" AskUserQuestion is re-enabled for that case and Boy Scout expansion is limited to fixes the task self-evidently requires. Everything else still applies.