clarify-component

clarify-component

A skill that turns an under-specified natural-language UI component request into a precise component specification, then writes the result to a Markdown file. The skill fills every dimension of the spec by inference and authors the result directly; it asks the director a question only when a decision is a genuine UI branch that passes Principle 2's two gate conditions at once (see references/dimensions.md, The governing rule: the gate is the law). In practice this reduces almost always to the interaction-model variant.

Invocation

/clarify-component "<natural-language request>"

The natural-language request may be supplied as an argument. If it is omitted, the AI asks for it as the first message of dialogue.

Output

A single Markdown file at:

docs/gyre/specs/components/<kebab-name>.md

The output path is not user-overridable in this iteration. See references/output-format.md for the file's full structure.

Language

Questions, prompts, multiple-choice presentations, and any follow-up messages delivered to the user are in the user's language, inferred from the user's first message. Everything else — the spec body in its entirety (Summary, Purpose, descriptions, rationale, edge cases, code-bound string literals), and any internal AI processing — is in English without exception. The skill body and reference files are written in English. The output Markdown file's section headings and content are both in English; the AI translates the user's natural-language answers into English at spec write time.

Process

The skill executes eleven steps in order. Steps 3–9 are the seven dimensions documented in references/dimensions.md, governed by the gate rule (The governing rule: the gate is the law) — filled by inference by default, asked only when the gate is satisfied. (Classify = 1, Risk read = 2, the seven dimensions = 3–9, Self-check = 10, Write spec = 11.)

1. Classify

Determine whether the request describes a single UI component, a page or layout, or a design guide.

• Clear component classification → proceed to step 2.
• Clear page or design-guide classification → tell the user the skill currently handles component specifications only, and terminate without writing a file. Page and design-guide handling are planned for future iterations.
• Ambiguous classification → ask the user directly which of the three the request is, and branch on the answer.

2. Risk read (internal)

Estimate the three risk axes documented in references/risk-signals.md from the request text alone. This estimate is never shown to the user and never written to the output file. It calibrates the depth of inference in subsequent dimensions and the self-check threshold (Step 10), per references/risk-signals.md.

3. Interaction model (gated question)

Run the Interaction model dimension as documented in references/dimensions.md. It activates when the requested component class admits more than one legitimate interaction model. Once activated, apply the gate: infer the variant when it is inferable from the intent; otherwise ask the single variant question. This is the one routinely-asked dimension.

4. Composition

Run the Composition dimension as documented in references/dimensions.md. It activates only when the component is divisible (several namable parts); for an atomic component it stays inactive and no ## Composition section is written. When ambiguous, default to inactive. Filled by inference; no director question. The units are stated as capabilities only — generate resolves which catalog component/primitive provides each, and whether the result is a molecule or organism.

5. What

Fill the What dimension by inference: purpose, usage scenarios, naming, and props. The inferred name establishes <kebab-name>, used as the output filename. No director question.

6. Look

Fill the Look dimension by inference: visual hierarchy, spacing, responsive behavior, token overrides/suggestions. Design-guide presence is generate's discovery; clarify does not ask about it. No director question.

7. How

Fill the How dimension by inference: states, interactions, accessibility, edge cases. Depth is calibrated by the risk read. The three sub-sections capturing observable behavior (## How → Interactions, ## How → Edge cases, ## How → Accessibility) follow the requirements-only voice rule; see references/dimensions.md and Step 10 Self-check.

8. Data / Content

Fill the Data / Content dimension by inference. The risk read calibrates inference depth (full vs. one-line schema), not whether the dimension is filled. No director question.

9. Non-goals

Infer and record at least one non-goal. A non-goal escalates to a question only when it passes the gate (rare).

10. Self-check

Evaluate, with no question asked to the user unless a gated escalation is warranted:

1. Could a code-generation step produce a coherent implementation from this spec, in one pass?
2. Are there any inferred items that could reasonably be interpreted in two different ways?
3. Are there any areas the risk signals flagged that have not been inferred in sufficient depth?
4. Does every bullet in ## How → Interactions, ## How → Edge cases, and ## How → Accessibility read as a requirement rather than an implementation pattern? Apply the three tests defined in references/dimensions.md (Note on requirements-only voice for ## How) and references/output-format.md (## How voice rule): the Outcome test, the Procedural test, and the Mechanism citation test. When an AI-authored bullet trips any test, rewrite it as the underlying requirement. Route prose to ## Implementation hints only when the director's original intent explicitly stated the pattern (with the director's rationale).

The ambiguity threshold tightens with risk: a high-risk component requires a lower ambiguity tolerance than a low-risk one to pass self-check.

If any check finds remaining ambiguity or a voice-rule violation, the AI deepens its inference (or, for a genuine gated UI branch, asks the one permitted question) and re-runs self-check. Repeat until no ambiguity or voice-rule violation remains. There is no iteration cap.

11. Write spec

Write the Markdown file at docs/gyre/specs/components/<kebab-name>.md per references/output-format.md. If a file already exists at the target path, do not overwrite silently — tell the user and ask whether to overwrite or pick a different name.

After writing, tell the user the file path so they can review.

Dialogue mode

Inference-first. The AI fills every dimension by inference and authors it into the spec. A director question is asked only when the gate is satisfied (almost always the Interaction model variant). Most invocations therefore involve zero or one question total.

Sequential discipline for the rare question. When a question is asked, it is delivered via the AskUserQuestion tool, one call per turn (see references/dimensions.md Question delivery). If a gated escalation co-occurs with the Interaction model question, ask Interaction model first.

Absorbing answers richer than asked. If the director volunteers information beyond what was asked (or in the original request), absorb it and let it override the corresponding inference.

Question accommodations (gated questions only)

For the rare gated question, every AskUserQuestion option is a proposed default the director can accept by selecting it. If the director's "Other" reply is equivalent to "I don't know," widen the candidate set or offer concrete examples in option descriptions; acceptance of a proposed default is a resolved decision, not a deferral. The skill never writes a spec containing an unanswered question; there is no Open Questions section.

Constraints on generated documents

The spec Markdown files produced by this skill are formal documents. They must not:

• Reference local paths of the host project beyond the conventional output path.
• Use vocabulary specific to development plugins outside the AI Harness.
• Link to files maintained by external plugins.

The only informal vocabulary they may use is vocabulary belonging to the AI Harness itself.

Reference files

• references/dimensions.md — The governing rule (the gate is the law), definitions, and inference sources for the seven dimensions.
• references/risk-signals.md — Three risk axes, the heuristic guide for assigning low/medium/high, and the context-announcement phrasing rules.
• references/output-format.md — Front matter schema and the Markdown body structure for the spec.

The AI reads these reference files at invocation time and uses them to drive dialogue and rendering. None of their contents are duplicated in this file.