@gobing-ai/spur 0.3.63 → 0.3.64

package/plugins/sp/skills/redesign-web-ui/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: redesign-web-ui
+description: "Upgrade an existing website or app UI past generic AI defaults without rewriting the stack. Triggers: \"redesign this UI\", \"make it look premium\", \"generic AI design\", \"polish this page\", \"restyle the web app\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - pipeline
+    - reviewer
+  pipeline_steps:
+    - scan
+    - diagnose
+    - plan
+    - apply
+    - verify
+  operations:
+    - redesign
+  openclaw:
+    emoji: "🎨"
+see_also:
+  - sp:code-implementation
+  - sp:code-review
+  - sp:source-driven-development
+---
+
+# redesign-web-ui — existing-UI visual upgrade
+
+This is a **technique** skill: it edits presentation. Specific product copy stays; placeholder copy
+becomes real draft text. Information architecture, routing, and data behavior stay unless the
+operator widens the scope.
+
+## When to use
+
+- Redesign or restyle an existing page, app shell, or component set.
+- Make an existing UI look premium / high-end rather than templated.
+- Strip generic AI design fingerprints (Inter-only type, purple-blue gradients, three equal feature cards).
+- Polish a page that feels unfinished (missing hover, focus, loading, empty, or error states).
+- Restyle a web app in place without a framework migration.
+
+## When not to use
+
+- **Greenfield visual identity with no existing UI** — there is nothing to upgrade; design from the brief.
+- **IA or navigation restructure** — out of scope unless the operator asks.
+- **Stack migration** — swapping CSS frameworks or component libraries.
+- **Non-UI work** — APIs, CLI, schemas, backend.
+- **Inventing legal or compliance surfaces** — privacy pages, terms, cookie banners. Link only
+  destinations the product already has.
+
+## Authority (read before changing tokens)
+
+Resolve visual authority in this order. A lower layer never overrides a higher one. Cite the source
+on every token change.
+
+1. **Repository-root `DESIGN.md`** — if it exists, it is the UI SSOT (palette, type, surfaces, motion,
+   density). Read it. Use its tokens by name.
+2. **Existing theme / CSS variables / Tailwind theme** — the live token file the app already compiles.
+3. **This skill's audit heuristics** — only for axes the two layers above leave free.
+
+`docs/04_DESIGN.md` owns non-UI surfaces (commands, flags, DTOs). It is not this skill's authority.
+
+Framework and CSS API facts (Tailwind v3 vs v4, styled-components APIs, browser features): verify
+with source for the pinned version via `sp:source-driven-development`. Cross-check against docs
+before changing config.
+
+## Pipeline
+
+Run in order. Later steps consume the previous step's artifact. Stop after Diagnose when the
+operator asked only for an audit.
+
+### Step 1 — Scan
+
+Read the target UI and its styling entrypoints. Record, with evidence:
+
+| Field | Evidence |
+|---|---|
+| Framework | manifest / entry file |
+| Styling system | Tailwind v3/v4, CSS modules, vanilla, styled-components, … |
+| Token source | `DESIGN.md`, CSS variables, `tailwind.config`, theme file |
+| Scope | routes, layouts, and shared components that will render the change |
+
+Done when every row has a path (or `none — proceed on heuristics`).
+
+### Step 2 — Diagnose
+
+Walk [references/audit-checklist.md](references/audit-checklist.md). Emit a findings table. Every
+row must cite `path:line`. No finding, no change. Cite the reference row you matched.
+
+```markdown
+| ID | Pattern | Severity | Evidence | In-stack fix |
+|----|---------|----------|----------|--------------|
+| F1  | …       | a11y \| fingerprint \| polish | `file:line` | … |
+```
+
+Severity:
+
+- **a11y** — focus, skip-link, alt, contrast, reduced-motion, keyboard path. Visible focus is required. Fix these.
+- **fingerprint** — generic AI look that fights this product. Fix unless a higher authority specifies it.
+- **polish** — optional quality. Apply when it does not fight the authority or the product type.
+
+Done when every checklist category has been considered and every hit is a table row (or the
+category is marked `none`).
+
+### Step 3 — Plan
+
+Order the findings by the Fix Priority below. State the typefaces, palette, and one signature
+choice, each cited to authority or to a subject-specific reason. Optional motion and layout
+upgrades live in [references/upgrade-techniques.md](references/upgrade-techniques.md) — load that
+file only when a finding needs a technique from it.
+
+The plan should list every **a11y** and **fingerprint** finding. Always cite the token source.
+Done when both are present.
+
+### Step 4 — Apply
+
+Work in the existing styling system. Targeted upgrades, not a rewrite.
+
+Fix Priority:
+
+1. Accessibility
+2. Token alignment to authority
+3. Typography and color fingerprints
+4. Hover, focus, active, loading, empty, error
+5. Layout, spacing, max-width
+6. Generic component cliches
+7. Motion that serves the product (and honors `prefers-reduced-motion`)
+
+Before any new import, read the project's dependency manifest. Before editing Tailwind config,
+validate the installed major version against its docs.
+
+Done when every planned **a11y** and **fingerprint** row is reflected in the diff, or explicitly
+deferred with a one-line reason.
+
+### Step 5 — Verify
+
+Confirm with evidence, not assertion. See **Verification** below.
+
+## Hard constraints
+
+- Keep the current framework and styling library.
+- Preserve existing functionality; a visual change that breaks a flow is a failed run.
+- Keep the diff reviewable — small, targeted edits over a greenfield restyle.
+- Prefer the project's existing icon set, font loader, and image pipeline over new dependencies.
+- Honor `prefers-reduced-motion` for every motion addition.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll migrate to a nicer component library while I'm here." | Stack change is out of scope. Upgrade what is already compiled. |
+| "DESIGN.md is just a mood board — I'll pick better colors." | Root `DESIGN.md` is authority. Cite its tokens; do not invent a parallel palette. |
+| "A full rewrite is faster than patching these class names." | Rewrites drop states, a11y, and behavior. Patch in place; the audit is the map. |
+| "I'll add stock photos / a new icon library for polish." | New assets and libraries are fingerprints of their own. Use the project's pipeline. |
+| "Legal links and a cookie banner will make it feel finished." | Invented compliance UI is worse than omission. Link only destinations the product already has. |
+| "A screenshot of the happy path is enough." | Verify behavior, shared routes, empty/error/focus, and both viewports when layout changed. |
+
+## Red Flags
+
+- Diff introduces a second CSS framework or a new icon/font package without a dependency-file check.
+- Palette or typeface that contradicts repository-root `DESIGN.md`.
+- Finding with no `path:line` evidence.
+- Custom scroll hijacking or inertia scroll on a product UI.
+- Claimed "done" with no visual verification evidence (or no statement of what could not be verified).
+- Placeholder copy (`Lorem ipsum`, "John Doe", "Acme Corp") left in the shipped UI.
+
+## Verification
+
+After Apply, ensure each box has evidence (command output, screenshot, or `file:line`), not assertion:
+
+- [ ] Every **a11y** and **fingerprint** finding is fixed or deferred with a reason.
+- [ ] Token changes cite `DESIGN.md`, the live theme file, or a subject-specific reason (source named).
+- [ ] Existing tests still pass; new imports exist in the dependency manifest.
+- [ ] Shared layouts/components that consume the changed tokens still render consistently — cross-check each route that shares them.
+- [ ] Browser (or closest substitute): golden path + empty/error/focus; desktop and mobile viewports when layout or spacing changed.
+- [ ] `prefers-reduced-motion` still disables added motion.
+- [ ] Document what could not be verified (no browser tools → say so; do not claim visual QA).
+
+## See also
+
+- **`sp:source-driven-development`** — verify framework/CSS API facts against the pinned version before editing config.
+- **`sp:code-implementation`** — owns feature implementation; this skill owns the visual upgrade pass.
+- **`sp:code-review`** — review the visual diff for regressions and out-of-scope stack changes.

