optimizexp

# OptimizeXP Run **multi-objective experience optimization** across **UX**, **DX**, and **AX**: 1. **Regime `harm_reduce`:** measure **and fix** **harms**, **friction**, **uncertainty** (lower better) until a **harm floor** (metrics-zero **or** irreducible residual with no S/M left). 2. **Regime `delight_maximize` (default next):** score **excitement**, **ease-of-use**, **perceived optimality** (higher better) **while still measuring harm and cognitive load** — reject any experiment that increases harm or breaches persona **cognitive thresholds** (feature sprawl, clutter, choice overload, …). Continue until **Pareto equilibrium** (no free lunch on the frontier / inverted-U peak). See `references/equilibrium.md`. 3. **Survey + backlog:** personas (with formal **KYC-lite demographic + psychographic** models) answer a pseudo survey → **pseudo feature requests** → ranked **experiment backlog**. **Default infinite does not terminate at the harm floor.** Only `--no-delight` / `--harm-only` opts into that early exit. Each review pass **must apply an experiment** (smallest safe change), re-score with evidence — not report-only by default. Scores are **falsifiable, not vibes**: `evidenceRefs` must point at files that exist, optional `evidenceChecks` rubric entries (exitCode / transcript assertions against captured `meta.json`) are programmatically enforced, and an iteration `scores.json` copied from `baseline.json` fails validation without an explicit `justification` (see `references/metric-scorecard.md`). Uses: - **Global** personas/features under repo-root **`.optimizexp/`** (cross-cutting) - **Project-local** personas/features under **`<project>/.optimizexp/`** (e.g. `site/.optimizexp/`) - Schema v2 personas with formal **`experiences: [ux, dx, and/or ax]`** binding, plus segments/demographics/psychographics/cognitive thresholds - Persona **feature folders** with Gherkin + evidence - Write-ahead **agent bus** + dual-regime loop until **pareto-equilibrium** (bus/runs stay **global**) - **Mandatory experiments** each pass unless `--report-only` - **`--passes` infinite** until equilibrium (finite N caps harm cycles only) - **Delight regime** after harm floor (`--delight-passes`; `--no-delight` to skip) - **Persona survey + experiment backlog** (default on) - Bus feedback after pass 1; optional **PR delivery** ## First moves 1. **Bare invocation (no flags):** treat as **all experiences** (`ux` + `dx` + `ax`) and **all projects**. First check whether init is needed: ```bash node --import tsx .agents/skills/optimizexp/harness/init.mts --mode needs-init # exit 0 → needs init; exit 1 → already bootstrapped enough to review ``` If `needsInit: true`, run full init (`harness/init.mts`, all experiences, **all projects**), then **continue** into the review loop with all experiences + all projects. If false, skip init and review immediately. Details: `references/init.md` § Auto-init on bare run. 2. Resolve **project flags** (default **all-projects**). List ids: `init.mts --mode list-projects`. Resolve **experience flags** (default **`ux`, `dx`, `ax`**). 3. If **`--init` only:** run repo bootstrap (respect `--projects` if set); **stop** unless user also asked to review. 4. If **`--persona` …** present: rewrite each seed → formal persona file under the correct **scope** (`references/personas.md`): single non-root `--project` → `<project>/.optimizexp/personas/`; otherwise **global** `.optimizexp/personas/`. Never use the raw seed as the review system prompt. 5. Resolve **persona set** for the run (same set drives feature fan-out) by merging **global + selected project** scopes (project-local shadows global on same id): - `--personas` list if set, else - personas generated this run if any, else - project `personas.defaultPanel` panel list if configured (e.g. Community Web `community-competitive`), else - all personas intersecting experiences. When competitive coverage applies (project `competitive.scorecard` or Community Web features), load `references/competitive-coverage.md` and keep dimension owners in the panel. 6. **Doctor (preflight):** audit structure, personas, feature quality, maps; repair safely; optional snapshot. **Standing approval:** invoking OptimizeXP authorizes its safe, in-scope preflight repairs; apply them without asking again. This does not authorize destructive, networked, secret-bearing, or unrelated changes. ```bash node --import tsx .agents/skills/optimizexp/harness/doctor.mts check --project <id> node --import tsx .agents/skills/optimizexp/harness/doctor.mts repair --project <id> node --import tsx .agents/skills/optimizexp/harness/doctor.mts snapshot --project <id> ``` See `references/doctor.md`. Doctor exit 0 ≠ optimizexp complete. 7. **CRITICAL — Explore + feature generation (quality bottleneck):** ```bash # a) Surface map + experience catalog (default entry, help, interactive, persona stacks) node --import tsx .agents/skills/optimizexp/harness/explore-app.mts --project <id> --personas … # b) Plan EXPERIENCE.md (rubber-duck + adversarial) then scaffold — see feature-quality.md node --import tsx .agents/skills/optimizexp/harness/generate-feature.mts --mode plan --id … --experience-id cold-start-tty-chat --project <id> # fill EXPERIENCE.md → accept + [x] adversarial boxes node --import tsx .agents/skills/optimizexp/harness/generate-feature.mts --mode rubberduck-check --id … node --import tsx .agents/skills/optimizexp/harness/generate-feature.mts --mode from-catalog --project <id> --personas … node --import tsx .agents/skills/optimizexp/harness/generate-feature.mts --mode validate --id … ``` **Illegal:** score a surface without an accepted feature for that experience. **Illegal:** template-only Gherkin (`When I exercise the surface…` alone). **Illegal:** skip **default entry / chat** when surface-map says interactive. 8. If **`--feature` …** present: still require EXPERIENCE.md rubberduck-check before treating the feature as reviewable (`references/features.md` + `feature-quality.md`). 9. Read global `.optimizexp/README.md` plus each selected project’s `.optimizexp/` when present. 10. Resolve **`--passes`** / `passes` (default **infinite**). See `references/flags.md` § Passes (outer cycles). 11. Load progressive-disclosure references below (only what you need) — **always** load `feature-quality.md` when generating or validating features; load `doctor.md` for preflight. 12. **Open/create a run first** (before product edits): ```bash node --import tsx .agents/skills/optimizexp/workflows/cross-agent/review-loop.mts \ --mode init --run <runId> --experiences … --personas … --features … --projects … ``` Confirm `status: running`, `stopPolicy: infinite-until-pareto-equilibrium` (unless `--no-delight`), and `INCOMPLETE.md`. Resume matching incomplete runs instead of starting a fake-complete story. 13. Execute the **review loop** (`references/review-loop.md` + `equilibrium.md`): every act uses **harness capture-evidence** (stamped meta); harm_reduce → delight → **assert-complete** → **mark-complete**. 14. Personas must be judged with **cognitive thresholds** and (for new/rewritten files) **v2 KYC models** (`persona-models.md`, `cognitive-thresholds.md`). 15. **Survey + backlog** on harm floor entry and at closeout (`persona-survey.md`, `experiment-backlog.md`). Competitive runs also answer parity/dealbreaker questions and write `competitive-scorecard.json` (`competitive-coverage.md`). 16. **Closeout (required):** write `summary.md` with `stopReason` → `assert-complete` (exit 0) → `mark-complete --stop-reason …`. Paste assert JSON in the user report. assert-complete now fails on missing surface-map, template-only features, unstamped evidence, P0 coverage gaps. Artifact-truth gates also block completion: `scorecard_artifact_missing` / `dimension_empty_evidence:<id>` / `dimension_evidence_missing:<id>:<path>` / `dimension_not_rescored:<id>` (products with `requireScorecardOnComplete`), `council_verdict_missing:<id>` (dimension status upgrades need `runs/<id>/design-council.md`), `backlog_malformed:<file>:<id>` (backlog integrity — no missing fields, no literal "undefined"), `standing_defect_open:<id>` (open P0/P1 in `.optimizexp/defects.json` for a touched product), `token_audit_missing` / `token_audit_failing:<rule>` (web products need a passing `npm run design:audit`), and `mobile_evidence_missing` (mutating UX runs on web products need one capture with viewport ≤ 480px). 17. When opening PRs: incremental commits + stacked PR + **post-pr-evidence** (`references/pr-delivery.md`). ## Flags Full grammar: `references/flags.md`. | Form | Meaning | |---|---| | **(none)** | **Auto needs-init** → init if needed → **review all experiences + all projects** | | **`--init`** | Bootstrap only (unless user also requested review): product personas + features | | **`--projects all`** / **`--all-projects`** | Evaluate every discovered project (**default** when omitted) | | **`--project <id>`** / **`--projects a,b`** | Limit init/review to named projects (`list-projects` for ids) | | `--ux` / `--dx` / `--ax` | Include only the listed experiences | | `--only ux,dx` | Include only listed | | `--exclude ax` / `--no-ax` | Drop listed from the default set | | bare `ux` `dx` after skill name | Same as `--only` | | **`--persona "seed"`** | Seed → formal `personas/<id>.md` | | `--personas id1,id2` | Select existing persona ids (**exclusive** when set) | | `--max-personas N` | Cap persona count | | **`--feature "seed"`** | Journey seed → feature folder + **per-persona** `.feature` files | | `--feature-id` / `--feature-file` / `--driver` | Feature id, seed file, capture driver | | `--features id1,id2` | Select existing feature folders for the run | | **`--passes infinite`** / `passes: infinite` | Default. Continue **harm → delight** until **pareto-equilibrium**. | | **`--passes N`** / `passes: N` | Cap **harm_reduce** cycles; still enter delight unless `--no-delight`. | | **`--delight-passes infinite\|N`** | Cap delight regime (default **infinite** until equilibrium). | | **`--no-delight`** / **`--harm-only`** | Stop after harm floor (opt out of equilibrium). | | **`--no-survey`** | Skip persona survey + survey-driven backlog. | | **`--report-only`** / **`--no-reduce`** | Measure only; no apply | **Feature × persona:** no persona flags → generate Gherkin for **all** personas in the resolved set. With `--personas` / `--persona` → only those. Echo `generatedPersonas` + `generatedFeatures` before reviewing. **Stop policy:** harm true plateau only **switches** to delight. Default infinite ends at **`pareto-equilibrium`** (or inverted-U peak / delight ceiling / caps / user / safety / blocked). Survey + backlog by default. No `--iterations` budget. ## Progressive disclosure Use the [reference index](references/index.md) to route to the minimum context needed. ### Always - `references/init.md` — **`--init`** and **bare auto needs-init** - `references/metrics.md` — harm metrics + HCD - `references/positive-metrics.md` — delight metrics - `references/cognitive-thresholds.md` — load channels + thresholds - `references/equilibrium.md` — Pareto / inverted-U stop policy - `references/persona-models.md` — KYC demographic/psychographic models - `references/persona-survey.md` — survey + feature requests - `references/competitive-coverage.md` — competitor gap scorecards, panels, currency (when product has a scorecard) - `references/experiment-backlog.md` — ranked uplift backlog - `references/metric-scorecard.md` — formal scores (+ positive, cognitive) - `references/agent-bus.md` — write-ahead bus - `references/review-loop.md` — dual-regime orchestration - `references/personas.md` — persona file contract - `references/config.md` — **global + project `config.json`** - `references/features.md` — feature folder + Gherkin layout - **`references/feature-quality.md`** — **critical path:** catalog, rubber-duck, adversarial, quality bar - `references/app-exploration.md` — surface-map probes feeding the catalog - **`references/doctor.md`** — doctor check / repair / snapshot preflight - `references/evidence.md` — capture policy, overwrite, media preference - `references/interface-patterns.md` — formal API, TUI, and web/mobile/desktop GUI standards + evidence forms - `references/harness.md` — test harness CLI + drivers - `references/workflow-generation.md` — host workflows