--- name: running-plans description: Execute an approved plan step by step with checkpoints, an append-only journal, and provider fallback when a tool fails or is missing. Use when a plan exists and the user says to start — 开始 / 执行 / 跑吧 / 继续 / 动手. Verifies each step against its own criterion instead of assuming success, stops and asks rather than silently rerouting when reality diverges, and refuses to retry a failing action more than twice without diagnosing it. Handles long-running work by reporting and yielding rather than waiting in silence. Appends to .superclarity//journal.md. Do NOT use without an approved plan, and do NOT use to expand scope beyond it. license: MIT metadata: pack: superclarity phase: execute --- # Execute without drifting Execution rarely fails because one step was performed badly. It fails by drifting: the goal shifts mid-run, a verification is skipped because the output "looked right", or the same failing action is retried eleven times. Answer the user in whatever language they wrote in. ## The loop, per step 1. **Mark it running** in the plan file, and in the todo tool if one exists. 2. **Do the step** using its bound provider. 3. **Check the result against the step's own `verify` line.** Not against your expectation of it. A tool returning without error is not evidence that it did the right thing — read the artifact. 4. **Mark the outcome** and append one journal line: what came out, what you now know, what surprised you. Step 3 is the one that gets skipped under pressure, and it is the one that matters. Everything downstream inherits an unverified step's errors. ## When the provider fails or is missing Go to the step's `fallback`. It was written before the pressure of the moment, which is exactly why it is more trustworthy than an improvisation now. If the fallback is also unavailable, stop. Do not invent a third route: an unplanned substitution is a scope change the user never approved. **Two failures of the same action is the limit.** Then diagnose before touching it again: - Read the actual error, in full. - Classify it — configuration (missing credential, not logged in), input (a parameter too narrow or malformed), or external (rate limit, outage). - Bring the user the diagnosis and two or three options with a recommendation. Retrying an unchanged action against unchanged conditions is not persistence, it is spending the user's budget to receive the same error. ## Long-running work When something will take longer than a few minutes: - **Preferred:** report that it has started, say how progress can be checked, and end the turn. The user can come back and ask. - If they explicitly want you to wait, wait, and surface progress as it arrives. Never sit silent for a long stretch without having said you would. From the outside, a working agent and a hung agent are indistinguishable. ## The journal Append to [`journal.md`](templates/journal.md) at every step boundary. Append only — correct a wrong entry with a new, timestamped correction, never by editing history. The journal's whole value is showing what was believed at each point. Keep entries short. One line for a routine step; a few for a decision, a surprise, or a deviation. Record *why*, not just *what* — the "what" is already in the plan. ## Deviation is a conversation, not a decision When reality contradicts the plan — a source is gone, the data is shaped differently, the shortlist was wrong — stop and say so. Propose two or three revisions with a recommendation, get agreement, update `plan.md`, log the revision. **Scope never changes silently, in either direction.** Adding a step because it seemed like a nice idea is not permitted at all. Dropping one because it became impossible needs the user's agreement before you drop it, not a disclosure afterwards — a result covering three of four vendors is a different result from the one they approved, and only they can say whether it is still worth having. ## Interruption Sessions end mid-step. Marking a step `running` before acting is what makes that recoverable, but `running` only records that work started, never that it finished — the journal entry comes at the step boundary, and an interrupted step never reached one. So on picking a task back up, never assume a `running` step needs redoing. Look for the evidence its own `verify` line names. If the evidence is there, the step completed. If it is absent and the step is reversible, redo it. If it is absent and the step is **irreversible** — an email sent, a payment made, a post published — stop and ask, stating exactly what may or may not have happened. Re-running an irreversible step "to be safe" is doing it twice. ## Never do these - Start a costly or irreversible step whose gate has not been passed. - Broaden scope beyond the brief — the user asked for a vendor comparison, not a negotiation strategy as well. - Claim a step is complete without reading what it produced. - Mark the plan complete while any step is `failed`, `blocked`, or `running`. - Record a credential, token, or key in the journal. Redact it and note that you did. - Keep working after asking a question. The answer cannot arrive mid-turn; anything built past the question rests on a guess. ## Checkpoints At each `ask-user` gate, and whenever the user has been away for a while, give three lines: what is done, what is next, what changed since they last looked. Not a step-by-step replay — they have the plan file for that. ## Worked example Step 2 of a vendor comparison is gathering published pricing. The research provider returns nothing for one of four vendors. Wrong: retry it three times, then write "pricing not publicly available" into the report. Right: retry once, since transient failures exist. On the second failure, diagnose — the site is reachable but pricing sits behind a "contact sales" form. That is not a tool failure, it is a fact about the vendor. Journal it, and bring the user a choice: mark that vendor "quote-only" and score it on the criteria that remain, or ask them to supply a quote they already hold. Then carry the distinction into the report: pricing was **not published**, which is not the same as pricing being high, low, or unavailable.