package/plugins/sp/skills/redesign-web-ui/references/audit-checklist.md

@@ -0,0 +1,121 @@
+# Audit checklist
+
+Lookup for `sp:redesign-web-ui` Diagnose. Every hit becomes a findings-table row with `path:line`
+evidence and an in-stack fix. Severity values (`a11y` / `fingerprint` / `polish`) and when to
+apply each are defined in the skill's Diagnose step.
+
+A category with no hits is recorded as `none`. Do not invent findings to fill the table.
+
+---
+
+## Typography
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Browser default, Inter, Roboto, or Arial as the only face | Pick a display + body pair for *this* product's subject and cite why. Repeating Inter, or swapping Inter for Geist/Outfit/Satoshi with no subject reason, is still a default. | fingerprint |
+| Headlines lack presence | Increase display size, tighten letter-spacing, reduce line-height so titles feel intentional. | fingerprint |
+| Body line length unconstrained | Cap paragraph measure near 65 characters; raise line-height for reading blocks. | polish |
+| Only 400 and 700 weights | Add 500/600 where hierarchy needs a middle step. | polish |
+| Proportional figures in tables, prices, metrics | Tabular nums (`font-variant-numeric: tabular-nums`) or a monospace face for data. | polish |
+| No tracking on display vs. labels | Negative tracking on large headers; slight positive tracking on small labels/small-caps. | polish |
+| All-caps subheaders as the only accent | Sentence case, small-caps, or italic — one treatment, used sparingly. | fingerprint |
+| Orphaned last words in headings | `text-wrap: balance` (headings) or `text-wrap: pretty` (body). | polish |
+
+## Color and surfaces
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Pure `#000` canvas or pure `#fff` only | Off-black / off-white or a tinted dark from the authority palette. | fingerprint |
+| Oversaturated accents | Keep saturation in range with surrounding neutrals; one chromatic accent unless authority specifies more. | fingerprint |
+| Mixing warm and cool gray families | One gray family, tinted with a consistent hue. | fingerprint |
+| Purple/blue "AI gradient" (or cream+serif+terracotta, or acid-green-on-black used as a default) | Neutral bases + the authority accent. Those three looks are legitimate for some briefs; they are fingerprints when chosen without a subject reason. | fingerprint |
+| Generic black `box-shadow` | Tint shadows to the surface hue. | polish |
+| Perfectly even 45° linear fades | Radial, mesh, or a noise overlay — or no gradient. | fingerprint |
+| Conflicting light sources across shadows | One implied light direction. | polish |
+| A single inverted-color band in an otherwise consistent page | Same palette, shifted shade — or a full committed dark/light mode. | fingerprint |
+| Empty flat sections that need presence | Texture, a restrained ambient gradient, or an existing product image. Use the project's image pipeline; do not inject random stock URLs. | polish |
+
+## Layout
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Everything centered and symmetrical | Offset, mixed aspect ratios, or left-aligned headers over centered content — when the content supports it. | fingerprint |
+| Three equal card columns as the feature row | Asymmetric grid, 2-column zig-zag, or a single highlighted module. | fingerprint |
+| `height: 100vh` full-screen sections | `min-height: 100dvh` (mobile browser chrome). | a11y |
+| No max-width on reading/marketing content | Container ~1200–1440px with auto margins. Data-dense dashboards may stay full-bleed. | polish |
+| Uniform radius on every element | Tighter radius on inner controls, softer on outer containers — or sharp, if authority is sharp. | polish |
+| Missing whitespace on marketing pages | Increase spacing until groups read as groups. Dense is correct for data tables. | polish |
+| Card CTAs / feature lists at uneven baselines | Align shared elements (title, price, list start, button) across the row. | polish |
+| Optical vs. mathematical centering (icon-in-circle, play button) | 1–2px optical adjustment. | polish |
+
+Do **not** treat "dashboard has a left sidebar" as a defect. Changing IA is out of scope.
+
+## Interactivity and states
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| No hover on pointer-capable buttons/links | Background, border, or 1px translate — 150–250ms. | fingerprint |
+| No active/pressed feedback | `scale(0.98)` or `translateY(1px)`. | polish |
+| Instant transitions (`transition: none` on chrome) | 150–250ms on interactive chrome; leave data-dense tables snappy. | polish |
+| Missing visible focus ring | Visible `:focus-visible` using the authority accent. Keyboard path is required. | a11y |
+| Spinner-only loading | Skeleton that matches the layout shape. | polish |
+| Blank empty states | A composed getting-started / zero-data view with one next action. | polish |
+| Errors via `window.alert()` or no inline message | Inline field/form error in the product voice. | a11y |
+| Buttons that go to `#` | Real href, or a disabled control with a reason. | a11y |
+| No current-page indication in nav | Distinct active style. | a11y |
+| Instant anchor jumps | `scroll-behavior: smooth` on the document, with reduced-motion fallback to instant. | polish |
+| Animating `top` / `left` / `width` / `height` | Animate `transform` and `opacity`. | polish |
+
+## Content
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| `Lorem ipsum` or `placeholder` copy | Real draft copy for this product. | fingerprint |
+| "John Doe", "Jane Smith", "Acme Corp", "Nexus", "SmartFlow" | Contextual names. | fingerprint |
+| Fake round metrics (`99.99%`, `$100.00`) | Organic figures, or label them as examples. | fingerprint |
+| AI cliches: Elevate, Seamless, Unleash, Next-Gen, Game-changer, Delve, Tapestry, "In the world of…" | Plain, specific language. | fingerprint |
+| "Oops!" / exclamation-mark success toasts | Direct: "Saved." / "Connection failed. Try again." | fingerprint |
+| Title Case On Every Header | Sentence case, unless the brand guide says otherwise. | polish |
+| Identical dates or avatars on every dummy person | Unique assets per distinct person, or drop the avatars. | fingerprint |
+
+## Component patterns
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Card = border + shadow + white fill on every block | Cards only when elevation encodes hierarchy; otherwise background or spacing. | fingerprint |
+| Always one filled + one ghost button | Text/tertiary action when the second action is low emphasis. | polish |
+| Pill "New"/"Beta" badges as decoration | Square badge, flag, or plain label — or remove. | polish |
+| Accordion FAQ / 3-card testimonial carousel / 3-tower pricing as empty decoration | A layout that matches the actual content. Keep the pattern when it *is* the product's IA. | fingerprint |
+| Modal for a single-field edit | Inline edit or a slide-over. | polish |
+| Footer link farm (4+ columns of unused links) | Primary paths + real legal destinations the product already has. | polish |
+
+## Iconography and media
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Mixed icon sets / mixed stroke widths | Standardize on the set already in the dependency manifest. Do not add Phosphor/Heroicons/Lucide as a second library. | fingerprint |
+| Rocket = Launch, shield = Security, as the only metaphors | Less obvious icons from the *same* set, or text. | polish |
+| Missing favicon | Branded favicon in the project's existing public/asset pipeline. | polish |
+| Random stock "team" photos | Real assets, a consistent illustration style, or no people photos. | fingerprint |
+
+## Code quality (UI)
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| Non-semantic soup for nav/main/content | `<nav>`, `<main>`, `<article>`, `<aside>`, `<section>` where they match the role. | a11y |
+| Inline styles mixed into a class-based system | Move the declaration into the project's styling system. | polish |
+| Hardcoded px widths on fluid layouts | `%`, `rem`, `em`, `max-width`, or the system's spacing scale. | polish |
+| Meaningful images with empty or `alt="image"` | Describe the image; decorative images get `alt=""` plus `role="presentation"` if needed. | a11y |
+| `z-index: 9999` and friends | A documented z-scale on the theme. | polish |
+| Missing `<title>`, description, or social meta | Fill from the product name and the page's job. | polish |
+| Import not in the dependency manifest | Use an already-installed package, or stop and ask before adding one. | fingerprint |
+
+## Completeness (product UI, not decoration)
+
+| Problem | In-stack fix | Severity |
+|---|---|---|
+| No skip-to-content link | Visually hidden skip link targeting `<main>`. | a11y |
+| Dead-end views with no way back | A back/close path that uses the existing router. | a11y |
+| No custom 404 | Branded empty-route view with a path home. | polish |
+| Forms without client-side required/format checks | Validate in the existing form library; keep server-side as source of truth. | a11y |
+| Footer legal links that 404 | Point at real routes, or omit. | polish |

