uplift

What this skill does

# stardust:uplift

One entry point. One URL. Three presales-quality redesign variants.

`uplift` collapses the `extract → direct → prototype × 3` chain into a
single opinionated command that picks every variability axis from the
captured brand surface rather than asking the user. The output is the
same as the long-form chain (state.json, brand-review.html, three
proposed files, motion validation) — the user just doesn't have to
coordinate it.

## Opinionated defaults

- **Single-page extract** — the homepage by default (the brand
  owner's first surface) unless `--page <slug>` overrides.
- **Brand-faithful Mode A** — palette + typography pinned. No
  invented colors, no fonts outside the captured surface.
- **Three variants, fixed role contract** — A is the green-light,
  B is the design-team motivator, C is the visionary cinematic
  pitch.
- **Cinematic register auto-picked** — C's motion register is
  selected from the captured PRODUCT.md Brand Personality per
  `../prototype/reference/motion-registers.md` § Selection
  heuristic.
- **"What if..." candidates from a closed catalog** — B and C
  each pick one captured-but-underused trait from
  `reference/what-if-candidates.md`. Different traits per variant.
- **Validation cascade runs** — every gate in
  `prototype/SKILL.md` Phases 2.5–2.8 fires, including cinematic
  Pass 6 for variant C.

## Inputs

- `<URL>` — required. The page to redesign. Defaults to homepage when
  the URL has no path (`https://example.com/` → home).
- `--page <slug>` — optional. Override the slug if the URL points
  elsewhere or the user wants a different surface.
- `--cinematic-register <name>` — optional. Override the auto-picked
  register for variant C. One of `arrival`, `kinetic-display`,
  `live-systems`, `editorial`, `kinetic-grid`. Recorded as
  `registerSource: "user-override"` in C's provenance.
- `--two-variants` — optional. Render only A and C (skip B). Useful
  when the brand surface is thin and a forced three-way differentiation
  would produce a weak middle (per the stop condition below).

There are no other flags. Everything else is derived from the
captured brand surface or governed by the underlying skills'
contracts.

## Setup

1. Run the master skill's setup
   (`../stardust/SKILL.md` § Setup): impeccable dep check, context
   loader, state read.
2. Verify Playwright is available (`extract` will fail without it —
   surface the same install message extract would).
3. Read `stardust/state.json` if present. If a previous `uplift`
   ran against the same URL on a recent date, ask whether the user
   wants to refresh the extraction or render against the existing
   capture.

## Procedure

Six phases. Phases 1, 4, 5 delegate to existing skills; phases 2,
3, 6 are owned by `uplift`.

### Phase 1 — Extract (delegate to `stardust:extract`)

Invoke `stardust:extract <URL> --single` (single-page mode).
Extract owns:

- Live Playwright render with the standard wait recipe.
- `stardust/current/_brand-extraction.json` (palette + type + motifs
  + voice + system components + photography).
- `stardust/current/pages/home.json` (full per-page capture).
- `stardust/current/brand-review.html` with the tensions detectors
  applied — this is the load-bearing input for Phase 2.
- `stardust/current/PRODUCT.md` and `DESIGN.md` (descriptive — the
  current state, not the target).

`uplift` does not crawl beyond one page. The brand surface from a
single homepage is sufficient for three variants; multi-page extract
is what `stardust:extract` (without `--single`) is for.

### Phase 2 — Tension and trait identification (owned by `uplift`)

Read `stardust/current/brand-review.html` § Tensions surfaced and
`_brand-extraction.json`. Produce two artifacts:

#### 2a — `stardust/uplift-improvements.md`

Five specific weaknesses observed in the captured site. Same
load-bearing contract as the existing presales workflow: without
specifics, "make it better" has no claim. Categories:

- Dated patterns the design world has moved past (be specific:
  "centered hero with stock photo + double CTA in primary blue
  reads as the SaaS template circa 2019")
- Cluttered IA / unclear hierarchy / weak CTAs / redundant sections
- Contrast failures, accessibility gaps, density issues
- Cliché conventions the brand could move past while staying
  recognisably itself
- Missed opportunities the captured surface doesn't capitalise on
  ("captured photography is excellent but the layout crops it to
  thumbnail-size")

Refuse to proceed if fewer than 3 specific weaknesses can be named
(see § Stop conditions).

Format (mirrors the provenance shape used by the rest of stardust):

```markdown
---
_provenance:
  writtenBy: stardust:uplift
  writtenAt: <ISO-8601>
  againstInput: <URL>
  readArtifacts:
    - stardust/current/_brand-extraction.json
    - stardust/current/pages/<slug>.json
    - stardust/current/brand-review.html
---

# Improvements — <URL>

1. **[dated-pattern]** <one-line headline> — <captured evidence>.
2. **[ia-clutter]** <one-line headline> — <captured evidence>.
3. **[contrast-or-density]** <one-line headline> — <captured evidence>.
4. **[cliché]** <one-line headline> — <captured evidence>.
5. **[missed-opportunity]** <one-line headline> — <captured evidence>.
```

The bracketed tag preceding each weakness is the category from the
list above. The headline is the one-sentence summary the agent will
restate when variant A's shape brief applies the fix.

#### 2b — `stardust/uplift-questions.md`

Six to eight "what if we leaned into…" candidates derived from the
captured brand surface. Each candidate cites the captured evidence
that makes it concrete. Candidates are picked from the closed
catalog in `reference/what-if-candidates.md`:

1. Display-typography amplification
2. Photography re-foregrounding
3. Live-data promotion
4. Signature-gesture extension
5. Voice-register pivot
6. Color-ladder re-weighting
7. Audience-routing reframe
8. Motif vocabulary swap

For each candidate the agent generates: a one-line "what if…"
phrasing, the captured evidence that makes the candidate concrete,
the variant role it best serves (B's composition bet vs C's
cinematic bet), and whether the candidate is **disqualified** for
this brand (e.g. "Photography re-foregrounding disqualified — the
captured photography is generic stock; amplifying it would expose
the weakness").

The disqualification step is what keeps the agent from reflexively
picking the same candidate for every brand.

### Phase 3 — Pick three variant directions (owned by `uplift`)

Default: three variants (A + B + C). When `--two-variants` is
active, skip § 3c (B's candidate selection) and the direction.md
authored in § 3d declares only A + C. Phase 4 then writes only
`DESIGN-A` and `DESIGN-C` files at the project root, and Phase 5
renders accordingly. All downstream contracts (variant
differentiation, motion validation on C, summary in Phase 6)
operate over the reduced variant set without modification.

#### 3a — Pick the cinematic register for variant C

Read PRODUCT.md Brand Personality (from `stardust/current/PRODUCT.md`)
and apply the heuristic in `../prototype/reference/motion-registers.md`
§ Selection heuristic. Record the picked register + the one-line
rationale.

#### 3b — Pick C's "what if" candidate

The candidate must be the one the picked register **naturally
amplifies through motion**:

| Picked register | Natural candidate |
|---|---|
| `arrival` | Signature-gesture extension OR Photography re-foregrounding |
| `kinetic-display` | Display-typography amplification |
| `live-systems` | Live-data promotion |
| `editorial` | Photography re-foregrounding OR Voice-register pivot |
| `kinetic-grid` | Motif vocabulary swap |

#### 3c — Pick B's "what if" candidate

Pick from the remaining (non-disqualified, non-C) candidates in
`uplift-questions.md`. Prefer:

1. A candidate that addresses a tension surfaced in
   `brand-review.html` § Tensions.
2. A candidate whose visual move is **composition