While True

Purpose

Turn both completed iterations and current-state assessments into one continuous planning and execution loop.

This skill exists to ensure that:

no implementation insight is lost
no newly discovered follow-up is left only in transient reasoning
the active plan file stays aligned with reality
the agent can begin from the current situation even when the plan is missing, stale, or incomplete
execution continues immediately instead of stalling after planning or reporting
status reporting does not accidentally terminate an otherwise active execution loop

Core Contract

At any loop boundary — before the first implementation slice, after any completed iteration, or whenever reality diverges from the current plan — the agent must:

assess the current situation
create or refine the canonical plan file
record every important insight, constraint, and obvious follow-up
choose the next highest-priority actionable task
start executing that task immediately
repeat until a real stop condition is reached

This skill is a reality-driven checkpoint-and-continue protocol, not merely a post-iteration checkpoint.

Operating Modes

1. Situation-first entry mode

Use this mode when the loop is starting from the current state rather than from a trustworthy pre-existing plan.

Typical triggers:

the user explicitly says while true, keep going, non-stop, or equivalent
the plan file exists but is stale, vague, or clearly behind the current repository state
there is no plan file yet
a new user request introduces work not yet reflected in the plan
validation, logs, or worktree state reveal obvious work that the plan does not capture
the conversation resumes mid-stream and the next task must be reconstructed from reality

In this mode, the agent may first inspect the current situation, derive the needed plan updates, and only then rely on the plan for subsequent continuation.

2. Post-iteration checkpoint mode

Use this mode after a meaningful execution slice when new insight must be folded back into the plan before continuing.

Typical triggers:

code was changed
tests exposed new constraints
validation revealed weaknesses, gaps, or follow-up work
documentation/spec changes clarified new implementation requirements
a finished task uncovered additional required tasks

Activation

Default Trigger

Activate when at least one of the following is true:

a meaningful iteration just finished and follow-up insight exists
the loop is about to start but no trustworthy plan exists yet
the current plan is materially out of sync with the repository or conversation state
a task is actionable and the user expects continued autonomous execution

Session Mode: ACTIVE_UNTIL_STOP

When the user explicitly activates while-true, the mode remains active across subsequent turns until one of the following is true:

the user explicitly says stop, pause, or equivalent
no actionable backlog items remain
only blocked, destructive, or externally gated work remains

This mode is persistent across checkpoint summaries, progress updates, clarification answers, and plan-repair turns.

Do Not Activate When

Skip activation when:

the interaction is purely informational
no new insight, task, or follow-up exists
the user explicitly asks to stop after the current step
continuing would require approval for destructive, irreversible, or externally sensitive actions

Plan File Selection

Use exactly one canonical planning file.

Planning-file equivalence

ROADMAP.md, PLAN.md, and TODO.md are equivalent names for the same class of canonical planning artifact. Do not treat them as separate mandatory layers unless the project explicitly says otherwise. Most projects use only one of them; start from that reality.

Selection rule

if exactly one of ROADMAP.md, PLAN.md, or TODO.md exists, use it
if more than one exists, use project instructions or repository reality to identify which one is authoritative for open work
if authority is still ambiguous, use the file that is already actively maintained as the open-work source of truth and avoid duplicating changes across multiple plan files
if none exists, create one only if project conventions clearly allow it; otherwise report the gap

Reality-over-plan rule

If the plan and the current situation disagree, trust reality first. Repair the plan before using it as the primary source for continuation.

Situation-seeded planning rule

A plan does not need to pre-exist. If no adequate plan exists, the agent may derive one from the current situation, write it into ROADMAP.md, PLAN.md, or TODO.md, and continue immediately.

Execution Continuity Contract

No status-only stop

A progress update, checkpoint summary, or explanatory response is not a valid stopping point while actionable plan items or obvious reality-derived tasks remain.

The agent must not end the loop on reporting alone.

Start-before-report rule

After selecting the next actionable task, the agent must begin executing it before emitting any completion-style checkpoint response.

Selecting a task is not sufficient. Execution must have started. Examples of valid start actions:

reading the relevant files
running the relevant validation command
opening the target implementation area
making the first scoped edit

Clarification persistence

Answering a user question about progress, rationale, or quality does not deactivate while-true mode unless the user explicitly requests a pause or stop.

Actionable-skip rule

If the highest-priority backlog item is not currently actionable, skip to the next actionable item instead of stopping the loop.

Safe-subset rule

If a full item is ambiguous but a safe subset is clear, execute the safe subset first and keep the item open in the plan.

Anti-replanning churn rule

Do not re-enter planning mode repeatedly without execution progress. A checkpoint should usually be smaller than the next execution phase unless validation repair or plan repair must happen first.