package/plugins/sp/skills/redesign-web-ui/references/upgrade-techniques.md

@@ -0,0 +1,66 @@
+# Upgrade techniques
+
+Optional moves for `sp:redesign-web-ui` Plan/Apply. Load this file only when a Diagnose finding
+needs a technique from it.
+
+Every technique here is **polish**. Accessibility and token authority always win. Honor
+`prefers-reduced-motion: reduce` by disabling or replacing motion with an instant state change.
+
+Product/app chrome (dashboards, settings, editors) stays restrained. Marketing/landing pages can
+spend more on one signature moment. Spend boldness in **one** place.
+
+---
+
+## When a technique is in play
+
+Use a technique when:
+
+- The finding is `polish`, and
+- The page type supports it (landing/marketing, or a single product moment), and
+- The authority layer (`DESIGN.md` / theme) does not forbid it.
+
+Skip the technique when:
+
+- It requires a new animation library or a CSS-framework migration.
+- It hijacks scroll (inertia/custom scrollbar physics) on a product UI.
+- It would be the second signature moment on the same page.
+
+---
+
+## Typography
+
+- **Variable-font weight/width** on hover or a short scroll range — one word or one heading, not every line.
+- **Outlined-to-fill** on a display line that is the page's thesis.
+- **Text as mask** only when a real, owned video/image sits behind it.
+
+## Layout
+
+- **Broken grid / overlap** — one element bleeds or overlaps on purpose; the rest stay on the grid.
+- **Whitespace maximization** — one block gets aggressive negative space so it is the only focus.
+- **Sticky stack** — sections pin and stack on scroll on a marketing long-scroll, not inside app chrome.
+- **Split-screen scroll** — two panes moving in opposition; marketing only, and never the only way to reach content.
+
+## Motion
+
+- **Staggered entry** — small Y + opacity cascade on first paint of a group (40–80ms steps).
+- **Spring on press** — interactive controls, not page load.
+- **Scroll-driven reveal** — mask, wipe, or SVG draw tied to scroll *progress*, with a reduced-motion static end-state.
+
+Do not add smooth-scroll inertia, scrolljacking, or a custom scrollbar on product UI. Native
+`scroll-behavior: smooth` plus a reduced-motion instant fallback is the ceiling unless the operator
+asks for more.
+
+## Surfaces
+
+- **Glass** — `backdrop-filter` plus a 1px inner border and a faint inner shadow; only over content
+  that remains readable.
+- **Spotlight border** — cursor-tracking edge light on one featured card.
+- **Grain overlay** — `pointer-events: none`, fixed, very low contrast; skip on dense data tables.
+- **Tinted shadows** — shadow hue matches the surface, not generic black.
+
+---
+
+## Signature test
+
+After picking techniques, keep one memorable moment. If two techniques compete, drop the weaker
+one. The surrounding UI stays quiet so the signature can read.

