---
name: butlers-redesign-prompt
description: Orchestrate a UX redesign of a Butlers dashboard page (or sub-page set) using /project-direction as the spec+beads engine, with redesign-specific upfront phases for vision capture, asset ingestion, impact analysis, backend-contract derivation, LLM-cost feasibility, manifesto/identity preservation, and a th-design design-bar audit. The binding design language is the Dispatch spec (openspec/specs/dashboard-design-language/spec.md); bundles live under pr/overview/ and resolve via references/bundle-registry.md. Use when asked to redesign a dashboard page, with or without a Claude Design bundle. Triggers on "redesign the X page", "plan the Y redesign", "integrate the redesign bundle", "what would it take to ship the SLUG redesign", "design language integration for AREA".
---

# Butlers Redesign Orchestrator

Plan the integration of a Claude Design redesign bundle into the live Butlers stack. This skill is a thin orchestrator that captures user vision, runs four redesign-specific phases via independent subagents, synthesises a brief, and then hands the brief to `/project-direction` so its existing Phase 1–3 (+ R1–R4+ reconciliation) machinery does the spec and beads work. The reason this skill exists is that `/project-direction` is generic; a Butlers redesign has a fixed input (a bundle under `pr/overview/`, or bundle-less origination from the Dispatch spec), a fixed risk profile (LLM cost blowouts, manifesto drift, vision loss in mechanical porting), and a fixed output shape that benefit from pre-baked scaffolding.

Two artifacts bind every run: the **Dispatch design language spec**
(`openspec/specs/dashboard-design-language/spec.md`) is the project design system, and the
**`/th-design` design bar** supplies the generic UX quality bar wherever the spec is silent.
Where they conflict, the spec wins — this is exactly th-design's own "project design system
overrides biases" rule.

## Hard Rules

1. **Vision is the source of truth.** Section 0 of the brief — "Design intent" — is binding. Every spec section, every component decision, every backend contract must trace back to it. Phase D treats violations of intent as automatic red regardless of cost math.
2. **Specifications are the source of truth for behaviour.** Once Section 0 is locked, every work item must link to a spec section. `/project-direction` enforces this — do not bypass it.
3. **No coding during this skill.** Output is vision capture, briefs, and beads only. Implementation is owned by `/beads-coordinator` later.
4. **Flag infeasible features early.** If an LLM-driven affordance would blow the token budget at expected user volume, surface it during Phase D — not during Phase 2 of `/project-direction`, and not during implementation.
5. **One subagent per phase.** Use independent subagents for Phases A–D so each gets a clean context window and the orchestrator window stays small. Pass each subagent the slug, the relevant paths, the brief's Section 0 (when applicable), and the phase's reference file from `references/`.
6. **Doctrine before details.** Read `about/heart-and-soul/` (or invoke the `heart-and-soul` skill) before declaring any feature acceptable — manifesto/identity drift is the failure mode that most often forces a redesign-of-a-redesign.
7. **The design bar is `/th-design`; the design system is the Dispatch spec.** Design quality judgments (density, motion, accessibility, perceived speed, discoverability) defer to th-design's design-bar and subskills. The Dispatch spec (`openspec/specs/dashboard-design-language/spec.md`) overrides th-design's generic biases wherever it speaks; a proposal that violates the spec is rejected regardless of how well it scores on generic criteria. Changing the language itself means changing the spec first (via OpenSpec), never ad-hoc in a redesign.

## Argument shape

Single positional argument: **the redesign slug**. Examples: `ingestion`, `qa`, `settings`, `butler-detail`.

Resolution source-of-truth: **`references/bundle-registry.md`** (skill-local). It maintains the canonical slug-to-folder map and the bundle contract. Read it first.

Resolution rules (in order, first match wins):

1. **Slug map hit** in `references/bundle-registry.md` — use that folder.
2. **Canonical match** `pr/overview/SLUG-redesign/`.
3. **Bare match** `pr/overview/SLUG/`.
4. **Fuzzy match** — any `pr/overview/` folder containing `SLUG`. Require user confirmation before proceeding.
5. **No bundle** — a legitimate mode, not an error. Most shipped pages have no bundle (they graduated). Originate from the Dispatch spec (`openspec/specs/dashboard-design-language/spec.md`) + `references/dispatch-kit/` + the live pages, and treat those as the bundle. Run the UI-maturity QC sweep first (`/butler-relentless-jarvis-pursuit` → `subskills/ui-maturity-audit/SKILL.md`) — it often reverses the framing (a page may already be real underneath, with the actual gaps in IA or unsurfaced endpoints).

