vision

name	vision
description	Fill or update the Vision section in PILOT.md — problem / target user / V1 scope / north star metric

/vision

Forces the product framing that solo builders skip. Fills (or updates) the ## Vision section in .meta/PILOT.md through a short guided dialogue.

Auto-proposed at first session when the Vision section is all _TBD_. Can be invoked manually at any time to update individual fields.

---

Hard rules

• Only edit the ## Vision section of PILOT.md — never touch other sections
• Never overwrite existing content without per-field confirmation — always show current value and ask before replacing
• Always update _Last updated: YYYY-MM-DD_ on any change
• Show the example only once — at session start, not repeatedly
• One question per section — do not bundle questions

---

Process — first fill (all fields are _TBD_)

Step 0 — Show example (once)

Show this filled example to unstick the user:

Vision example — "Expense Tracker CLI"

Problem: Developers track expenses in spreadsheets because dedicated apps are
either over-featured or require SaaS subscriptions. A local CLI with plain-text
storage fits the Unix philosophy and removes the data-trust problem.

Target user:
- Solo developers or small freelance teams (1-5 people)
- Currently using Google Sheets or Numbers — losing 10 min/week to manual entry
- Privacy-conscious, prefer no cloud sync

V1 scope (MoSCoW):
- Must: add expense, list by month, export CSV
- Should: categories, basic totals
- Won't (v1): multi-currency, cloud sync, web UI

North star metric: ≥3 expenses logged per week by the end of month 1.

Then say: "Now let's fill in your project. I'll ask one question at a time."

Step 1 — Problem

Ask: "What real-world friction does this project remove? (3-5 lines: the pain, who feels it, what they do today instead)"

Wait for the answer. Do not move on until the user responds.

Step 2 — Target user

Ask: "Who hits this friction? Give me 2-3 bullets: role, frequency of the pain, and what they use today as a workaround."

Step 3 — V1 scope

Ask: "What must v1 do? Use MoSCoW: Must / Should / Won't for v1. A single Must bullet is fine if you're uncertain — you can expand later."

Step 4 — North star metric

Ask: "One measurable signal that tells you the project is working. Examples: '≥10 daily active users', '≥5 GitHub stars in month 1', 'processes 100 transactions/day without error'. Make it concrete and time-bound."

Step 5 — Confirm and write

Show the complete drafted Vision section and ask: "Does this capture it? I'll write it to PILOT.md."

On confirmation, use Edit to replace the Vision section (Problem through North star metric) in .meta/PILOT.md, and update _Last updated: YYYY-MM-DD_.

---

Process — update (existing non-TBD content)

1. Read .meta/PILOT.md and display the current Vision section.
2. Ask: "Which fields would you like to update? (Problem / Target user / V1 scope / North star metric / all)"
3. For each selected field: show current content, ask for the new version, confirm before writing.
4. Update _Last updated: YYYY-MM-DD_ regardless of which fields changed.

---

PILOT.md section template (for reference)

## Vision

_Last updated: YYYY-MM-DD_

### Problem
<!-- 3-5 lines: what real-world friction does this project remove? -->

### Target user
<!-- 2-3 bullets: who hits this friction? what do they do today instead? -->

### V1 scope
<!-- MoSCoW short: Must / Should / Won't (for v1) -->

### North star metric
<!-- One measurable metric that tells you if the project is working. -->

Note for skills-pack users: this skill assumes .meta/PILOT.md contains a ## Vision section with the four subsections above. If your PILOT.md was not generated by metadev-protocol, add the section manually before running /vision.

---

Rationalizations (why you must NOT skip steps)

Excuse	Why it's wrong
"I know my project, skip the questions"	The point is the written artifact, not the knowledge. Unwritten vision disappears from AI context and from your own clarity after 3 sessions.
"I'll fill it later"	You won't. The gap between "I'll fill it later" and "why is the AI suggesting completely wrong features" is exactly one week.
"This is too early, I don't know V1 scope yet"	MoSCoW can start with Must only. One bullet is a valid V1 scope. The goal is commitment, not perfection.
"The north star metric feels arbitrary"	An arbitrary metric beats no metric. You can change it. You can't improve what you don't measure.