package/plugins/sp/skills/spur-cli/references/agent.md

@@ -48,7 +48,7 @@ through a coding agent as an external process, producing a persisted run record
 
 | Flag | Purpose |
 | ------ | --------- |
-| `--agent <name>` | Role, executor, agent binary, `auto`, or `inline`. A **role** (`scribe`/`coder`/`reviewer`/`planner`, from `plugins/sp/references/roles.md`) selects the starting tier; an **executor** (an `agent.executors` entry) is a permanent pin; a **bare binary name** works with a one-time warning (transition shim); `auto` uses the declared/default role. **`inline` is host-session-only** (G5 / ADR-047 amendment): `agent run` is a headless subprocess surface, so explicit `inline` is rejected with exit 2 and a stable error message — it never normalizes to `agent.default`. |
+| `--agent <name>` | Role, executor, agent binary, `auto`, or `inline`. A **role** (`scribe`/`coder`/`reviewer`/`planner`, from `plugins/sp/references/roles.md`) selects the starting tier; an **executor** (an `agent.executors` entry) is a permanent pin; a **bare binary name** works with a one-time warning (transition shim); `auto` uses the declared/default role. `inline` is the default selector (0687 / ADR-087): on a host session the work runs in-session; on a headless subprocess surface like `agent run` it substitutes tier resolution and warns once naming the resolved executor — no rejection, no `agent.default` normalization. |
 | `--model <name>` | Agent model argument (e.g. `o3`, `sonnet`). Passed through to the agent's model flag. |
 | `--mode <mode>` | Agent output mode: `text` or `json`. |
 | `--continue` | Resume the previous agent session instead of starting fresh. |