**Toolkit refusal.** If the registry marks the resolved target as `System (refuse)` (e.g. `dispatch-kit/`), stop and tell the user: "This is a design system / portable toolkit, not a redesign of a specific page. The skill cannot process it. Pick a redesign slug instead." Do not run any phase.

**Optional override.** A user may pass `--bundle=PATH` to bypass the slug resolver entirely (for unlisted or in-flight bundles).

## Workflow

The skill runs in two acts:

- **Act 1 (Phases 0 → 0.5 → A → B → C → D)** — vision capture + four redesign-specific phases, each via its own subagent. Output is a synthesised **redesign brief** doc.
- **Act 2 (Phases E → F → G → H)** — synthesise the brief, hand it to `/project-direction`, post-process the resulting beads graph, deliver a final handoff message.

### Phase 0 — Resolve, gate, detect prior runs

Before anything else:

1. **Resolve the slug** per the rules above. State the resolved path back to the user in one line. If toolkit-refused, stop.
2. **Tolerate file variants.** Check the bundle for these files (in this order):
   - Handoff: `IMPLEMENTATION.md` **or** `PLAN.md` (either is acceptable).
   - Recipe TL;DR: `*_HANDOFF.md` (preferred, optional).
   - Design language delta: `DESIGN_LANGUAGE.md` (optional). The Dispatch spec is always binding; a bundle DL is a delta against it. Warn if the bundle DL contradicts the spec.
   - Vision: `VISION.md` (optional; controls Phase 0.5 behaviour).
3. **Read handoff headers only** — first 30 lines of `IMPLEMENTATION.md` / `PLAN.md` / `*_HANDOFF.md`. Confirm sub-page count and route map. Do not load full bodies into the orchestrator window — that is Phase A's job.
4. **Detect prior runs.** Check for:
   - Prior brief: `ls docs/redesigns/*-SLUG-brief*.md` (any version).
   - Prior beads epics: `bd list --json | jq '.[] | select(.title | test("SLUG redesign"; "i"))'`.
5. **If prior found**, ask the user via `AskUserQuestion`:
   - `fresh` — ignore prior artifacts; create new brief at `-vN+1` and new epics.
   - `diff` — generate `-vN+1` brief that explicitly diffs against the prior brief and only re-runs phases whose inputs changed.
   - `amend` — edit the prior brief in place and update existing beads.
   Default to `fresh` if no prior found.
6. **Confirm scope.** State back to the user: resolved path, mode, target brief filename, and any warnings (missing `DESIGN_LANGUAGE.md`, sparse intent, etc.). Do not proceed without acknowledgement.

### Phase 0.5 — Vision capture

Goal: capture the WHY behind the design before any mechanical analysis runs. This is what makes the skill a vision-to-implementation bridge instead of a port-and-pray tool.

1. **If `BUNDLE/VISION.md` exists**, read it. Use its content as the draft of Section 0. Confirm with the user that it is current ("Should I use this verbatim, or do you want to refine any of the bullets?").
2. **Otherwise**, prompt the user via `AskUserQuestion` with these five questions, one at a time:
   - **Problem being solved** — "What's wrong with the current `/SLUG` page; what specific user pain does this redesign address?"
   - **Primary audience** — "Who is this for in v1? (owner / team / operator / external user). If multiple, who ranks highest?"
   - **Deliberate design moves** — "Name the 2–5 specific choices that define the redesign, with the reason you made each during the Claude Design session."
   - **Things deliberately rejected** — "What did Claude Design and you explicitly choose NOT to do? Why? The implementation must resist these temptations."
   - **Success criteria** — "What user-observable behaviours will tell you the integration worked? (Not 'tests pass' — 'owner can do X in N seconds' style.)"
3. **Write Section 0 to the in-memory brief draft.** It becomes Phase D's intent gate input.
4. **Offer to persist back to `BUNDLE/VISION.md`** if it didn't already exist. Storing it in the bundle lets the next iteration skip Phase 0.5.

This phase is the most important difference between this skill and a generic `/project-direction` invocation. Do not skip it.

### Phase A — Input gathering (subagent)

Goal: produce an asset inventory + sub-page enumeration + design-token extraction.

Read `references/input-gathering.md`. Dispatch with `subagent_type: Explore`. Pass it the bundle path. Output: sub-pages, components, design tokens, open questions.

### Phase B — Impact analysis (subagent)

