| name | gmira-brief |
| description | Use when starting any web surface and no written brief exists yet: a new landing page, a vehicle inventory site, a product detail page, a course or cohort page, a dashboard, a portfolio, a checkout. Also use when a build is about to invent content it has no right to invent (prices, customer names, logos, benchmarks, seat counts, review scores), when the requested page turns out to be several surfaces with different jobs, or when a first draft came back generic because nobody wrote down what is actually true. Extracts product truth against aspiration, the visitor scene, the real content model field by field, the surface mode, and the uninventable list, then commits all of it to `.gmira/surfaces/<slug>.md`. Run it before `gmira-direction`, every time, including on "just fix the hero". |
Brief
Extract what is true. Everything downstream is allowed to be bold about how it looks and about
nothing else.
Load ../gmira/references/DOCTRINE.md first. This skill produces the input that Part 2 and
gate G7 both depend on.
The premise
A brief is not a summary of what the user said. It is the set of facts the build is not allowed
to invent, plus the content model that decides what the layout can even be. A page built without
one defaults twice: once on the aesthetic, once on the shape of the data. The second default is the
one nobody names, and it is where card grids come from. A card with a title, an icon, and two
lines is a shape. A vehicle listing has 22 fields and 24 photographs.
The output is a written file. If the brief is not on disk, it does not exist, because the finishing
review has to audit against something.
Step 1: name the state you are in
Four states, four different verdicts. Decide before asking anything.
| State | Verdict |
|---|
| Redesign | Preserve product truth, content, function, constraints, explicit brand commitments. Replace the old visual world rather than polishing it. The old look is evidence of what the subject is, not authority over what it becomes. |
| Established world | Inherit it. A missing design doc does not erase a coherent identity already present in the code. Document that identity instead of inventing a replacement. |
| Incomplete brand | Preserve the confirmed assets and the recognizable traits, then extend the system for this surface. |
| No visual authority | Create a new world with the user. Full anti-default procedure in gmira-direction. |
Scope guard, and it is the one people break: a section, component, feature, or state inside an
established surface inherits that surface. Do not turn a local addition into a new identity
exercise.
INCORRECT user asks for a filter sidebar on an existing inventory page,
agent proposes a new color world and a type pairing.
CORRECT state = established world. Inherit tokens, type, spacing, and control vocabulary.
The brief covers only the new fields, states, and how the addition joins.
Step 2: ask, at most once
Two or three questions per message, then wait. One round is the default. A second round only
when an answer exposes a material gap, never to be thorough.
The question list, in order
- What is this surface for, and what does the visitor have to understand or do on it before
they leave?
- Who reaches it, on what device, under what light, with how much time, and how expert are they
in this category? One sentence, physical. This is the scene, and it later forces dark versus
light and the contrast floor.
- What is uniquely true here that a neighbouring product or a generic template could not
claim? If the answer is a category adjective, ask once more for the specific.
- Name the actual fields one item carries, and how many items there are at minimum, typically,
and at maximum. For a listing, a product, a course, a record. Not the card shape, the fields.
- What must remain untouched? Domain, URLs, legal text, an existing logo, a component the
client's team maintains, a data contract.
- What would make a polished result feel wrong? The single most useful question in the list.
It catches the constraints nobody states because they seem obvious.
- What is not allowed to be invented? Prices, customer names, certifications, availability,
capabilities, benchmark figures, headcount. Read back your own list and have it confirmed.
Five is the floor, seven is the ceiling. If the prompt already answered four of them, ask the
remaining two or three and stop.
When to stop
- Never ask for CSS values or a menu of aesthetic lanes. "Modern or classic", "which of these
three palettes", "do you want it playful" are all the same question and it is the wrong one.
Direction is assigned in
gmira-direction, not chosen from a list here.
- Never ask which mode the surface is. Infer it from question 1 and state the inference.
- Never restate a settled fact as a question. If the ask says "car dealership in Oldenburg with
41 cars in stock", the location and the stock size are settled.
- Assert the likely reading and invite correction. "I am reading this as Persuade, a first visit
from paid traffic on a phone, and the primary action is a test drive request. Correct me on any of
the three." That costs one line and replaces three questions.
- A sparse prompt gets one full round. A precise prompt may need only the compact confirmation.
- Two consecutive rounds with no new constraint means you are interrogating. Write the brief with
the inferences marked and move.
What to infer instead of asking
Every inference goes in the file on an INFERRED line so it can be corrected in one word.
| Inferable | How |
|---|
| Mode | From the visitor's success condition in answer 1 |
| Effect budget | From mode, per the doctrine table |
| Dark or light | From the scene sentence in answer 2, resolved in gmira-palette |
| Content model gaps | From the category's real data shape, then flagged as assumed |
| Locale, currency, date format, units | From the business location |
| Breakpoint set | 390, 834, 1024, 1440, 1920. Fixed by the verify gate |
| Legal surface requirements | Impressum, Datenschutz, Widerruf for a German commercial site |
Step 3: mode, per surface
Mode names what the visitor's success looks like on the surface in hand, not on the project.
A tool's landing page is Persuade even though the product is Operate. A fashion house's
documentation is Read.
| Mode | Visitor success | Effect budget |
|---|
| Persuade | decides and acts; design is the product | Highest. One heavy effect, bounded, in the first viewport. |
| Experience | is inside the work itself | Highest. The effect may be the content. |
| Read | understands something | Low. Nothing animated inside the measure. |
| Operate | completes a task | Near zero. A checkout with a fluid background is a bug. |
Mode also sets the type scale ratio (1.25 brand, 1.125 to 1.2 Operate), the color strategy floor
(Restrained is the default for Operate and Read), and where the budget goes instead: state coverage
and input latency.
INCORRECT MODE: operate (because the product is a dashboard)
CORRECT one project, three briefs:
/ MODE: persuade marketing site, effect budget open
/app MODE: operate effect budget near zero, ratio 1.2
/docs MODE: read measure first, no motion in the column
Step 4: the real content model
This is the half of the brief that people skip, and skipping it is what produces the card grid.
Write the field list. The field count and the nesting depth decide what the layout can be.
Vehicle listing, German dealer stock
| Field | Note | Range |
|---|
| make, model, trim | trim absent on roughly 20% of stock | |
| model year and first registration MM/YYYY | two different fields, routinely conflated | |
| mileage km | the number buyers read second | 0 to 320,000, typical 48,000 |
| power kW and PS | both are shown, PS is the one that is read | |
| fuel, transmission, drivetrain, body, doors, seats | 6 enum fields | |
| exterior colour + paint type | uni, metallic, pearl | |
| interior material + colour | | |
| previous owners | | 0 to 6, typical 1 |
| service history | full, partial, none | |
| next HU date | absent on new stock | |
| emissions class, CO2 g/km, combined consumption | legally required on the page | |
| warranty months remaining | | 0 to 24 |
| VAT status | §25a versus ausweisbar, changes the price block for business buyers | binary |
| price, financing rate from, monthly | | |
| branch, VIN | | |
| photographs | portrait and landscape mixed, not one crop ratio | 8 to 60, typical 24 |
| equipment list | | 12 to 80 lines, typical 34 |
| free-text description | | 0 to 1200 chars, absent on 40% |
| accident and damage declaration | required, never optional | |
Twenty-two fields, mixed photo ratios, one long list, and one field that changes the price display
for a whole buyer class. That is a spec table plus a gallery plus a disclosure, not a card.
Course or cohort
course > module (4 to 12) > lesson (3 to 8) > resource, four levels. Plus format, language, start
date, duration in weeks (4 to 24), hours per week, session schedule with timezone, cohort cap (8 to
40), seats remaining, prerequisites (0 to 5 lines), instructors (1 to 4, each a real bio and a real
link), project deliverable, certificate type and issuing body, funding eligibility (Bildungsgutschein,
AZAV certificate number, employer invoice), price, payment plan, refund window, waitlist state.
A card grid flattens four levels to one. That is the whole argument against it here.
Product detail
Title, brand, SKU, variant axes (size 4 to 14 values, colour 2 to 12) with stock per combination,
price, compare-at, tax note, shipping lead time, returns window, weight, dimensions, materials,
care, spec table 6 to 20 rows, reviews 0 to 4000 with a real distribution, badge state
(new, sale, last one, preorder, backorder), bundle and cross-sell relations.
Ranges are part of the model
Every repeating set gets min, typical, max, and the layout has to survive all three. A grid tuned
for the typical case breaks at min (one item, alone, in a three-column track) and at max (80
equipment lines in a container built for 12).
INCORRECT "a list of features"
CORRECT equipment: 12 / 34 / 80 lines, single-column at 390, two at 834,
three at 1440, alphabetized inside groups, no truncation at any count.
At 12 the block must not read as an empty grid.
Step 5: what must not be invented
Two lists, and the distinction between them is the rule most often broken in both directions.
Uninventable, always. Commercial and factual claims: prices, customer names, logos,
testimonials, quoted people, benchmark numbers, certification and registration numbers, headcount,
funding amounts, API endpoints, availability dates, review counts, star ratings, "trusted by",
capabilities the product does not have, awards, press mentions, years in business.
Illustrative, allowed when labeled. Truth binds claims, not demonstrations. In greenfield work,
author whatever material the concept needs at full fidelity, label it wherever a visitor could
mistake it for real, and hand back the replacement list.
INCORRECT refusing a spec-table hero because the client has not sent the stock feed,
and shipping a centered headline with two buttons instead.
CORRECT author one full vehicle record at real fidelity, mark it
data-illustrative="true", render a visible "Beispieldatensatz" label,
and list it under ILLUSTRATIVE in the brief with the field the real feed supplies.
Refusing a committed direction because its demonstration data does not exist yet is timidity
wearing honesty's clothes. Inventing a customer logo is not boldness, it is a false statement.
True versus aspirational
Go through the ask sentence by sentence and mark each T or A. A T has a source you could
point at: a feed, an invoice, a certificate, a public register, a live count. An A is a hope, an
ambition, or a comparative with no measurement behind it.
| Sentence | Mark | Consequence |
|---|
| "41 cars in stock" | T, and it is queryable | renders, from the feed, never hardcoded |
| "largest independent Porsche specialist in Lower Saxony" | A | goes in ASPIRATIONAL, never renders as a claim |
| "AZAV certified, cert 12345-6" | T | renders with the number |
| "students land jobs fast" | A | renders only if a real outcome figure exists, otherwise cut |
Aspirational content is not deleted from the brief. It is recorded so that later, when someone asks
why the hero does not say it, the answer is on file.
Step 6: write the file
.gmira/surfaces/<slug>.md. One file per surface, not per project. gmira-direction appends
its 5-block contract to the same file, which is how the finishing review audits promise by promise.
# <slug>
STATE redesign | established-world | incomplete-brand | no-visual-authority
MODE persuade | operate | read | experience
SCENE one sentence, physical: who, device, light, time, expertise
JOB what the visitor must understand or do before leaving
ONLY-TRUE-HERE the thing a neighbouring product could not claim
TRUE verified facts, each with the source that backs it
ASPIRATIONAL said in the ask, not yet true, does not render as a claim
CONTENT item type, field list, min / typical / max per repeating set
STATES which of empty, loading, error, partial, overflow, expert actually occur here
UNINVENTABLE the explicit list, confirmed by the user
ILLUSTRATIVE what may be authored, how it is labeled, what replaces it
UNTOUCHABLE domains, URLs, legal text, owned components, data contracts
WRONG-EVEN-IF-POLISHED
INFERRED one line per inference made instead of asking
OPEN choices a builder must not invent, still unanswered
Three to five bullets per block when the task is settled. Use the full structure only for an
ambiguous, multi-screen, or standalone surface. Do not restate the conversation.
Then stop. The brief never writes code and never writes a direction contract. Hand to
gmira-direction.
Checks before this skill is done