package/plugins/sp/skills/spur-cli/references/workflows/authoring-workflows.md

@@ -218,9 +218,14 @@ verifying shape, or stand in a `note` action until the path is proven, then swap
 
 ## Authoring checklist
 
+- [ ] Fit gate cleared before the mode gate — replay + machine-checkable branch + durable record
+      ([workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#1-fit-gate--workflow-or-prose)).
 - [ ] Mode chosen deliberately (loop → state-machine; pipeline → transition-flow); recorded the reason.
 - [ ] `kind: transition-flow` set for flows; `$schema` quoted.
 - [ ] Initial + terminal states/nodes declared; every transition/edge target exists.
 - [ ] Guards/conditions ordered so the specific case precedes the fallback.
 - [ ] `iterationBound` set for any loop; `env.allow` lists every `${env.X}` used.
+- [ ] Every node inside the simplicity budget — `shell` at or under 5 non-comment units,
+      `agent.run` input referencing a command rather than a raw prompt, guards a single predicate
+      ([workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#3-node-simplicity-budget)).
 - [ ] Validates clean AND dry-run reaches the expected terminal state.

package/plugins/sp/skills/spur-cli/references/workflows/operations.md

@@ -161,22 +161,31 @@ Turn a described process into a validated, dry-run-verified workflow in the righ
 1. **Clarify intent** — restate the process as one or two sentences: the steps, the success terminal,
    the loop/branch points. If ambiguous (which step retries? what ends it?), state the interpretation
    taken.
-2. **Mode-selection gate** — run [mode-selection gate](#sub-procedure-mode-selection-gate). This is
+2. **Fit gate** — run the three-part test in
+   [workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#the-three-part-test) *before* the mode
+   gate: the process earns a workflow only if it replays, branches on a machine-checkable predicate,
+   and needs a durable per-run record. Fewer than three → recommend a descriptive procedure /
+   checklist instead and stop; do not author YAML the process will not use.
+3. **Mode-selection gate** — run [mode-selection gate](#sub-procedure-mode-selection-gate). This is
    mandatory and gating: surface the recommended mode with its reason and the rejected alternative,
    and **confirm before authoring**. Honor an explicit `--kind`.
-3. **Reconcile against existing workflows** — run [find-existing-workflow](#sub-procedure-find-existing-workflow).
+4. **Reconcile against existing workflows** — run [find-existing-workflow](#sub-procedure-find-existing-workflow).
    If the process is already covered, **stop and hand to refine (or extend the existing flow) on
    confirmation** — do not author a redundant workflow. Only the "no real match" / "add-new" branch
    proceeds to author below.
-4. **Author the YAML** — use the **real schema shape** for the chosen mode
+5. **Author the YAML** — use the **real schema shape** for the chosen mode
    ([authoring-workflows.md → Per-mode shapes](authoring-workflows.md#per-mode-shapes)). Set `name`,
    `description` (the WHY), the initial + terminal states/nodes, the steps with their actions, the
    transitions/edges with guards/conditions in the right declaration order, `iterationBound` for any
    loop, `env.allow` for any `${env.X}`, and a quoted `$schema`. For transition-flow, set
    `kind: transition-flow`.
-5. **Place the file** — default `.spur/workflows/<name>.yaml` (a `--file` arg overrides), named for
+   Keep each node inside the simplicity budget
+   ([workflow-fit-and-tuning.md](workflow-fit-and-tuning.md#3-node-simplicity-budget)): `shell`
+   commands at or under 5 non-comment units, `agent.run` inputs referencing a slash command rather
+   than carrying a raw prompt, guards a single predicate.
+6. **Place the file** — default `.spur/workflows/<name>.yaml` (a `--file` arg overrides), named for
    what the workflow does.
-6. **Verify** — run the [validate-and-dry-run core](#sub-procedure-validate-and-dry-run) with the
+7. **Verify** — run the [validate-and-dry-run core](#sub-procedure-validate-and-dry-run) with the
    expected terminal state. Not done until the definition validates AND the dry-run reaches it.
 
 Output contract: YAML workflow content + chosen mode + reason + destination path + validate result +
@@ -197,6 +206,12 @@ Adjust an existing workflow with the smallest change that meets the intent. Proc
    - missing step → add a state/node + its transition/edge in the correct declaration order
    - runaway loop → set or raise `iterationBound`
    - missing variable/env → add to `vars` or `env.allow`
+   - too slow / unreadable trace (not a correctness bug) → the
+     [optimize procedure](workflow-fit-and-tuning.md#optimize--refine-an-accepted-workflow-in-place),
+     backed by a before/after `spur workflow trace <run-id> --json` pair
+   - the whole file is the wrong surface (all nodes raw `agent.run`, no branching, edited more than
+     run) → not a refine: the
+     [demote procedure](workflow-fit-and-tuning.md#demote--workflow--descriptive-procedure)
    See [authoring-workflows.md](authoring-workflows.md) for each mechanism's real shape. **Do not
    switch mode** in a refine — a mode change is a rewrite; hand it back to `add`.
 3. **Apply the smallest change.** Preserve declaration order semantics (the first passing