define-vision

Skill: Define Vision

Purpose

Define and document thevision: the long-term future the project aims to create. The vision statement answers "What kind of future are we building?" and stays aligned with the mission. It does not define metrics, goals, or milestones.

Vision is different from：

mission: the fundamental purpose of the project's existence (use define-mission）。
North Star: a single metric representing delivered value (use define-north-star）。
strategic goals: 3–5 outcomes that realize the vision (use design-strategic-goals）。
milestones: phase checkpoints for execution (use define-roadmap）。

Core Objectives

Primary objective: generate a user-confirmed vision statement aligned with the mission, and persist it to the project's agreed path.

Success criteria(all requirements must be met):

✅ Vision statement exists: one to three sentences describing only the desired future state (no metrics, OKRs, or roadmap).
✅ Aligned with mission: the vision does not contradict the mission; if the mission is missing, suggest running define-mission first or state the assumed purpose.
✅ User confirmation: the user explicitly approves (e.g., "approved", "looks good", "continue", or equivalent).
✅ Document persistence: write to the agreed path (default docs/project-overview/vision.md or project convention).
✅ Respect scope: the statement does not define North Star metrics, strategic goals, or milestones.
✅ YAGNI/DRY/Conciseness: follow the spec §4 documentation artifact principles; the vision statement is the core, avoid unnecessary optional sections (such as explicit statements of mission alignment or time horizon).

Acceptance test: can the reader understand what kind of long-term future the project is trying to create, and see that it is aligned with the mission?

Handoff point: after the vision is approved and persisted, hand off to define-north-star or design-strategic-goals; if only the vision was requested, stop.

Scope boundaries

What this skill must do

Articulate the desired long-term future state of the project or product.
Produce a vision statement (1–3 sentences).
Ensure alignment with the mission (read the mission from define-mission output or existing documentation).
Persist to the project's agreed path (default docs/project-overview/vision.md）。

What this skill must not do

Define the fundamental purpose (use define-mission）。
Define North Star metrics or strategic goals (use define-north-star、design-strategic-goals）。
Define milestones (use define-roadmap）。
Write roadmaps, requirements, or backlogs (use capture-work-items , etc.).

Vision quality guidelines

A strong vision statement should have:

Conciseness: 1–3 sentences; focused on the future state.
Aligned with mission: supports the fundamental purpose in the mission; does not introduce a new purpose.
Imaginable: a picture of success 2–5 years out; the reader can sketch a concrete scene.
No metrics: contains no KPIs, OKRs, or numeric targets; metrics are the responsibility of define-north-star or design-strategic-goals .

Avoid in the vision:

Implementation details: Technology, deliverables, or the "how".
Buzzwords: Vague terms that fail to clarify the future state.

Usage Scenarios

After the mission is complete: After clarifying "why we exist", establish "the future we are building".
Strategic or directional reset: Realign the team around long-term goals.
When the roadmap lacks a goal: Create a clear vision so the roadmap aligns with the goal.
Second layer of the strategy chain: When building the complete hierarchy, run after define-mission .

Behavior

Interaction Strategy

Default: The output path of the project specification (docs/ARTIFACT_NORMS.md or .ai-cortex/artifact-norms.yaml); otherwise docs/project-overview/vision.md. Infer the mission from docs/project-overview/mission.md or the user.
Choose an option: If multiple possible futures exist, provide 1–3 candidate statements and ask the user to choose or refine.
Confirm: Before overwriting an existing vision file; before final persistence. If the mission is missing, confirm whether to assume a purpose or suggest running define-mission。

Execution Process

Load the mission: Read the mission from docs/project-overview/mission.md or a user-provided summary.
Elicit: What will "success" look like in 2–5 years? What kind of world are we creating for users?
Draft: Vision statement (1–3 sentences); future state only, no metrics or KPIs.
Check consistency: Ensure the vision supports the mission; refine with the user if necessary.
Persist: Write to the project's agreed path; if missing, create docs/project-overview/。

Inputs and Outputs

Inputs：

Required: Mission (statement or path to the mission document); project/product context.
Optional: Existing vision draft, time horizon, audience.

Outputs：

Artifact: Vision statement (1–3 sentences).
Location：docs/project-overview/vision.md(or per project specification).
Content: Vision statement; optional (YAGNI: only when truly needed) "alignment with mission" and "time horizon" notes.
Lifecycle: living (update when the strategic direction changes).

Constraints

Hard Boundaries

Do not include north star metrics, strategic goals, OKRs, or milestones in the vision statement.
Do not overwrite an existing vision file without explicit user confirmation.
Do not produce more than one vision document; this skill generates only the vision artifact.
YAGNI: The vision document centers on the statement; do not add unnecessary optional sections.

Skill Boundaries (avoid overlap)

Do not do these (other skills handle them)：

Mission: Root purpose → Use define-mission
North Star Metric: Single key metric → Use define-north-star
Strategic Goals: 3–5 outcomes → Use design-strategic-goals
Milestones: Phase checkpoints → Use define-roadmap
Roadmap, requirements, or backlog → Use capture-work-items etc.

When to stop and hand off：

User says "approved" or equivalent → vision complete, hand off to define-north-star or design-strategic-goals
User requests "one metric" or "north star" → Hand off to define-north-star
User asks about goals or milestones → Hand off to design-strategic-goals or define-roadmap

Self-check

Core success criteria (all criteria must be met)

Vision statement exists: one to three sentences, future state only (no metrics, goals, milestones).
Aligned with mission: does not contradict the mission; or the absence of a mission has been noted and confirmed by the user.
User confirmation: the user says "approved", "looks good", "continue", or similar.
Document persistence: write to the agreed path (default docs/project-overview/vision.md or project convention).
Respect scope: the statement contains no north star, goals, or milestones.
YAGNI/DRY/concise: follow the spec §4 document artifact principles.

Process quality check

Use the mission: before drafting the vision, was the mission read or requested?
Future state only: was mixing in metrics or OKRs avoided?
Quality guidelines: were the vision quality guidelines applied (concise, aligned with mission, imaginable, no buzzwords)?
Document artifact principles: were YAGNI, DRY, and conciseness followed (spec §4)?

Acceptance test

Can the reader understand what kind of long-term future the project is trying to create, and see that it supports the mission?

If no: the vision is incomplete or misaligned. Refine and re-check against the mission. If yes: the vision is complete. Continue the handoff or stop.

Examples

Example 1: Defining a vision when a mission already exists

Context: the mission is "We exist to give engineering teams a single, reliable way to deploy services from code to production." The user asks to define the vision.

Process: elicit a 2–5 year goal, such as "Every team can deliver to production in 5 minutes with a single click, with full audit and rollback." Draft the vision; check whether it supports the mission. The user confirms. Write to docs/project-overview/vision.md。

Result: the vision is persisted; hand off to define-north-star(e.g., "number of successful deployments within 5 minutes per week") or design-strategic-goals。

Example 2: Mission not yet defined (edge case)

Context: the user asks to "define our vision", but no mission document exists.

Process: ask whether to assume a purpose from the README or context, or suggest running define-missionfirst. If the user agrees to continue, note the assumed purpose in the vision document; draft the vision and confirm it with the user. Persist; suggest adding the mission later to complete the strategy chain.

Result: the vision is persisted, with an optional "assumed purpose" note; the user can later run define-mission to complete the chain.