Situation Assessment Protocol

Use this when entering the loop, resuming after interruption, or when the existing plan cannot be trusted as the sole source of truth.

Step 1: Inspect current reality

Review only the sources needed to rebuild an accurate current picture, such as:

the latest user request
current conversation state
the canonical plan file, if any
modified files and uncommitted work relevant to the task
failing tests, validation output, logs, or runtime errors
relevant docs/specs/design notes

Step 2: Build a current-state snapshot

Identify:

what is already done
what is currently in progress
what is broken or red
what is missing
what is blocked
what obvious upcoming work should be decomposed now

Step 3: Extract plan-worthy insights

Capture only material items such as:

new implementation tasks
missing validation
missing regression coverage
newly clarified acceptance criteria
broken surfaces requiring repair
explicit assumptions and risks
deferred-but-real research or follow-up work

Step 4: Seed or refine the plan

Translate the current-state snapshot into the canonical plan file.

This may mean:

tightening an existing item
adding missing subtasks
marking already-finished work complete
splitting one vague future item into a few concrete ordered tasks
creating the initial plan from scratch when none exists

Step 5: Continue immediately

Once the plan reflects reality, choose the next actionable task and start executing it. Creating or repairing the plan is not a stopping point.

Checkpoint Protocol

Use this after any meaningful execution slice or after a situation assessment that uncovered plan-worthy truth.

Global guardrails

prefer targeted updates over wholesale plan rewrites
do not reorganize the entire plan file for cosmetic reasons
do not split one task into many smaller tasks unless the split improves execution clarity
do not create plan churn just because a checkpoint happened
if an existing plan item already captures the discovered issue, refine that item instead of creating a near-duplicate

Step 1: Gather insights

Review the completed iteration or the just-assessed current situation and extract:

newly discovered bugs
deferred edge cases
missing validation
missing benchmarks
missing docs/spec sync
performance concerns
invariants that should become tests
temporary compromises
migration triggers
runtime/config assumptions
user-visible limitations
newly clarified future work

Do not capture noise. Only capture items that prevent future mistakes, unblock future work, or preserve important discovered constraints.

Step 2: Classify each insight

For each insight, decide whether it is:

done — already fully resolved in the same iteration
follow-up required — must be added to the plan file
future research — not actionable now, but must remain visible
assumption/risk — should be documented in the plan until resolved

Only unresolved or strategically important items belong in the plan file.

Step 3: Update the plan file

Write all follow-up-required items into the canonical plan file.

Required rules

preserve the project's existing file structure and style
place items in the correct section instead of dumping them into a generic bucket
write concise but specific tasks
include the discovered nuance, not just a vague title
mark completed items complete if the current iteration finished them
add newly discovered tasks immediately when they become real
keep research items visible but clearly separated from immediate implementation work
prefer refining an existing plan entry over creating a new duplicate
create a new item only when the discovered insight is materially distinct from what is already tracked
if an existing item is too vague, tighten it with the newly discovered constraint instead of appending a second vague item
keep chronology secondary to usefulness; the goal is a more accurate plan, not a larger one

Deduplication rules

When a related item already exists:

refine the existing entry if the new insight narrows scope, adds a discovered edge case, or clarifies acceptance criteria
create a sibling entry only if the new work is truly separate in execution or ownership
avoid synonym duplication where two items describe the same future work with different wording
if duplicate items already exist, consolidate them into one stronger canonical item when safe to do so

Decomposition Rules

When future work is obvious enough to plan before execution begins, decompose it immediately.

Use decomposition when

the next work is clearly larger than one step
the plan is too vague to support immediate continuation
a bug report or validation failure obviously implies 2-5 concrete follow-up tasks
the user asked for continuous execution and the agent would otherwise stall on vague planning

Decomposition rules

decompose only to the depth needed for immediate execution clarity
prefer a small number of concrete siblings over one vague umbrella task
preserve blocked vs actionable distinctions
keep research-only lines clearly separated from implementation lines
do not create speculative subtrees for work that is not yet real
if only the first slice is clear, plan the first slice and record the remaining uncertainty explicitly

Step 4: Update related in-progress documentation when needed

If the current task touched documentation that is still in a design or exploration stage, update it only when the iteration closed a real white spot.

Documentation update rules

update related docs only if they are clearly still under active design, planning, or specification refinement
do not rewrite stable reference docs just because implementation moved slightly
do update a design/spec doc when the iteration resolved an open ambiguity, fixed a misleading statement, or turned a hand-wavy area into an explicit contract
if the documentation still contains white spots after the iteration, keep them visible instead of pretending the design is complete
if the iteration reveals a new white spot, record it in the plan file and only extend the doc if that extension improves future execution clarity

