Repository navigation
Conversation
domain-interview makes no design decisions on purpose, so a build that starts from a brief (Plan it with me, or I already have a brief) was never asked how it should feel; only Just build it asked. boxel-design now runs a Look check at build entry: the feel and real-details questions, asked once and only when unanswered, recorded as Look: and Real details: lines in the brief's designDirection in the user's words. domain-interview's hand-off, the index route and the glossary say the same. Split out of #151 so it can be tested on its own. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Facts in spec do not answer the real-details question; offer the concept-or-pitch option like the Just build it call; give every skip a recorded form; say how the field is written and that the build reads it; point at the first-call paragraph instead of a step that does not exist. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…skip takes the recommended option Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ource Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Staging Workspace Sync SuccessfulSuccessfully synced changes to staging workspace Sync Details |
…n every label Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…reason in the description Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…g places pick one, notes without a look answer nothing Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…uted accents, record the hue a mode word took Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
lucaslyl
commented
Oct 12, 2026
lucaslyl
left a comment
lucaslyl
left a comment
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Lens: whether the Look check agrees with the briefs domain-interview actually writes, with index.md, and with the neighbouring boxel-design sections, checked by reading plus simulated runs on this head (three runs each for two scenarios, not a live Boxel build).
One blocking issue: the "Use what's in the brief" option and the "spec facts count as a source" claim treat invented sample data as user-supplied, and the simulated builder then published invented prices as the business's own. Two non-blocking decisions follow.
- (blocking) Key the option and the source claim to what the user supplied, not to anything in
spec; see the comment on the "concrete facts" sentence. - Decide what a feel word with no hue records, and how "quiet" differs from "earthy"; see the comment on "A cue that settles the feel".
- State whether a governing
BrandGuideanswers the feel question; see the comment on "The colour words in the label are binding".
lucaslyl
deleted the
eco-602-look-check-ask-about-the-look-when-a-build-starts-from-a
branch
October 12, 2026 08:50
Reverts the place-fitted looks (kept on branch eco-602-dynamic-looks-backup). The feel question is Light & calm / Dark & dramatic / Bold colour / You decide, as in the design pipeline PR, so this PR stays a small split of it. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…er nothing, designs answer the feel, typed details are prefixed Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…f's, design text is not a stated fact, hand-off names both questions Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…th a real model Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ing brand guide answers the feel Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…Guide Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
habdelra
reviewed
Oct 12, 2026
|
|
||
| **Record it on the brief**, when there is one, straight after the answer, including what the user's | ||
| prompt already said. Write the `Look:` and `Real details:` lines it does not already have into its `designDirection` field (this skill's field; | ||
| `domain-interview` owns `spec`) with `run-realm-code`, changing only that field: add the two lines after any text already there, never deleting it; if the |
Contributor
There was a problem hiding this comment.
Look check tells the builder to edit designDirection with run-realm-code, but domain-interview (Output) says multi-line markdown must never be hand-escaped into the JSON string and must go through patch-fields (assistant) or a JSON.stringify script + boxel file write (terminal agents, where run-realm-code does not exist). A realm.fs.replace on Brief/.json with a raw newline or quote produces invalid JSON / a broken card, and Claude Code / Codex builds get no usable write path at all.
Generated by Claude Code
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Fixed in 667de6b. The Look check no longer names run-realm-code. The assistant reads the card and uses patch-fields on designDirection; terminal agents follow domain-interview → Writing it from a terminal agent (parse the brief JSON, set the field in a script, JSON.stringify, boxel file write --file, re-read before and after).
habdelra
reviewed
Oct 12, 2026
| Real details: use what's in the brief | facts: <the user's words> | leave marked slots | leave sections out | concept (demo mode) | ||
| ``` | ||
|
|
||
| On `Look:` a skipped question records `You decide`, and a feel answered by a governing `BrandGuide` or |
Contributor
There was a problem hiding this comment.
A feel answered by a governing Theme is told to record Look: from the BrandGuide (<its name>). When the governing source is a StructuredTheme/StyleReference (no BrandGuide), the brief permanently records a BrandGuide that does not exist, and a later build reading the line will look for one.
Generated by Claude Code
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Fixed in 667de6b. The recorded line is from the <BrandGuide or Theme> (<its name>), naming the kind the governing source actually is.
habdelra
reviewed
Oct 12, 2026
| **Already answered** means any of: the user's prompt or attachments state it (named colours, a | ||
| brand, a logo or a reference site, or a feel word that names one of the three options or a colour | ||
| ("dark", "bold", "light and calm"), for question 1; facts for question 2); a governing `BrandGuide` | ||
| or Theme for this work (see *Brand and Style Source* below) answers question 1 too; it was answered |
Contributor
There was a problem hiding this comment.
"A governing BrandGuide or Theme ... answers question 1" — but Brand and Style Source (user/custom realm work) has the assistant "derive or choose the Theme ... from the user's domain". A Theme the assistant picked or an unrelated realm Theme therefore counts as answered, so the feel question is skipped and the user never decides the look, which is what this check exists to prevent. Limit it to a BrandGuide/Theme the user named or that their work already links.
Generated by Claude Code
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Fixed in 667de6b. Only a BrandGuide/Theme the user named or their work already links answers question 1. A Theme the assistant derived or chose under Brand and Style Source, or one that merely exists in the realm, answers nothing.
habdelra
reviewed
Oct 12, 2026
| user typed always start with `facts:`, so typed text can never be read as one of the other four, and | ||
| they add to the facts the user stated in the brief, never replace them. A | ||
| skip records the one it took. The build reads both lines as given: the look steers the mockup, and the | ||
| real-details line decides what the build may write about the user's business. Only what the user stated counts as a source under |
Contributor
There was a problem hiding this comment.
Only the Interview record is treated as a source, but domain-interview says "where the record and a section differ, the section is what the build follows", and the record stores picked option labels including assistant-proposed "(Recommended)" ones. A user who corrected a fact later in Scope/Content contracts (or whose answer was an assistant suggestion) gets either the stale record value or an assistant-written fact published as the business's own.
Generated by Claude Code
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Fixed in 667de6b. Facts that count now says a later Scope or Content-contract section that corrects a record value is what the build follows, and that an assistant-proposed "(Recommended)" option taken by a skip (Skipped) is not a source.
habdelra
reviewed
Oct 12, 2026
| design decisions on purpose. | ||
|
|
||
| Ask only the questions that are still unanswered, together in one choice-UI call, each with its skip | ||
| option (rules: [`domain-interview`](../domain-interview/SKILL.md) → *Skipping*): |
Contributor
There was a problem hiding this comment.
Skip rules point to domain-interview → Skipping, whose "Skip the rest" description is "I'll decide this and everything after, and write the brief". At build time the option will tell the user it writes a brief, and a builder following that rule may stop and rewrite the brief instead of building. Give the build-time description here (the PR notes the mismatch but this section newly depends on it).
Generated by Claude Code
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Fixed in 667de6b and 0ad9840. The Look check words the skip for a build: Skip the rest with "I'll decide this and go on to build", never "write the brief". index.md uses the same wording.
habdelra
reviewed
Oct 12, 2026
| 2. **Real details:** "Anything true about this place a competitor couldn't say?" When the brief's | ||
| `spec` already holds concrete facts the user stated (names, places, prices, house rules, as in its | ||
| Interview record), the real options are | ||
| **Use what's in the brief** (recommended) / *No details — leave marked slots for them* / *It's a |
Contributor
There was a problem hiding this comment.
When the brief has user-stated facts, the option list drops No details — leave those sections out, though leave sections out is one of the five stored values. A user with a few facts in the brief who wants the remaining unsourced sections omitted has no option for it and is pushed to marked slots or demo mode.
Generated by Claude Code
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Fixed in 667de6b. With user facts in the brief the options are Use what's in the brief (recommended) / No details beyond the brief — leave the other sections out / the concept-or-pitch option, so leave sections out is reachable.
habdelra
reviewed
Oct 12, 2026
|
|
||
| ``` | ||
| Look: Dark & dramatic | ||
| Real details: use what's in the brief | facts: <the user's words> | leave marked slots | leave sections out | concept (demo mode) |
Contributor
There was a problem hiding this comment.
designDirection is a MarkdownField: the Look: and Real details: lines written on consecutive lines (and appended directly after existing text) render as one paragraph ("Look: Dark & dramatic Real details: ..."), and appending without a blank line merges them into the prior note's paragraph. Specify a blank line before them, or a list.
Generated by Claude Code
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Fixed in 667de6b. Each line is its own paragraph: a blank line between Look: and Real details:, and a blank line before the first when text is already in the field. The example block shows it.
habdelra
reviewed
Oct 12, 2026
| five, written exactly so (they are the stored form of the options, not their labels); details the | ||
| user typed always start with `facts:`, so typed text can never be read as one of the other four, and | ||
| they add to the facts the user stated in the brief, never replace them. A | ||
| skip records the one it took. The build reads both lines as given: the look steers the mockup, and the |
Contributor
There was a problem hiding this comment.
"The build reads both lines as given" — nothing in design-playbook.md (the actual build process) or critical-rules.md mentions designDirection, Look: or Real details:. A build resumed in a later session from the playbook has no step that reads them, so leave sections out / concept (demo mode) is silently ignored.
Generated by Claude Code
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Fixed in 667de6b. design-playbook.md Stage 1 now opens with reading the Look: and Real details: lines from designDirection, and critical-rules.md → Never invent proof points to the Real details: value.
habdelra
reviewed
Oct 12, 2026
| - **Just build it** → `boxel-design` and the design-playbook, after one call of questions (below), to a first version: the page, or for an app, its linked cards and Home card. **The default recommendation**, because most users want to see something first. List it first. | ||
| - **Plan it with me first** → `domain-interview`, which asks for the main input first and sizes the rest of the interview from how the user answers. Recommend this instead only when the domain has regulation, money, safety or specialist vocabulary a builder would not know. | ||
| - **I already have a brief or a design** → go straight to the build, reading the brief card when one exists. | ||
| - **I already have a brief or a design** → go straight to the build, reading the brief card when one exists; `boxel-design`'s *Look check* asks the feel and real-details questions once if the brief does not record them. |
Contributor
There was a problem hiding this comment.
The route covers "a brief or a design", but the Look check sentence only conditions on the brief recording the answers, and boxel-design's Look check intro names only "I already have a brief". With an attached design and no brief it is unclear whether the real-details question is asked; an attached design answers the feel but not real details, so a build may proceed with no real-details decision.
Generated by Claude Code
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Fixed in 667de6b. The Look check applies to a brief or an attached design. An attached design answers the feel (recorded as from the attached design) and never the real details, so that question is still asked. index.md says the same.
habdelra
reviewed
Oct 12, 2026
| → `boxel/references/design-playbook.md` | ||
|
|
||
| - **Layout vocabulary** — eight layout moves (layered surface, bento, masonry, unequal split, edge overlap, editorial type, bleed, sticky scroll), each with what it is for, when not to use it, and its in-card CSS; sections come first, and zero moves is valid. → `boxel-design/references/layout-vocabulary.md` | ||
| - **Look check** — the feel and real-details questions asked once before the first design decision: in the "Just build it" first call, or at build entry from a brief; recorded as `Look:` and `Real details:` lines in the brief's `designDirection`. → `boxel-design/SKILL.md` |
Contributor
There was a problem hiding this comment.
New "Look check" entry is inserted between "Layout vocabulary" and "Layout gravity wells", splitting the two layout entries; place it after them.
Generated by Claude Code
Contributor
Author
There was a problem hiding this comment.
[Claude Code 🤖] Fixed in 667de6b. The Look check entry now follows the two layout entries.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ook read, ordering) Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
richardhjtan
approved these changes
Oct 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes ECO-602. Split out of #151 so this one piece can be tested and reviewed alone.
Problem
domain-interviewmakes no design decisions on purpose. On main only the "Just build it" route asks how it should feel, so a build that starts from a brief ("Plan it with me" or "I already have a brief") or from an attached design is never asked about the look.Change
boxel-designgets a Look check that runs at build entry from a brief or an attached design:Look: from the attached design) and never the real detailsindex.md"Just build it" says the same)BrandGuideor Theme answers the feel question only when the user named it or their work already links it (or it is the built-in Boxel Brand Guide for built-in work); a Theme the assistant derived or that merely exists in the realm answers nothing. It is recorded asLook: from the <BrandGuide or Theme> (<name>)Look:andReal details:in the brief'sdesignDirection, in the user's words, never expanded into a palette or fonts; typed details are prefixedfacts:. Each line is its own paragraph (blank line between, and before the first when text is already there)patch-fieldsin the Boxel AI assistant; in a terminal agent, a script that sets the field andJSON.stringifys the brief, thenboxel file write --file, with a re-read before and after.run-realm-codeis not usedboxel-designandindex.mddesign-playbook.mdStage 1 andcritical-rules.md→ Never invent proof read theLook:andReal details:lines, so a resumed build follows themindex.md, thedomain-interviewhand-off and the glossary point at itLeft out: the page-colour table (needs
style-families.md, not on main yet).Where to start
Read the Look check section in
skills/boxel-design/SKILL.md; the other files only point at it or read its two lines.Testing
Simulated builder runs (agents reading the skill text), three scenarios of three runs each on the current head, all 9 passing:
boxel file writepatch-fieldsfrom the attached designrecorded, corrected hours used, existing note keptThese are simulations, so a signal rather than proof. Not tested: a real build in the Boxel app, and real-model runs of the final head. The eval cases are not part of this PR.
🤖 Generated with Claude Code