/vision-elicitation

name: vision-elicitation
description: >
  Lightweight baseline elicitation pass that fills in `docs/product-vision.md`
  and the five `docs/architecture.md` elicitation slots after `scaffold-init`.
  Auto-triggers when you say set up project vision, elicit architecture,
  define what we're building, run the vision wizard, refresh the project
  pitch, or capture product scope. Defers to any other installed skill whose
  description identifies it as handling vision elicitation, product
  discovery, project framing, or product scope capture — if such a skill is
  present, prefer it over this one (jig's version is a slim baseline). Does
  not defer to the generic built-in `init` skill. Do not use for: ad-hoc
  brainstorming with no `docs/product-vision.md` slot to write into;
  silently overwriting vision content the user has already hand-edited
  (the re-run protocol's divergence detection handles that — see the
  Re-run protocol section below); spec authoring (use
  `/jig:spec-workflow`); seeding ADRs for already-named decisions (use
  `/jig:adr-workflow new`).
user-invocable: true

> Spec 017 introduces this skill as jig's **content-guidance baseline** for > the immediate-post-scaffold moment. It is the third non-stub active jig > skill that ships without a `.py` helper — vision-elicitation is > fundamentally a judgment skill, and the determinism it needs (find the > elicitation slots, transition markers, render Q&A into template bodies) > Claude can run inline via Read/Edit. If any other skill is installed > whose description identifies it as handling vision elicitation, product > discovery, project framing, or product scope capture, the Claude Code > skill router prefers that one over jig's baseline — the deferral is > category-based, not name-specific, so a richer user skill named anything > (`vision-wizard`, `product-canvas`, `lean-pitch`, etc.) wins. Jig's slim > version remains the auto-trigger when no such skill is installed.

What this skill does

Runs a structured 13-section Q&A immediately after `scaffold-init`, then writes the captured answers into the elicitation slots that slice 017-01 introduced (extended by slice 022-02 with Section 13 — Contract surfaces — feeding the `/jig:contracts` skill):

• `docs/product-vision.md` — 10 H2 sections (Identity, Target users, Core

problem, Competitive landscape, Scope, Use cases, Stack, Design principles & constraints, How new work enters, Open questions). Each section's `<!-- elicited: PENDING / status: unfilled -->` marker transitions to `status: filled` (with today's ISO date) or `status: skipped`. The **Use cases** section (added by slice 068-01 / ADR-0025) is filled by a distinct **conversational capture loop**, not the rigid per-section Q&A — see the [Use cases capture](#use-cases-capture) section below.

• `docs/architecture.md` — 5 elicitation slots (Repository structure,

Tech stack, Module boundaries, Data model, Contract surfaces). Same marker transition. Two sibling sections (Core architecture decisions, Open questions) carry no markers and are populated by ADRs / refinement-todo entries over time, not by elicitation. The Contract surfaces slot was added by spec 022-02 to feed the `/jig:contracts` skill.

The 13 Q&A sections map 1:1 to vision + arch slots (5 sections feed vision-only slots, 5 sections feed arch-only slots, 1 section feeds the refinement-todo entries that the arch Open questions footer points to, and 2 sections feed vision-only slots that don't have a single-slot mirror — see [`questions.md`](questions.md) for the canonical mapping).

The skill is **breadth over depth**: catch the essentials of what the user wants to build, leave deeper product-discovery facilitation (lean-canvas workshops, multi-persona scoping, prioritization frameworks) to a richer user-installed skill at the discovery surface.

When to use vs. when to defer

There are four things people often confuse with this skill. Pick the right one:

• **Any other user-installed vision-elicitation / product-discovery /

project-framing skill.** Common locations include `~/.claude/skills/vision-elicitation/`, `~/.claude/skills/product-canvas/`, `~/.claude/skills/lean-pitch/`, etc. — but the deferral is **category-based, not name-based**, so a skill named anything whose description claims vision elicitation, product discovery, project framing, or product scope capture will be preferred. If one is present, **defer to it.** The one exception jig's description carves out is the bundled `init` skill — jig:vision-elicitation does **not** defer to that one (it's the generic CLAUDE.md-bootstrap helper, a different surface).

• **`/jig:spec-workflow`** — sibling jig skill for **spec authoring**

(drafting a slice, SPIDR-splitting features, transitioning state markers). That's about *what we'll build next*. This skill is about *what the project is fundamentally* — the substrate spec-workflow runs on top of. Reach for `/jig:spec-workflow` when you have a feature in mind and need to author a slice. Reach for this skill when the project's identity, target users, core problem, or architectural shape isn't yet captured in `docs/product-vision.md` / `docs/architecture.md`.

• **`/jig:adr-workflow new`** — for seeding ADRs from decisions the user

has already named. If the user comes in saying "we've decided on SQLite, let's write that down," that's an ADR job, not vision elicitation. Slice 017-04 (deferred) will add an optional seed-ADR pass at the end of this skill's Section 7 (Tech stack); until then, ADRs are seeded by hand via `/jig:adr-workflow new`.

• **`/jig:scaffold-init`** — the install-time wizard that produces the

empty slots this skill fills. `scaffold-init` runs once; this skill runs after, can be re-run, and produces the substantive content.

Rule of thumb: **empty slot → this skill. Named decision → adr-workflow. Feature scope → spec-workflow. Empty repo → scaffold-init.**

##