Typical signs a doc is still in-progress

it explicitly describes future work, open questions, deferred design, or planned implementation slices
it contains exploratory or boundary-setting language
it is being used as a live design contract rather than a finished reference

Typical signs to skip doc updates

the document is already a stable reference and the iteration did not materially change its contract
the only possible edit would be cosmetic phrasing
the insight belongs in the plan file, not in the documentation yet

Good task examples

Add runtime regression for dust assignment when delegator split leaves operator remainder
Benchmark O(D) delegation-backed payout scan and define cached aggregation migration trigger
Document RewardPerDraw bootstrap-only transition in VRF spec and runtime README
Split launch stabilization into repo-local validation vs live operational evidence

Bad task examples

Fix rewards
Improve docs
Handle edge cases

Continuation Protocol

After creating, repairing, or updating the plan file:

re-read the updated plan file
identify the next highest-priority actionable task
start executing that task immediately
only then emit a checkpoint-style progress update if needed

Priority source order

Determine priority using this order:

explicit user instruction
safety or correctness issues exposed by current reality
project-specific canonical priority source
current section ordering inside the canonical ROADMAP.md, PLAN.md, or TODO.md
default execution priority rules below

Validation-first rule

If the current iteration or current situation introduced or exposed failing validation, broken tests, inconsistent docs/spec contracts, or compile errors, the next task must be to repair that broken surface before resuming feature work unless the user explicitly instructs otherwise.

Actionable backlog definition

Actionable items include:

implementation tasks
validation repairs
regression tests
benchmark work
in-progress design/spec updates that close real white spots
measurable hardening work
plan creation or refinement needed to unblock immediate execution

Not immediately actionable:

long-horizon research with no safe subset
tasks explicitly marked deferred by project policy
tasks blocked on missing external approvals or credentials
operational work that requires access the agent does not have

Default execution priority

correctness or safety fixes
broken validation, failing tests, compile errors, or doc/spec dishonesty
missing implementation pieces required by the active roadmap
missing regression coverage for newly discovered invariants
in-progress design/spec updates needed to close newly resolved white spots
deferred research items with a clear safe subset

Stop Conditions

Do not auto-continue only when:

the next step is destructive or irreversible
the next step requires secrets, credentials, or external accounts
the user explicitly asks to stop
the remaining ambiguity blocks even a safe subset of work
no actionable backlog items remain
only blocked or externally gated work remains

If a safe subset exists, continue with that subset.

Output Discipline

When reporting progress, be concise and include:

what insight(s) were added or refined in the plan
which plan file was updated
what next task was selected
what execution has already started
whether execution remains in active while-true mode

Differentiate:

situation checkpoint — the loop was seeded or repaired from current reality and continues
post-iteration checkpoint — the loop folded newly discovered execution insight back into the plan and continues
terminal update — the loop may stop because a real stop condition was reached

Behavioral Axioms

1. Plan honesty over cosmetic completeness

Do not mark work complete if important discovered follow-up is still unresolved.

2. Insight compression over verbosity

Capture the real discovered nuance in the shortest form that preserves future usefulness.

3. Continue by default

The checkpoint is not the end of the task loop. After the plan is updated, execution should continue automatically unless a real stop condition exists.

4. No hidden debt

If the iteration or current-state assessment reveals technical debt, limitations, or required polish, that debt must become visible in the canonical ROADMAP.md, PLAN.md, or TODO.md immediately.

5. Plan stability over plan churn

A checkpoint should make the plan more accurate, not more volatile. Prefer the smallest plan edit that preserves the discovered truth.

6. Reporting does not terminate execution

A message to the user is not, by itself, the end of the loop. The loop ends only on a real stop condition.

7. Reality can seed the plan

The loop may begin from the current repository and conversation state, not only from a pre-existing task list.

8. Reality outranks stale planning

When the plan is out of date, repair or replace the relevant part of it before relying on it for continuation.

Loop Invariant

while actionable, safe work remains:
  assess current reality
  create or refine plan
  choose next actionable task
  start execution
  complete a meaningful slice
  capture new insights
  repeat

The loop may not terminate on a reporting step alone.

Minimal Operating Loop

enter loop or finish iteration
→ assess current situation
→ create or refine ROADMAP.md, PLAN.md, or TODO.md
→ choose next actionable task
→ start execution
→ finish a meaningful slice
→ capture new insights back into the plan
→ continue immediately

Success Condition

This skill is working correctly when the agent can:

start from a missing, stale, or partial plan by reconstructing reality first
turn current-state insight into a usable canonical plan without stalling
fold completed-iteration insight back into that plan after each slice
keep chaining naturally into the next actionable task
avoid terminating on planning or reporting alone while safe work remains