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.
For improvements to an existing implementation, derive the prototype from evidence of that implementation and change only the question under test. Preserve decision-relevant appearance and behavior without requiring the same technology stack.
For UI prototypes, use the smallest sufficient design: retain only what the core task, comprehension, trust, essential feedback, accessibility, and recovery require; give each fact, action, and state one authoritative source; and assess possible removals counterfactually by default. Modify and rerun the artifact only when the effect cannot be judged reliably from current evidence and could change the prototype conclusion.
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:

Existing instructions, spec, plan, or user notes.
Relevant app or service entry points.
Existing UI patterns, screenshots, rendered references, test tools, prompt artifacts, schemas, or APIs.
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 optimization, refinement, or refactoring of an existing surface, establish a bounded baseline before building:

Inspect the relevant implementation and its direct components, styles, state transitions, or contracts. Use code for implemented behavior and the spec or user request for intended changes; make material discrepancies explicit.
Use available rendered views or screenshots alongside code. Run the affected project path only when a missing observation could change the decision; do not set up the full app merely to reproduce its layout. Record the source paths and baseline evidence, the proposed change, and what must remain stable in normal prototype notes; a separate report is not required.
If execution is unavailable, use inspected code and supplied evidence, label unobserved behavior, and limit the conclusion accordingly. Return Not Answered or Blocked only when the missing baseline can change the decision.

For UI work, inherit Target Platforms from the related spec and read only its matching entries in 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;
no usable product design system or a component system must be chosen: references/ui-system-selection.md;
common interface icons appear, or icons can affect usability, hierarchy, or platform fidelity: 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.
Default to disposable HTML/CSS/JavaScript for UI prototypes, including improvements to existing web and native apps. Reproduce the relevant layout, styles, content, and interactions from the inspected baseline, then apply the proposed change; identify stubs and deliberate departures.
Use another UI runtime when explicitly requested or when the question depends on behavior HTML cannot establish, such as native gestures, system integration, actual component rendering, or runtime performance. Reuse a disposable copy or harness in that case, and state why the runtime is needed. An existing native app or component library alone does not justify switching runtimes.
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 existing-surface improvements, compare baseline and prototype with the same relevant inputs, states, and viewport. Check the intended change and decision-relevant behavior that should remain stable. Correct unrelated drift before concluding, and disclose simulation gaps that limit the evidence.
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. 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.

Maintainer Eval

Only when explicitly evaluating this skill, run evals/run_eval.py; start with python3 evals/run_eval.py --validate-suite from the skill directory. Do not read or run eval assets during ordinary prototype work.

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

vibe-prototype

Vibe Prototype

Rules