Goal: classify every component as `reuse / adapt / new / replace`, locate the current implementation, flag stack changes, and **emit a `## Butlers touched` table** that Phase D will use to scope its manifesto pass.

Read `references/impact-analysis.md`. Dispatch with `subagent_type: Explore`. Pass it Phase A's output. Output: current implementation map, component classification, stack delta, butlers touched, risks.

### Phase C — Backend-contract derivation (subagent)

Goal: derive the API contract each new affordance needs, reconcile against existing routers, and mark every row with its **evidence basis** (`live-endpoint / spec / fixture`). Fixture-only rows are automatically `unclear`.

Read `references/backend-contract.md`. Dispatch with `subagent_type: Explore`. Output: affordance inventory, API delta with evidence column, schema migration impact, proposed backend epic outline.

### Phase D — Butlers guardrails (subagent)

Goal: three passes in one subagent — (1) LLM-cost feasibility audit grounded in `references/llm-pricing.md` and the intent gate, (2) manifesto/identity preservation scoped to Phase B's `## Butlers touched` table, (3) **design-bar audit**: load the th-design design-bar subskill (`~/.claude/skills/th-design/subskills/design-bar/SKILL.md`) and run its UX walkthrough (entry, first glance, pace, repetition, defaults, recovery, habit) against each proposed flow — specs and mockups are reviewable exactly like built UI. The Dispatch spec (`openspec/specs/dashboard-design-language/spec.md`) is the project design system: check the proposal against its Page Conformance requirement, and let it override generic biases on conflict. Every finding cites the violated spec requirement or design-bar bias.

Read `references/butlers-guardrails.md`. Dispatch with `subagent_type: general-purpose` (needs to read manifestos, the spec, the design-bar subskill, and reason about cost). Pass it **Section 0 of the brief draft** plus Phases A–C reports. Output: cost findings table, manifesto findings table, design-bar findings table, intent-compliance check, Phase D verdict.

### Phase E — Synthesise the brief

1. Determine the target filename:
   - Base: `docs/redesigns/YYYY-MM-DD-SLUG-brief.md`.
   - If a brief already exists at that path (same-day collision) or prior versions exist, append `-vN` where N = next integer.
2. **Copy** `assets/brief-template.md` to the target path. Do not re-type the template — `cp` it, then `sed`-substitute placeholders (`SLUG`, `YYYY-MM-DD`, `RESOLVED_BUNDLE_PATH`, `PATH_OR_NONE`, version, mode).
3. **Fill the body** by quoting structured tables verbatim from the four subagent reports. Do not paraphrase. Phase 0.5's Section 0 goes in first.
4. **Pause and let the user read the brief.** If they request changes, re-run the relevant phase's subagent with their feedback appended; do not edit the brief in place without re-running.

### Phase F — Hand off to `/project-direction`

Invoke `/project-direction` with **feature evaluation focus**, using this concrete invocation pattern:

```
/project-direction --focus=feature \
  --brief=docs/redesigns/YYYY-MM-DD-SLUG-brief.md \
  --bundle=RESOLVED_BUNDLE_PATH \
  --binding-design-language=openspec/specs/dashboard-design-language/spec.md \
  --binding-design-intent=docs/redesigns/YYYY-MM-DD-SLUG-brief.md#0-design-intent \
  --red-flag-policy=descope-or-escalate
```

Append `--bundle-design-language-delta=RESOLVED_BUNDLE_PATH/DESIGN_LANGUAGE.md` only when the bundle carries a DL delta. If `/project-direction` does not accept these flags literally, paste the equivalent paragraph but **list every binding artifact path** so its Phase 1 doctrine reconciliation can cite them.

Capture the OpenSpec changeset path that `/project-direction` Phase 2 (`/opsx:ff`) emits — Phase H needs it.

### Phase G — Split out backend epic (with existing-work detection)

After `/project-direction` Phase 3 produces the beads graph, post-process:

1. **Detect existing epics.** Query `bd list --json` for any open epic whose title contains `SLUG redesign — backend contracts` (or its frontend sibling). If found and mode is `amend`, update the existing epics in place. If found and mode is `fresh`, ask the user before creating duplicates.
2. Identify every bead whose work is entirely backend (new API contract, schema migration, butler/api router change) by cross-referencing against the Phase C delta.
3. Create (or amend) the **backend epic** titled `SLUG redesign — backend contracts` and re-parent the backend beads under it.
4. Wire `blocked-by` from the frontend epic to the backend epic so the frontend cannot start before backend contracts land.
5. Add `discovered-from` links from each backend bead to the brief doc path.
6. Verify Phase D red verdicts: every red-verdict feature in the brief must either be missing from the bead graph or carry a `descope-decision-link` annotation pointing to where the user de-scoped it. Flag any leak as a bead-graph error before Phase H.

