Vibe Prototype

Use a disposable artifact to answer one uncertainty with observed evidence, then feed the decision back into the active workflow artifact.

Rules

• Treat the runnable, rendered, or executable artifact and its observed evidence

as the primary work. Keep it isolated from production code unless the user explicitly asks to prototype there.

• Stop and ask before destructive changes, production credentials, private data,

paid services, deployment, or irreversible external actions.

Workflow

1. Frame The Question

Before building or inspecting, define the question and success criteria in working context or temporary notes:

• Question: what uncertainty will this prototype answer?
• Decision unlocked: what spec or plan decision depends on it?
• Success criteria: what observable result is sufficient to answer the question?
• Surface: mobile, web, backend, agent workflow, prompt, state machine, or

architecture.

• Timebox: keep the prototype small enough to discard.
• Evidence: screenshot, command output, fixture result, notes, or artifact.

2. Inspect The Project Surface

Read only enough project context to choose a realistic prototype form:

1. Existing instructions, spec, plan, or user notes.
2. Relevant app or service entry points.
3. Existing UI patterns, screenshots, rendered references, test tools, prompt

artifacts, schemas, or APIs.

1. Constraints such as mobile target, browser support, credentials, sandbox, or

test data.

Screenshots and rendered references are valid context for visual decisions, but do not infer behavior they do not show. Stop only when missing context prevents the prototype from answering its specific question; record that blocker and the smallest missing evidence.

For UI work, inherit Target Platforms from the related spec and read only its matching entries in [references/platform-ui-checks.md](references/platform-ui-checks.md). If the declaration is missing or conflicts with the requested experience and that ambiguity can change the conclusion, return Blocked or Not Answered instead of guessing. Load these additional references only when the question needs them:

• layout, hierarchy, affordance, or visual alternatives:

[references/ui-prototype-method.md](references/ui-prototype-method.md);

• no usable product design system or a component system must be chosen:

[references/ui-system-selection.md](references/ui-system-selection.md);

• common interface icons appear, or icons can affect usability, hierarchy, or

platform fidelity: [references/icon-selection-method.md](references/icon-selection-method.md).

3. Build, Simulate, Or Inspect The Prototype

• When reviewing an existing prototype, run, render, and inspect it first. Do

not rebuild or modify it unless the user also asks for changes.

• Match the form to the surface:

- mobile or web: exercise the relevant viewport, navigation, interaction, and platform states; - backend: use a proof of concept, contract probe, fixture, or boundary check; - agent workflow or prompt: try the prompt, tool flow, artifact shape, and stop or escalation behavior; - state machine: exercise states, transitions, guards, invalid paths, recovery, terminal states, and an observable trace; - architecture: prove a boundary, interface, migration path, or test target.

• Prefer static HTML for quick UI exploration when product code is not needed

and framework fidelity is not part of the question. When visual-system or component fidelity matters, use the project runtime or another runtime that can render the selected system credibly.

• For static HTML, use only browser-renderable dependencies. When it represents

a native app, treat native libraries and conventions as visual references, and label the result as simulated rather than native-platform validation.

• Prefer existing test harnesses or small scripts for backend or data questions.
• Prefer transcript-style trials for prompt and agent workflow questions.
• Name prototype files so they are obviously disposable.
• Use the product or spec language for user-facing prototype content.

In OpenSpec mode, determine the current change directory from the user-specified change/path or an input artifact; ask if neither identifies it. Keep disposable prototype files under its prototypes/ directory, and do not overwrite existing files unless explicitly requested.

4. Run, Observe, And Decide

• Run or render the prototype in the runtime needed to answer the question.
• Exercise the smallest set of paths, states, variants, or viewports that can

confirm or invalidate the success criteria.

• Capture the smallest credible evidence: rendered views, interaction results,

command output, traces, fixtures, or concise notes.

• For UI work, apply only the selected platform and design checks that can change

the decision; record material evidence or deferral rather than treating the references as a universal checklist.

• Decide whether the evidence answers the question. Separate observed facts

from subjective judgments and require human review when the latter controls the conclusion.

5. Persist Evidence Only When Needed

Create a saved prototype report only when the user asks for one, the repository workflow requires one, or the decision needs durable handoff or audit evidence. Otherwise, keep the evidence with the disposable prototype and summarize the result in the final response.

When saving a report, use [references/prototype-report-template.md](references/prototype-report-template.md). Follow its formatting contract; localize placeholder prose and human-readable explanations to the user's language or the source artifact's primary language; keep paths, commands, code, IDs, status values, and direct quotes unchanged.

Validate saved reports with:

python3 skills/vibe-prototype/scripts/validate_prototype_report.py path/to/prototype-report.md

6. Return The Result To The Workflow

• Identify the exact spec, plan, review, or test-evidence change supported by

the conclusion. Apply it only when the user requests that update or repository instructions make it part of the current task; otherwise recommend it without editing the workflow artifact.

• If it fails to answer the question, record the blocker and next question

instead of pretending the prototype is conclusive.

Output

Lead with the decision rather than reproducing the report template. Briefly include:

• what uncertainty and surface were tested, and what observable result counted

as sufficient;

• where the disposable prototype lives and what evidence or validation was

produced;

• the decision or blocker, including any human judgment still needed;
• what should return to the spec, plan, review, or test evidence;
• when the prototype can be deleted.

Link a saved report instead of pasting it into the final response.

Use the user's language in the final explanation. Keep paths, commands, code, IDs, status values, and direct quotes unchanged.

Skill Signature

Always end the final response with:

Vibe Skill Signature
Skill: vibe-prototype
Status: Completed | Passed | Failed | Blocked | Partial
Next: concise next workflow step