Repository navigation
feat(prototype): make the HTML mockup explore-directions' default host #8776
Description
Part of #8773
Problem
/prototype:explore-directions builds variants on the real stack by default. Its intent selector marks sub-shape A (variants mounted inside an existing page behind ?variant=) as the default (plugins/prototype/skills/explore-directions/SKILL.md:75) and picks the self-contained HTML mockup only when there is no page to host it and "speed matters more than realism" (:77). The description says it "Runs on the real stack by default or as a self-contained HTML mockup" (:2).
The proposal: make the self-contained HTML mockup the default decision surface, including for developers, because any decider (developer, product owner, designer, or several) can open a file:// page with nothing running, and it needs no dev server. The real stack stays as an explicit override and as the place the winner is folded in.
Evidence
Verified on origin/main 31eafaa (prototype 0.14.0) with git show. The item cited "Prefer A" wording from 0.13.11; 0.14.0 replaced it with the intent-selector table but kept sub-shape A as the default.
The current default is deliberate. The skill argues for realism: "a parcel card that looks roomy on a bare route can push the order summary off screen on the real /shipments, with its header, its filters and forty parcels in transit" (:80-84), and "B costs a running app and buys a judgment made inside it; the mockup gives up that realism for a page that opens with nothing running" (:86-88). The anti-patterns table also guards against live API writes from real-stack variants (:365), a risk the mockup removes.
Inferred: grounding the mockup in the existing product's look (#8429, plus its comment on token mapping) would recover much of the realism the current default buys, which weakens the argument for keeping sub-shape A as the default. That depends on #8429 landing.
Decision needed
- Flip the default to the HTML mockup (the source item's recommendation). Sub-shape A and B become explicit overrides ("on the real stack", "in the app") and the fold-in path for the winner. Recommended only together with explore-directions: HTML mockups of an existing app's feature should keep the app's look #8429, so a mockup of an existing app keeps the app's look.
- Keep sub-shape A as the default, and instead widen the mockup row's trigger to "a non-developer decides, or several people review". Smaller change; keeps the realism argument; leaves developers on the real stack.
- Ask once per run which host to use. Costs a question every run; rejected by the item as adding friction to the common case.
Proposed approach (for option 1)
SKILL.md: reorder the intent selector so the HTML mockup row is the default and sub-shape A/B rows are chosen on an explicit request for real-stack variants. Rewrite:80-88to say when the real stack is still worth its cost (layout sensitive to live data volume, existing page chrome that the mockup cannot reproduce). Update the description at:2and the Purpose paragraph at:42-45.- Keep the model auto-invoke gate unchanged (
context/discipline.md:17-21): "default" means the default host once the skill runs; it does not let the model start a prototype unasked. - Keep the CSP and no-remote-fetch rules (
SKILL.md:114-119) unchanged; this child adds a check that they hold. - Update
docs/native-surfaces/records.jsonrows whosereasonstates the real-stack default (for example:1941, which says "ours builds switchable throwaway layout variants on the real stack"). - Add or update evals in
plugins/prototype/skills/explore-directions/evals/evals.jsonfor the new default and the override.
Acceptance criteria
- Invoking the skill with no host override and no running dev server produces a single self-contained HTML file; real-stack variants appear only on an explicit request. (Source check 1.)
- The generated page carries the restrictive CSP meta tag and makes no network request when opened from
file://(verified in a browser network panel or a headless run). (Source check 2.) - With the model reaching for the skill unasked, the STOP-and-confirm gate still fires before any file is written.
- The description, Purpose, intent selector and native-surfaces rows agree on which host is the default.
- An eval case covers the default and one covers the real-stack override.
Constraints and gotchas
- "Default" already means two things: "The HTML mockup stays the default" (
SKILL.md:151,:279) is relative to the/designcanvas offer, while sub-shape A is the default host (:75). Keep them distinct in the rewrite. - The anti-pattern at
:365(stub every write) still applies to the real-stack override. explore-directionsis a grandfathered emitter under the rendered-views convention, held to "their shipped ladder andmediumonly" (docs/conventions/rendered-views/README.md:552-558, ADR 0025). Changing which medium it produces by default is a change to that ladder; check the convention's content-class rules and say in the PR whether the skill stays grandfathered or adopts the convention.prototypeuses changelog fragments (scripts/fragment-plugins.txt:74): add one under.changes/prototype/; noplugin.jsonbump.- A description change shifts the skill listing; check it against the listing budget work in perf(skills): trim skill descriptions until the listing fits, then lower skillListingBudgetFraction #6846.
- Coordinate with Concise skills rollout: prototype (2 skills, 2 model-invoked) #6589 (prototype skill rewrite).
Context
Source: local handoff item 2026-10-06-ui-mockup-review-mode.md, overlap 1 (replace the default) and overlap 3 (keep the auto-invoke gate). Related: #8429.
Activity
github-actions commentedon Oct 21, 2026
Proposed work class: work-class: structural
Basis: automated intake triage; the lanes App applied this class.
Size: Medium
Complexity: Medium
Uncertainty: Known
Flags: none
Blocked by: #8429
The decision settles the open questions: flip the default host to the HTML mockup (option 1) once #8429 lands, keep the real stack as an explicit override, and keep explore-directions grandfathered under the rendered-views convention. The work is a bounded change to the skill, its evals, the native-surfaces rows and a changelog fragment. It is blocked by #8429.
Automated triage, applied by the lanes App.
kyle-sexton commentedon Oct 25, 2026
Released for re-triage under the owner's 2026-10-24 rule: an issue stops for a person only for an intent or vision question, a security call, a host or attended run, or spend outside prepaid credit. The hold label came off and intake triage runs again now; it re-applies a hold, with a numbered question, when one of those applies.
To hold this issue again, add
needs-human(orstatus: needs-decision) and say why in a comment.melodic-automation-lanes commentedon Oct 25, 2026
The latest triage verdict holds nothing: the issue is at
status: ready.melodic-automation-lanes commentedon Oct 25, 2026
Refinement. A read-only run explored this repository, searched its issues and pull requests, and read the allowed docs to draft what follows. On an issue a listed human filed, it counts as the issue's spec once posted, while unedited; it is still model text, so check it.
Intended outcome: Option 1 once #8429 lands: the self-contained HTML mockup becomes explore-directions' default host, with real-stack sub-shapes A and B as explicit overrides and the winner's fold-in path.
Dependencies
Related work
Open questions
RECOMMENDED: Option 2 for now; revisit option 1 after #8429 lands. It is the smaller change and keeps the realism argument, but the owner must choose because the issue lists three options and picks none. Basis: plugins/prototype/skills/explore-directions/SKILL.md:75
RECOMMENDED: Yes. Without it a mockup of an existing app loses the realism that the current default buys (SKILL.md:80-88). Basis: 8429
RECOMMENDED: Stay grandfathered and say so in the PR. A change of default host does not need the convention's content classes. Basis: docs/conventions/rendered-views/README.md:552-558
Sources read
Automated refinement by the lanes App. Answer with a comment whose first line is
**Decision recorded.**.kyle-sexton commentedon Oct 26, 2026
Decision recorded. The owner answered in the Refinement and Issue Triage sessions (2026-10-25), deciding the open items below on the facts:
Owner ledger: Q37 (
.work/issue-triage-owner-sweep-1/interview-checklist.md:62) is markeddeferred, "outside the pipeline focus; issue not touched". It decided nothing, so nothing below reverses it.Questions from intake's refinement (#8776 (comment)):
Decided: Option 1, flip the default to the HTML mockup, blocked by explore-directions: HTML mockups of an existing app's feature should keep the app's look #8429. The issue's title and its own criteria state that outcome; option 2 would keep sub-shape A as the default and so not meet it. The body recommends option 1 "only together with explore-directions: HTML mockups of an existing app's feature should keep the app's look #8429", and explore-directions: HTML mockups of an existing app's feature should keep the app's look #8429 is decided in this batch to keep the app's look on the mockup. The skill's realism argument (
plugins/prototype/skills/explore-directions/SKILL.md:80-88, origin/main 68d3f2b) covers a page shown without its real chrome and without its live data volume. explore-directions: HTML mockups of an existing app's feature should keep the app's look #8429 restores the chrome by building each variant from the app's own CSS and surrounding page; the mockup still binds synthetic data only (SKILL.md:108-113). In the body's words, grounding the mockup in the product's look would "recover much of the realism the current default buys", and the real stack stays an explicit override for layout that depends on live data volume, as the body's proposed approach says. Option 3 adds a question to every run, which the body rejects as friction.Decided: Yes. Until it lands, the mockup substrate still forces a different look per variant (
SKILL.md:134-138,:195), so flipping the default first would put existing-app work on the look the owner rejected in explore-directions: HTML mockups of an existing app's feature should keep the app's look #8429.Decided: Stays grandfathered. The convention holds current emitters "grandfathered on their shipped ladder and
mediumonly" and listsprototype:explore-directions(docs/conventions/rendered-views/README.md:552-555). The HTML mockup is already a host on that shipped ladder (SKILL.md:77), so making it the default adds no medium.Blocked by: #8429.
Acceptance criteria: the body's five criteria stand as written. One is added:
prototype:explore-directionsremains on the grandfathered list indocs/conventions/rendered-views/README.md, and the pull request says so.melodic-automation-lanes commentedon Oct 26, 2026
Not admitted to the issue lane yet: blocker #8429 is not closed by a listed human or a merge.