# Vision

> Create or update the project vision document

- Skill: `asermax/vision` (Agent Skill)
- Install (CLI): `npx skillmds@latest add asermax/vision`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asermax/vision/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: asermax (https://skillmd.com/u/asermax)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/asermax/vision

---


# Vision Document Workflow

Guide the user through creating docs/planning/VISION.md.

## Context

**You must load the following skills and read the following files before proceeding.**

### Skills
- `katachi:framework-core` - Workflow principles

### Vision document
- `docs/planning/VISION.md` - if it exists

## General Guidance

Follow the collaborative workflow principles from the framework-core skill.

**Vision-specific guidance:**

**Use a scratchpad** - Track state in `/tmp/vision-<project-name>-state.md` (where `<project-name>` is the basename of the current working directory):
- Current section being worked on
- Questions asked and answered
- Gaps identified
- Topics to revisit

## Process

### 0. Check Existing State

If `docs/planning/VISION.md` exists:
- Read current vision document
- Read project state (features, specs, implementation progress if any)
- Summarize current state to user
- Ask: "What aspects need refinement? Or should we review the whole vision?"
- Enter iteration mode as appropriate

If no vision exists: proceed with initial creation

### 1. Understand the Problem

- What problem are you trying to solve?
- Who experiences this problem?
- How do they currently deal with it?

### 2. Research Existing Solutions

Use Task tool (general-purpose agent) to research:
- Existing solutions (commercial and open source)
- Technical approaches (models, frameworks, libraries)
- Known issues with alternatives
- Best practices and patterns

Synthesize findings to inform questions.

### 3. Define Core Workflows

- What are the main things a user will do with this software?
- For each workflow:
  - What triggers this workflow?
  - What's the end result?
  - What are the key steps?

### 4. Set Scope Boundaries

- What MUST be in v1? (included)
- What is explicitly NOT in v1? (excluded)
- Challenge scope creep: "Is this really necessary for v1?"

### 5. Technical Context

- Where does this run? (platform)
- How do users interact with it?
- What external systems does it connect to?
- DETECT: Platform/language/storage choices → prompt for ADR

### 6. Write the Document

- Show draft to user
- Ask for feedback
- Iterate until approved

### 7. External Validation

Dispatch a general-purpose subagent to review the completed vision.

Request structured critique covering:
- **Clarity**: Is the problem, solution, and scope clearly articulated?
- **Completeness**: Are workflows fully specified? Is technical context sufficient?
- **Internal consistency**: Do all sections align? Do workflows solve the problem?
- **Unstated assumptions**: What's implied but not explicit?
- **Scope boundaries**: Is v1 scope realistic? Are exclusions clear?
- **Gaps**: Between problem/workflows, workflows/scope, scope/technical context
- **Edge cases**: What scenarios aren't addressed?

Review subagent findings with user.
Ask: "Should we iterate on any section based on this feedback, or is the vision complete?"

## Decision Detection

When user mentions hard-to-change choices, offer to create ADRs:
- Platform choice → "Should we create an ADR for platform?"
- Language choice → "Should we create an ADR for language?"
- Storage approach → "Should we create an ADR for storage?"
- Model/library choice → "Should we create an ADR for this choice?"

## Workflow

**This is a collaborative process:**
- Ask one question at a time
- Agent proposes, user confirms
- User makes all decisions
- Provide research-backed alternatives
- Never fill gaps yourself
- Iterate until approved