### Phase H — Final handoff message

End the orchestrator with a fixed message giving the user every artifact path and the literal next command. Template:

```
✓ Redesign plan ready for SLUG.

Brief:               docs/redesigns/YYYY-MM-DD-SLUG-brief.md (vN)
Vision (Section 0):  <persisted to BUNDLE/VISION.md? yes/no>
OpenSpec changeset:  openspec/changes/<change-id>/  (created by /project-direction Phase 2)
Frontend epic:       <bd-id>  (N beads)
Backend epic:        <bd-id>  (M beads, blocks frontend epic)

Red-flag verification:
  - <K> red verdicts in Phase D
  - All <K> have de-scope decisions linked in the bead graph ✓ / ✗

Next:
  /beads-coordinator    # start parallel worker dispatch on the two epics
```

Do not run `/beads-coordinator`. The skill's contract is planning + handoff, not execution.

## Reference and asset files

| Path | Type | When to read | Purpose |
|------|------|--------------|---------|
| `references/input-gathering.md` | reference | Phase A | Subagent prompt for asset ingestion + sub-page enumeration + design-token extraction. |
| `references/impact-analysis.md` | reference | Phase B | Subagent prompt for current-state baseline + per-component classification + stack delta + `## Butlers touched` table. |
| `references/backend-contract.md` | reference | Phase C | Subagent prompt for deriving API contracts with `evidence` column. Fixture-only rows → `unclear`. |
| `references/butlers-guardrails.md` | reference | Phase D | Three-pass subagent prompt: LLM-cost feasibility (intent gate + pricing-grounded) + manifesto/identity preservation (scoped via Phase B) + th-design design-bar audit against the Dispatch spec. |
| `references/llm-pricing.md` | reference | Phase D | Per-MTok rate table, cadence reference, sanity-default per-affordance rows, verdict thresholds. Re-verified date inside. |
| `references/bundle-registry.md` | reference | Phase 0 | Slug-to-folder map + bundle contract + VISION.md authoring guide. Skill source-of-truth for resolution + toolkit refusal. |
| `references/dispatch-kit/` | reference | Phases A–E, bundle-less mode | Dispatch execution kit: JSX patterns, page recipes, paste-ready tokens, 12-item pre-merge checklist. |
| `assets/brief-template.md` | asset | Phase E | Raw markdown template. `cp` to `docs/redesigns/YYYY-MM-DD-SLUG-brief[-vN].md` and substitute placeholders. **Never load into context; copy to disk.** |
| `openspec/specs/dashboard-design-language/spec.md` (repo-level) | external | All phases | The Dispatch spec — the binding design language and project design system. Overrides generic design biases. |
| `~/.claude/skills/th-design/subskills/design-bar/SKILL.md` (global) | external | Phase D | Generic design quality bar: default biases, UX walkthrough, definition of done. Applies wherever the Dispatch spec is silent. |

## Common failure modes

- **Skipping Phase 0.5.** The mechanical phases will produce a competent port plan with the vision lost. Section 0 is the spine of every downstream phase.
- **Skipping Phase D's cost audit.** Easy because the design looks delightful and cost only appears at the token-counting step. The brief is the right place to surface a $50/user/day feature — not a post-launch incident.
- **Judging design quality ad-hoc instead of via the bar.** Without the design-bar pass, phases optimize for faithful porting and miss UX defects the mock itself carries (dead waits, undiscoverable features, unwalkable flows). Findings must cite a Dispatch spec requirement or a design-bar bias — "looks good to me" is not a verdict.
- **Letting `/project-direction` re-derive Phase A.** Pass the brief in so the spec phase grounds in it. Otherwise R1–R4+ reconciliation passes rediscover sub-pages.
- **Merging frontend and backend beads into one epic.** Backend contracts have different worker pools and dependencies; keep them separate so `/beads-coordinator` can dispatch in parallel.
- **Trusting `data.jsx` fixtures.** Phase C's evidence column is the guardrail. Fixture-only rows must go to `unclear` and resolve before spec phase.
- **Treating the brief as final.** It is the input to `/project-direction`, not the spec. Specs live in `openspec/`; the brief primes the spec phase.
- **Re-running without `--mode`.** Phase 0's iteration detection catches this — don't skip it, or you will silently overwrite a previous run's brief and duplicate beads epics.