@bastani/atomic 0.9.0-alpha.2 → 0.9.0-alpha.3

package/docs/workflows.md

@@ -43,12 +43,14 @@ Use a workflow when a task should be repeatable, inspectable, resumable, or spli
 - [Direct One-Off Runs](#direct-one-off-runs)
 - [Fast Inference for Workflow Stages](#fast-inference-for-workflow-stages)
 - [Writing a Workflow](#writing-a-workflow)
+- [Migrating from the `defineWorkflow()` Builder API](#migrating-from-the-defineworkflow-builder-api)
 - [Workflow Primitives](#workflow-primitives)
 - [Task and Stage Options](#task-and-stage-options)
 - [Programmatic Usage](#programmatic-usage)
 - [Context Engineering](#context-engineering)
 - [Design Checklist](#design-checklist)
 - [Common Mistakes](#common-mistakes)
+- [Workflow Best Practices](#workflow-best-practices)
 
 ## Quick Start
 
@@ -156,7 +158,7 @@ For the builtin result tables below, `deep-research-codebase`, `goal`, and `ralp
 |---|---|---|
 | `deep-research-codebase` | Scout + research-history chain → parallel specialist waves → aggregator. Indexes the whole repo and synthesizes findings. | Broad or cross-cutting research before you decide what to change. Prefer `/skill:research-codebase` for one subsystem. |
 | `goal` | Persisted goal ledger → bounded worker turns → receipts → three-reviewer gate → deterministic reducer → final report. | Small-to-medium scope changes when you can identify the work surface, state the exact outcome, and name the validation that proves it is done — for example tests, lint/typecheck, docs builds, or observable behavior. |
-| `ralph` | Prompt-engineering → codebase/online research → sub-agent orchestration → multi-model parallel review → optional final-stage PR handoff. | Larger migrations, broad refactors, and multi-package changes where you want Atomic to transform the prompt into a research question, research the codebase before implementing, delegate through sub-agents, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`. |
+| `ralph` | Prompt-refinement → research-prompt-refinement → codebase/online research → sub-agent orchestration → multi-model parallel review → optional final-stage PR handoff. | Larger migrations, broad refactors, and multi-package changes where you want Atomic to refine the prompt for clarity, transform it into a research question, research the codebase before implementing, delegate through sub-agents, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`. |
 | `open-claude-design` | Design-system onboarding → reference import → HTML generation → impeccable-driven refinement → quality gate → rich HTML handoff. Renders a live `preview.html` you can iterate against (opens through `browser` when available). | UI, page, component, theme, or design-token work that benefits from generation + critique loops. |
 
 ### `deep-research-codebase`
@@ -223,7 +225,7 @@ Run examples:
 /workflow goal objective="Fix the settings form validation bug; add/adjust the focused test and consider it done when invalid emails show the inline error without submitting"
 ```
 
-`goal` creates an OS-temp `goal-ledger.json` artifact, renders goal-continuation context for each worker turn, writes each worker receipt to `work-turn-N.md`, and appends receipts, reviewer decisions, blockers, reducer decisions, and lifecycle events to the ledger. The objective is treated as user-provided data, not higher-priority instructions.
+`goal` starts with a single `prompt-refinement` stage that invokes the `prompt-engineer` skill (`/skill:prompt-engineer`) to sharpen the raw objective into a clearer, more actionable form using the Workflow Best Practices prompt anatomy documented later in this guide; the refined objective becomes the operative one recorded in the ledger (the original is preserved as `original_objective` and shown in the final report when it differs). `goal` then creates an OS-temp `goal-ledger.json` artifact, renders goal-continuation context for each worker turn, writes each worker receipt to `work-turn-N.md`, and appends receipts, reviewer decisions, blockers, reducer decisions, and lifecycle events to the ledger. The objective is treated as user-provided data, not higher-priority instructions.
 
 Write the `objective` like a compact acceptance spec. Say what should exist when the run is done, how you want testing handled, which command(s) or manual checks matter, and what outcome proves completion. The workflow is intentionally lean: it does not first generate an RFC or migration plan, so the developer-supplied objective is where scope, validation, and completion criteria belong.
 
@@ -237,7 +239,8 @@ Result fields:
 | `status` | Final reducer status: `complete`, `blocked`, or `needs_human` (or `active` only if externally interrupted). |
 | `approved` | Whether the reducer reached `complete`. |
 | `goal_id` | Per-run goal identifier stored in the ledger. |
-| `objective` | Normalized goal objective used by the run. |
+| `objective` | Normalized goal objective used by the run (after the `prompt-refinement` stage refines the raw objective). |
+| `original_objective` | The raw user-provided objective exactly as given, before `prompt-refinement`. Omitted when refinement left it unchanged. |
 | `ledger_path` | OS-temp path to `goal-ledger.json`, including receipts, reviewer decisions, reducer decisions, blockers, and lifecycle events. |
 | `turns_completed` | Worker/review turns completed. |
 | `iterations_completed` | Same value as `turns_completed`, retained for status summaries. |
@@ -265,7 +268,7 @@ Run examples:
 /workflow ralph prompt="Safely implement the API refactor" git_worktree_dir=../atomic-ralph-api-wt base_branch=main
 ```
 
-Each `ralph` iteration starts by prompt-engineering the user prompt with `/skill:prompt-engineer Transform the following user prompt to a codebase and online research question which can be thoroughly explored: ...`, then researches that transformed question with `/skill:research-codebase ...` and writes the findings under `research/`. The orchestrator treats that research artifact as its primary implementation context, initializes/updates an OS-temp implementation notes file while generating verifiable evidence for any claims it records in the notes and reviewer artifacts, delegates implementation through sub-agents, and asks three independent reviewers to inspect the patch directly against `base_branch`. The reviewer fan-out runs each reviewer on a different primary model family (with shared fallbacks) so the adversarial review gets cross-model coverage instead of three passes from one model. Ralph's orchestrator and reviewers are prompted to verify user-visible behavior end-to-end when practical, using `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios. For UI-applicable or full-stack changes, the orchestrator runs a `playwright-cli` end-to-end QA pass and records a reviewable proof video (referenced in the implementation notes and surfaced as `qa_video_path`); when `create_pr=true`, the final `pull-request` stage attaches or links that video to the created PR/MR/review. If reviewers find issues, the next prompt-engineering and research stages receive the review artifact path so follow-up research can address unresolved findings, and research stages fork from prior research session data when available. The loop stops only when all three reviewers independently approve (each finds no issues) or `max_loops` is reached, so a P0–P3 finding from any single reviewer keeps Ralph iterating instead of being out-voted by a majority quorum. By default Ralph does not start the final `pull-request` stage, and `pr_report` is omitted. Prompt text alone does not opt in. Pass `create_pr=true` only when you explicitly want the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation, such as GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling; Ralph's own PR-creation instructions live in that final stage.
+Each `ralph` run starts with a single `prompt-refinement` stage that invokes the `prompt-engineer` skill (`/skill:prompt-engineer`) to sharpen the raw user prompt into a clearer, more actionable objective using the Workflow Best Practices prompt anatomy documented later in this guide; that refined prompt becomes the operative objective for research, orchestration, and review, while the original is surfaced as `original_prompt`. Each iteration then transforms the refined prompt with `/skill:prompt-engineer Transform the following refined user request into a codebase and online research question which can be thoroughly explored: ...` (`research-prompt-refinement`), researches that transformed question with `/skill:research-codebase ...`, and writes the findings under `research/`. The orchestrator treats that research artifact as its primary implementation context, initializes/updates an OS-temp implementation notes file while generating verifiable evidence for any claims it records in the notes and reviewer artifacts, delegates implementation through sub-agents, and asks three independent reviewers to inspect the patch directly against `base_branch`. The reviewer fan-out runs each reviewer on a different primary model family (with shared fallbacks) so the adversarial review gets cross-model coverage instead of three passes from one model. Ralph's orchestrator and reviewers are prompted to verify user-visible behavior end-to-end when practical, using `playwright-cli`-skilled subagents for web/frontend flows that may depend on backend/API behavior and tmux-skilled subagents for TUI or terminal-app scenarios. For UI-applicable or full-stack changes, the orchestrator runs a `playwright-cli` end-to-end QA pass and records a reviewable proof video (referenced in the implementation notes and surfaced as `qa_video_path`); when `create_pr=true`, the final `pull-request` stage attaches or links that video to the created PR/MR/review. If reviewers find issues, the next `research-prompt-refinement` and research stages receive the review artifact path so follow-up research can address unresolved findings, and research stages fork from prior research session data when available. The loop stops only when all three reviewers independently approve (each finds no issues) or `max_loops` is reached, so a P0–P3 finding from any single reviewer keeps Ralph iterating instead of being out-voted by a majority quorum. By default Ralph does not start the final `pull-request` stage, and `pr_report` is omitted. Prompt text alone does not opt in. Pass `create_pr=true` only when you explicitly want the final `pull-request` stage to inspect provider credentials and attempt provider-appropriate PR/MR/review creation, such as GitHub `gh`, Azure Repos `az repos pr create`, or Sapling/Phabricator tooling; Ralph's own PR-creation instructions live in that final stage.
 
 Set `git_worktree_dir` when you want Ralph's worker stages isolated in a reusable Git worktree. Relative paths resolve from the invoking repository root, existing same-repository worktree roots are reused, and missing paths are created from `base_branch`. Ralph preserves the invoking repo-relative cwd inside the worktree, so launching from `repo/packages/api` with `git_worktree_dir=../repo-wt` runs stages from `../repo-wt/packages/api`.
 
@@ -285,6 +288,8 @@ Result fields:
 | `iterations_completed` | Number of research/orchestrate/review loops completed. |
 | `review_report` | Compact reference to the latest reviewer payload artifact. |
 | `review_report_path` | JSON artifact path for the latest Ralph review round. |
+| `original_prompt` | The raw user prompt exactly as provided, before the `prompt-refinement` stage. |
+| `refined_prompt` | The clarity-refined prompt produced by the `prompt-refinement` stage and used as the operative objective for research, orchestration, and review. |
 
 A typical end-to-end flow is `/skill:research-codebase` → `/skill:create-spec` → `/workflow goal objective="Implement the researched rate-limit behavior, run the focused tests, and finish when the documented burst behavior is validated"` when you can identify the work surface, state the exact outcome, and name the validation that proves it is done. Keep using `/workflow ralph` for larger migrations, broad refactors, and multi-package changes where you want Atomic to research first, delegate through sub-agents, review, iterate, and optionally allow only the final `pull-request` stage to attempt PR creation with `create_pr=true`.
 
@@ -1071,27 +1076,7 @@ Authoring basics:
 - `outputs` declares typed outputs that parent workflows receive from `ctx.workflow(childWorkflow, ...)`.
 - `run: async (ctx) => { ... }` defines the workflow body.
 
-Codemod-style migration from the removed builder API:
-
-```diff
--import { defineWorkflow, Type } from "@bastani/workflows";
-+import { workflow } from "@bastani/workflows";
-+import { Type } from "typebox";
-
--export default defineWorkflow("review-changes")
--  .description("Run two reviewers and synthesize findings.")
--  .input("target", Type.String())
--  .output("decision", Type.String())
--  .run(async (ctx) => ({ decision: await review(ctx) }))
--  .compile();
-+export default workflow({
-+  name: "review-changes",
-+  description: "Run two reviewers and synthesize findings.",
-+  inputs: { target: Type.String() },
-+  outputs: { decision: Type.String() },
-+  run: async (ctx) => ({ decision: await review(ctx) }),
-+});
-```
+Migrating an existing file from the removed `defineWorkflow(...).compile()` builder? See [Migrating from the `defineWorkflow()` Builder API](#migrating-from-the-defineworkflow-builder-api) for the full method-to-key mapping, a before/after walkthrough, and a conversion checklist.
 
 `prompt` and `task` are aliases for task text. Prefer `prompt` inside authored workflow files because it mirrors lower-level `stage.prompt(...)`; `task` remains useful in direct tool calls and chain examples.
 
@@ -1503,6 +1488,121 @@ If a parent workflow exits through `ctx.exit(...)` while a child workflow is in
 
 Continuation replay treats the parent child-workflow boundary as the durable checkpoint: a previously completed child boundary replays with the original exposed outputs and without re-running the child, while a child that failed or was interrupted before completion starts again from the beginning on continuation. If `ctx.exit(...)` wins while a completed boundary is being replayed but before replay finalization, the boundary is finalized as skipped and its preloaded child metadata is omitted from store, persistence, restore, and expanded graph views.
 
+## Migrating from the `defineWorkflow()` Builder API
+
+The chained builder API — `defineWorkflow(name).description(...).input(...).output(...).worktreeFromInputs(...).run(...).compile()` — was removed in [#1457](https://github.com/bastani-inc/atomic/pull/1457). The single `workflow({ name?, description, inputs, outputs, run })` object form is now the only authoring door. There is no shim and no deprecation period: workflow files that still call `defineWorkflow(...).compile()` fail discovery with a module-load error until they are migrated.
+
+This section is for workflow files written against the previous API. If you are authoring a new workflow, skip it and start from [Writing a Workflow](#writing-a-workflow).
+
+### What changed
+
+- `import { defineWorkflow, Type } from "@bastani/workflows"` → `workflow` now comes from `@bastani/workflows`, and `Type` comes from the `typebox` package directly. `@bastani/workflows` no longer re-exports `Type`. The `Static` and `TSchema` *type* exports are still re-exported from `@bastani/workflows`, so `import type { Static } from "@bastani/workflows"` keeps working — only the runtime `Type` builder moved.
+- The fluent builder chain became one object literal passed to `workflow({ ... })`.
+- `name` moved from the `defineWorkflow(name)` argument into the object. It is now **optional** — omit it and discovery derives the name from the filename (the recommended style used by the builtins and most examples), or keep it when you want the name to differ from the file's basename.
+- `outputs` is now **required**. Workflows that declared no outputs before must now pass `outputs: {}`.
+- `.compile()` is gone. `workflow({ ... })` returns the frozen, branded definition directly; `export default` it.
+- The imperative object-form `runWorkflow(...)` runner is also removed (it is a `never` placeholder that throws on access). Programmatic execution uses the exported `run(def, inputs)` helper or a registry — see [Programmatic Usage](#programmatic-usage).
+
+### Builder method → object key
+
+| Removed builder API | New `workflow({ ... })` key |
+| --- | --- |
+| `defineWorkflow("name")` argument | `name: "name"` (optional; derived from the filename when omitted) |
+| `.description(text)` | `description: text` |
+| `.input(key, schema)` (repeatable) | `inputs: { key: schema, ... }` |
+| `.output(key, schema)` (repeatable) | `outputs: { key: schema, ... }` (required, even if `{}`) |
+| `.worktreeFromInputs(binding)` | `worktreeFromInputs: binding` (binding shape unchanged) |
+| `.run(fn)` callback | `run: fn` |
+| `.compile()` terminal | delete — `workflow({ ... })` returns the definition |
+
+`ctx` and every primitive (`ctx.task`, `ctx.chain`, `ctx.parallel`, `ctx.stage`, `ctx.workflow`, `ctx.exit`, `ctx.ui`) are unchanged, so workflow **bodies do not need rewriting** — only the authoring wrapper changes.
+
+### Full before / after
+
+Before (removed API):
+
+```ts
+import { defineWorkflow, Type } from "@bastani/workflows";
+
+export default defineWorkflow("review-changes")
+  .description("Run two reviewers in parallel and synthesize a decision.")
+  .input("target", Type.String({ description: "Path or change target to review." }))
+  .input("base_branch", Type.String({ default: "origin/main" }))
+  .output("decision", Type.String())
+  .output("concerns", Type.Optional(Type.Array(Type.String())))
+  .worktreeFromInputs({ baseBranch: "base_branch" })
+  .run(async (ctx) => {
+    const target = String(ctx.inputs.target);
+    const [quality, runtime] = await ctx.parallel(
+      [
+        { name: "quality", prompt: `Review quality of ${target}` },
+        { name: "runtime", prompt: `Review runtime behavior of ${target}` },
+      ],
+      { concurrency: 2 },
+    );
+    return { decision: `${quality.text}\n${runtime.text}`, concerns: [] };
+  })
+  .compile();
+```
+
+After (current API):
+
+```ts
+import { workflow } from "@bastani/workflows";
+import { Type } from "typebox";
+
+export default workflow({
+  name: "review-changes", // optional — omit to derive from filename
+  description: "Run two reviewers in parallel and synthesize a decision.",
+  inputs: {
+    target: Type.String({ description: "Path or change target to review." }),
+    base_branch: Type.String({ default: "origin/main" }),
+  },
+  outputs: {
+    decision: Type.String(),
+    concerns: Type.Optional(Type.Array(Type.String())),
+  },
+  worktreeFromInputs: { baseBranch: "base_branch" },
+  run: async (ctx) => {
+    const target = String(ctx.inputs.target);
+    const [quality, runtime] = await ctx.parallel(
+      [
+        { name: "quality", prompt: `Review quality of ${target}` },
+        { name: "runtime", prompt: `Review runtime behavior of ${target}` },
+      ],
+      { concurrency: 2 },
+    );
+    return { decision: `${quality.text}\n${runtime.text}`, concerns: [] };
+  },
+});
+```
+
+### Conversion checklist
+
+For each `.atomic/workflows/*.ts` (or workflow-package) file:
+
+1. Swap the import to `import { workflow } from "@bastani/workflows"` and add `import { Type } from "typebox"`. Drop `defineWorkflow` from the `@bastani/workflows` import. `import type { Static, TSchema }` can stay on the `@bastani/workflows` import if you use those types.
+2. Replace `defineWorkflow("<name>")` with `workflow({`. You may keep `name: "<name>"` or drop the key entirely to derive the name from the filename.
+3. Move `.description("<text>")` to a `description: "<text>",` property.
+4. Collect every `.input(key, schema)` into one `inputs: { key: schema, ... },` map.
+5. Collect every `.output(key, schema)` into one `outputs: { key: schema, ... },` map. If there were no `.output(...)` calls, add `outputs: {},` — it is now required.
+6. Move `.worktreeFromInputs(binding)` to a `worktreeFromInputs: binding,` property (same binding shape, unchanged).
+7. Move the `.run(fn)` callback to a `run: fn,` property; the body stays byte-for-byte the same.
+8. Delete the trailing `.compile()`, close the object with `})`, and keep `export default`.
+9. Run `/workflow reload` (or restart Atomic) and `/workflow list` to confirm the file loads. Because `ctx` and its primitives are unchanged, stage behavior, graph layout, resume/kill, and human-input prompts are unaffected.
+
+### Gotchas
+
+- **`outputs` is required.** The old `.output(...)` calls were optional, and a workflow with none compiled fine. The new object form throws `workflow: outputs must be a schema map` when `outputs` is missing, so declare `outputs: {}` for outputless workflows.
+- **`Type` is no longer re-exported.** `import { Type } from "@bastani/workflows"` fails type-checking; import it from `typebox` instead. (`Static` and `TSchema` *types* are still re-exported from `@bastani/workflows`, so those imports do not need to change.)
+- **`.compile()` does not exist.** Leaving it produces a runtime `TypeError`; `workflow({ ... })` already returns the frozen, branded definition.
+- **`name` is derived from the filename when omitted.** `review-changes.ts` becomes the `review-changes` workflow, so an explicit `name` is only needed when it should differ from the basename.
+- **No hand-rolled definitions.** Objects carrying `__piWorkflow: true` that you construct by hand are rejected by discovery and by `ctx.workflow(...)`. Only definitions minted by `workflow({ ... })` are accepted.
+- **The imperative `runWorkflow` runner is gone.** It is now a `never` placeholder that throws on access; use the exported `run(def, inputs)` helper or a registry for programmatic execution.
+- **Keep `outputs` inline for the strictest type checking.** The old builder enforced no-extra-output keys through a `NoExtraOutputs` generic on `.run(fn)`; the object form re-creates that check for inline `outputs` maps, but cannot recover output keys when a schema map is widened or built up before being passed to `workflow({ ... })`. Keep the `outputs` literal inline so the declared-key check stays exact.
+
+Everything else — stage primitives, `ctx.inputs` typing, runtime validation, DAG inference, MCP scoping, resume/kill, worktree binding, model fallback, and the `/workflow` tool contract — is unchanged.
+
 ## Workflow Primitives
 
 Prefer high-level primitives because they create tracked graph nodes, provide consistent handoff semantics, and keep workflow definitions easier to read.
@@ -1904,3 +2004,653 @@ Good workflows are information-flow systems, not just prompt sequences. Keep sta
 - Do not write stage prompts that depend on hidden workflow-wide awareness; make each model stage locally scoped and self-described.
 - Do not parse model gate decisions from ad-hoc prose with regular expressions; configure `schema` on a focused workflow item and consume `result.structured`.
 - Return compact structured decisions and save large artifacts to files; artifact handoffs should still use files when the next stage does not need the whole payload in context.
+
+## Workflow Best Practices
+
+This is the playbook I use to get consistently better results from coding agents and workflow systems.
+
+The core idea is simple: do not treat an agent like a magic box. Treat it like a capable engineering partner that needs a clear objective, tight scope, explicit validation, and occasional steering.
+
+Most weak agent runs fail for predictable reasons: the goal is vague, the scope is too broad, validation is missing, or the agent keeps following the wrong signal. This playbook is about avoiding those failure modes.
+
+The examples below are synthetic and intentionally generic. Replace placeholders like `[component]`, `[test command]`, and `[workflow]` with your own project details.
+
+---
+
+### The core loop
+
+The workflow pattern I rely on most often is:
+
+```text
+Objective -> Scope -> Done criteria -> Run -> Inspect -> Steer -> Validate -> Summarize
+```
+
+In practice, that means:
+
+1. Define the end state.
+2. Constrain the blast radius.
+3. State what counts as done.
+4. Let the agent or workflow work.
+5. Inspect status before reading details.
+6. Steer only when the run is off track, blocked, or missing criteria.
+7. Require evidence before accepting the result.
+8. Ask for a summary, handoff, or next-step plan.
+
+A good workflow prompt does not just say what to try. It says what success looks like.
+
+---
+
+### Prompt anatomy
+
+A strong workflow prompt usually has these parts:
+
+#### Objective
+
+What should be true when the work is complete?
+
+```text
+Implement `[specific behavior]` in `[component]`.
+```
+
+#### Context
+
+What does the agent need to know before acting?
+
+```text
+This is needed because `[reason]`. The relevant code likely lives near `[area]`.
+```
+
+#### Scope
+
+What is the agent allowed to change?
+
+```text
+Only touch files directly required for `[behavior]`.
+```
+
+#### Non-goals
+
+What should the agent avoid?
+
+```text
+Do not redesign `[subsystem]`, refactor unrelated code, or change public behavior outside `[case]`.
+```
+
+#### Done criteria
+
+How will we know the work is complete?
+
+```text
+Done means:
+- `[new behavior]` works.
+- `[existing behavior]` is unchanged.
+- `[test command]` passes.
+- The final response includes changed files, validation results, and remaining risks.
+```
+
+#### Stop conditions
+
+When should the agent stop and ask instead of guessing?
+
+```text
+If this requires changing `[public API/security behavior/data migration]`, stop and ask first.
+```
+
+---
+
+### Core principles
+
+#### 1. Start with the end state
+
+I try to describe what should be true at the end, not just what the agent should investigate.
+
+Bad:
+
+```text
+Look into the login issue.
+```
+
+Better:
+
+```text
+Fix the login redirect regression. Done means users who sign in from `[page]` return to `[expected destination]`, and `[test command]` passes.
+```
+
+#### 2. Keep scope tight
+
+Agents are often tempted to clean up nearby code. Sometimes that is useful, but most workflow runs should be bounded.
+
+Use phrases like:
+
+- `Only touch files required for this behavior.`
+- `Do not refactor unrelated code.`
+- `Preserve existing behavior for [case].`
+- `Make the smallest correct change.`
+
+#### 3. Separate implementation from validation
+
+A change is not done because the agent says it is done. It is done when the relevant evidence supports it.
+
+That evidence can be:
+
+- a targeted test,
+- a broader regression test,
+- a smoke command,
+- a typecheck or lint command,
+- a structured output contract check,
+- or a clear manual verification step.
+
+#### 4. Prefer evidence over speculation
+
+When something fails, I steer the agent back to the observable signal: the error, failing test, log line, user behavior, or broken contract.
+
+```text
+Treat the failing assertion as the source of truth. Do not guess from nearby code alone.
+```
+
+#### 5. Use staged thinking
+
+For ambiguous work, I usually separate the flow into stages:
+
+```text
+Investigate -> identify root cause -> propose fix -> implement -> validate -> summarize
+```
+
+If the cause is not clear, I do not want the agent making broad changes just to see what happens.
+
+#### 6. Steer, do not micromanage
+
+The best steering messages are short and corrective. They add constraints, redirect attention, or provide a decision.
+
+You usually do not need to rewrite the whole prompt. You need to say what changed.
+
+#### 7. Treat failed validation as the next task
+
+A failed test is not a footnote. It becomes the next objective.
+
+```text
+Validation failed on `[command]`. Treat that as the source of truth. Fix the root cause only, rerun the failing check, then report the result.
+```
+
+#### 8. Interrupt stale or wrong work
+
+If a run is solving the wrong problem, based on outdated assumptions, or duplicating another run, stop it. Letting it continue usually creates more cleanup later.
+
+#### 9. Inspect at the right level
+
+For long-running workflows, I do not start by reading every log. I check:
+
+1. overall status,
+2. current stage,
+3. blocker or failure reason,
+4. relevant stage details only if needed.
+
+#### 10. Ask for synthesis before handoff
+
+Before switching from investigation to implementation, or from implementation to review, I often ask for a concise synthesis:
+
+```text
+Summarize root cause, proposed fix, files involved, validation plan, and remaining risks.
+```
+
+---
+
+### Common workflow patterns
+
+#### Scoped implementation sprint
+
+**Use when:** You have a clear feature, bug fix, or issue to delegate.
+
+**Prompt shape:**
+
+```text
+Implement `[feature]` in `[component]`. Only touch files directly needed for this behavior. Done means the new behavior works, existing behavior is unchanged, and `[test command]` passes.
+```
+
+**Why it works:** The agent gets autonomy, but the objective and blast radius are bounded.
+
+**Validation:** Run the most relevant targeted check first, then a broader nearby check if the change is risky.
+
+---
+
+#### Regression repair loop
+
+**Use when:** CI, tests, typecheck, lint, or smoke validation fails.
+
+**Prompt shape:**
+
+```text
+Fix the failing `[test suite]` regression. Treat the failure output as the source of truth. Do not refactor unrelated code. Done means the failing test passes and no nearby tests regress.
+```
+
+**Why it works:** It anchors the run to observable evidence instead of speculation.
+
+**Validation:** Reproduce the failure, fix the root cause, rerun the failing check, then run a nearby or broader check.
+
+---
+
+#### Workflow or tooling smoke test
+
+**Use when:** You changed a workflow definition, prompt contract, structured output, CLI behavior, or developer tool.
+
+**Prompt shape:**
+
+```text
+Validate `[workflow/tool]` after the change. Run a minimal smoke case, confirm required outputs are present, and report whether it can be invoked with expected inputs.
+```
+
+**Why it works:** Workflow and tooling changes often fail at integration boundaries. A small smoke case catches those failures early.
+
+**Validation:** Reload or rerun the tool, check the output shape, and report contract mismatches.
+
+---
+
+#### Human-in-the-loop checkpoint
+
+**Use when:** The workflow might need a product decision, API decision, migration choice, or risky approval.
+
+**Prompt shape:**
+
+```text
+If blocked, ask before changing public API behavior. Otherwise proceed with the smallest compatible fix.
+```
+
+**Why it works:** The agent keeps moving where it can, but does not guess on high-impact decisions.
+
+**Validation:** Confirm the decision is reflected in the final behavior and summary.
+
+---
+
+#### Release gate
+
+**Use when:** Preparing a release, version bump, changelog, publish step, migration, or deployment-adjacent task.
+
+**Prompt shape:**
+
+```text
+Prepare a `[release kind]` release for `[version]`. Do not publish unless validation passes. Report the exact checks performed and any unresolved blockers.
+```
+
+**Why it works:** Release work needs explicit gates and stop conditions.
+
+**Validation:** Require changelog review, tests, build/package checks, and a clear publish/no-publish decision.
+
+---
+
+#### Monitor-and-steer long run
+
+**Use when:** A workflow runs asynchronously, has multiple stages, or may need supervision.
+
+**Prompt shape:**
+
+```text
+Show the current stage and blocker. If implementation is complete, summarize validation status and remaining risks.
+```
+
+**Why it works:** It avoids both blind trust and excessive log-reading.
+
+**Validation:** Inspect status first, then stages, then only the relevant details.
+
+---
+
+#### Investigate before implementing
+
+**Use when:** A bug or request is ambiguous.
+
+**Prompt shape:**
+
+```text
+Investigate `[bug]`, identify root cause, and propose the smallest fix. Do not implement until the cause is clear.
+```
+
+**Why it works:** It prevents the agent from making changes before it understands the failure mode.
+
+**Validation:** Ask for a reproduction, root-cause explanation, proposed fix, and test plan before implementation.
+
+---
+
+### Steering patterns
+
+#### Tighten scope
+
+**Signal:** The agent starts expanding into adjacent cleanup, unrelated files, or broad refactors.
+
+**Steer:**
+
+```text
+Narrow this to `[specific behavior]` in `[component]`. Do not refactor unrelated code or change `[adjacent area]`. Done means `[specific acceptance criteria]`.
+```
+
+**Why:** Prevents risky changes and keeps the run reviewable.
+
+---
+
+#### Add missing done criteria
+
+**Signal:** The agent has a plan, but no clear finish line.
+
+**Steer:**
+
+```text
+Use these done criteria:
+1. `[behavior]` works.
+2. `[regression]` remains unchanged.
+3. `[test command]` passes.
+4. Report files changed and validation results.
+```
+
+**Why:** Makes completion verifiable.
+
+---
+
+#### Redirect an off-track stage
+
+**Signal:** The workflow is investigating the wrong area or solving the wrong problem.
+
+**Steer:**
+
+```text
+Stop pursuing `[wrong direction]`. The relevant signal is `[error/test/user behavior]`. Re-focus on `[target area]` and continue from there.
+```
+
+**Why:** Saves time and prevents wrong assumptions from compounding.
+
+---
+
+#### Respond to a blocked prompt
+
+**Signal:** The workflow asks for approval, a choice, or clarification.
+
+**Steer:**
+
+```text
+Choose `[option]`. Continue only if `[condition]`; otherwise stop and report the blocker.
+```
+
+**Why:** Keeps the workflow unblocked without adding ambiguity.
+
+---
+
+#### Turn failed validation into the next task
+
+**Signal:** Tests, typecheck, lint, build, or smoke checks fail.
+
+**Steer:**
+
+```text
+Validation failed on `[command]`. Treat that as the source of truth. Fix the root cause only, rerun the failing check, then report the result.
+```
+
+**Why:** Prevents accepting partially working output.
+
+---
+
+#### Ask for synthesis
+
+**Signal:** The workflow has gathered information, but the next action is unclear.
+
+**Steer:**
+
+```text
+Synthesize the current findings into: root cause, proposed fix, files likely involved, validation plan, and remaining risks.
+```
+
+**Why:** Converts exploration into a usable plan.
+
+---
+
+#### Pause, kill, or rerun
+
+**Signal:** A run is stale, duplicated, superseded, or based on outdated assumptions.
+
+**Steer:**
+
+```text
+Pause this run; it has been superseded by `[new context]`. Resume only with `[updated objective]`, or stop and summarize current state.
+```
+
+**Why:** Avoids conflicting changes and wasted work.
+
+---
+
+### Copy-paste templates
+
+#### Start a workflow
+
+```text
+Objective:
+Implement/fix `[specific behavior]` in `[component]`.
+
+Context:
+`[short context about why this matters or where to look]`
+
+Scope:
+- Only touch files required for `[behavior]`.
+- Do not refactor unrelated code.
+- Preserve existing behavior for `[existing case]`.
+
+Done criteria:
+- `[new behavior]` works.
+- `[regression case]` still works.
+- `[test command]` passes.
+- Report changed files, validation results, and any risks.
+
+Stop conditions:
+- If this requires `[risky decision]`, stop and ask first.
+```
+
+#### Tighten scope
+
+```text
+Tighten scope to `[specific target]`.
+
+Do not work on:
+- `[excluded area 1]`
+- `[excluded area 2]`
+- broad cleanup or unrelated refactors
+
+Continue only on the path needed to satisfy:
+`[acceptance criterion]`.
+```
+
+#### Add acceptance criteria
+
+```text
+Add these acceptance criteria before continuing:
+
+1. User can `[action]`.
+2. System handles `[edge case]`.
+3. Existing behavior `[existing behavior]` is unchanged.
+4. `[test command]` passes.
+5. Final response includes validation evidence.
+```
+
+#### Redirect a stage
+
+```text
+This stage is off track.
+
+Stop investigating `[wrong area]`.
+The relevant signal is `[error/output/requirement]`.
+Refocus on `[correct area]`.
+
+Next:
+1. Reproduce or inspect `[signal]`.
+2. Identify root cause.
+3. Make the smallest fix.
+4. Run `[validation command]`.
+```
+
+#### Handle failed validation
+
+```text
+Validation failed:
+
+Command:
+`[command]`
+
+Failure:
+`[short sanitized failure summary]`
+
+Treat this as the source of truth.
+Fix only the root cause.
+Rerun the failing command.
+If it still fails, summarize the blocker and stop.
+```
+
+#### Ask for synthesis
+
+```text
+Synthesize current progress into:
+
+- What was attempted
+- What changed
+- What evidence supports the result
+- What remains uncertain
+- Recommended next steps
+- Exact validation commands run
+```
+
+#### Turn findings into implementation steps
+
+```text
+Convert the findings into an implementation plan:
+
+1. Files/components to change
+2. Order of changes
+3. Tests to add or update
+4. Validation commands
+5. Risks or edge cases
+6. Stop conditions
+```
+
+#### Prepare a release gate
+
+```text
+Prepare `[version]` as a `[release kind]` release.
+
+Requirements:
+- Verify changelog entries are complete.
+- Run `[test command]`.
+- Run `[build/package command]`.
+- Do not publish unless all validation passes.
+- If any gate fails, stop and report blockers.
+
+Final response should include:
+- Version
+- Checks run
+- Results
+- Files changed
+- Publish readiness
+```
+
+---
+
+### Concrete examples
+
+#### Example 1: Fixing a failing test
+
+**Scenario:** A package has one failing unit test after a recent change.
+
+**Initial objective:**
+
+```text
+Fix the failing `[unit test]`. Do not rewrite the module. Done means the test passes and nearby tests still pass.
+```
+
+**Steering message:**
+
+```text
+Stop exploring unrelated failures. Focus only on the assertion mismatch in `[test file]`.
+```
+
+**Validation:** Run `[targeted test command]`, then `[nearby test command]`.
+
+**Outcome:** Small fix applied, regression test passes, and the workflow reports exact commands and results.
+
+---
+
+#### Example 2: Repairing a workflow definition
+
+**Scenario:** A custom workflow no longer returns the expected structured output.
+
+**Initial objective:**
+
+```text
+Validate `[workflow]` and fix its output contract. Done means the smoke run returns `[required fields]`.
+```
+
+**Steering message:**
+
+```text
+Treat the missing output field as the root issue. Do not change unrelated stage prompts.
+```
+
+**Validation:** Reload workflow, run minimal smoke input, inspect structured result.
+
+**Outcome:** Contract fixed, smoke test passes, and the workflow can be reused safely.
+
+---
+
+#### Example 3: Investigating before implementing
+
+**Scenario:** A user-reported bug is ambiguous.
+
+**Initial objective:**
+
+```text
+Investigate `[bug]`, identify root cause, and propose the smallest fix. Do not implement until the cause is clear.
+```
+
+**Steering message:**
+
+```text
+Synthesize findings first: root cause, affected path, proposed fix, and validation plan.
+```
+
+**Validation:** Add or run a reproduction test before changing code.
+
+**Outcome:** Clear implementation plan produced, then delegated as a scoped fix.
+
+---
+
+### Anti-patterns
+
+| Anti-pattern | Better approach |
+| --- | --- |
+| `Fix this.` | `Fix [specific failure]; done means [test command] passes.` |
+| No validation step | Require tests, smoke checks, typecheck, or explicit manual verification. |
+| Broad refactors | Constrain the run to the files needed for the objective. |
+| Letting a wrong stage continue | Redirect or interrupt as soon as the agent follows the wrong signal. |
+| Accepting unverified summaries | Ask for changed files, commands run, results, and remaining risks. |
+| Mixing investigation and implementation too early | Ask for root cause and proposed fix before code changes. |
+| Ignoring blocked stages | Answer directly with one decision and any constraints. |
+| Continuing stale runs | Pause, kill, or rerun with updated context. |
+| Reading every log | Inspect status, then stages, then only relevant details. |
+| Publishing without gates | Require release validation and explicit stop conditions. |
+
+---
+
+### Quick reference
+
+Before starting a workflow, include:
+
+- [ ] Objective
+- [ ] Context
+- [ ] Scope
+- [ ] Non-goals
+- [ ] Done criteria
+- [ ] Validation command
+- [ ] Reporting requirements
+- [ ] Stop conditions
+
+Before accepting a workflow result, ask:
+
+- [ ] What changed?
+- [ ] Why was this the right fix?
+- [ ] What evidence supports it?
+- [ ] Which commands were run?
+- [ ] What still might be risky?
+- [ ] Is anything blocked or unresolved?
+
+The better the prompt defines the game, the better the agent can play it.