---
name: beacon-vision
description: ふわっとしたアイデアを対話で精緻化し、構造化されたプロジェクトビジョンとして`project-vision` COREドキュメントに記録する。フォーム入力ではなく、Socratic対話で6セクション（大目的・ターゲット・問題・成功基準・制約・やらないこと）を自然に埋める。
version: 0.1.0
triggers:
  - /beacon-vision
  - ビジョンを作りたい
  - プロジェクトビジョン
  - 何を作るか整理したい
---

# Beacon Vision

> ふわっとしたアイデアを対話で精緻化し、構造化ビジョンとして記録する。フォーム入力ではなく対話駆動。

## 文章の書き方 (Beacon 全体の哲学)

Beacon に書き込む全ての文章 (task / マイルストーン / Operation / コミット / PR / レビュー / ドキュメント / ノート / セッションログ / リリース / デプロイ) は、**非開発者を含む読み手** が読めるように書く。これは Skill ごとの方針ではなく Beacon プロジェクト全体の哲学。

### 守ること

1. **読み手目線 1 行から始める**: 「何が嬉しいか」「何が困るか」をユーザー体験の言葉で。技術用語ではなく価値で書く
2. **横文字 3 段階**:
   - そのまま OK: 固有名詞 (`Firestore` / `pipx` / `MCP` / `Tauri` / `WebSocket`)
   - 初出時に日本語注: 技術概念 (`allowlist (= 許可リスト)` / `opt-in (= 個別許可)` / `subcollection (= 子コレクション)`)
   - 日本語化が望ましい: 一般概念 (configure → 設定 / receiver → 受信側 / audit → 監査 / hit → 一致 / install → 設置 / merge → 取り込み / deploy → 配置)
3. **ID 参照には文脈**: `e-XXXX` / `UC?` / `ms-XX` は初出に必ず『何の話か』1 行添える。例 ✗「e-1140 の AC のうち」→ ✓「e-1140 (自動応答の受信側挙動を hook で扱う) の受入条件のうち」
4. **尻切れトンボ禁止**: 主語と述語を省略しない、論理関係を明示

### Self-review (生成直後に必ず)

文章を書いた直後、自分で読み返して以下を自問:
- (a) 読み手 (非開発者を含む) は 1 度読んで意味が取れるか?
- (b) 一般概念の横文字 (configure / receiver / audit / hit / install / merge / deploy 等) が残ってないか?
- (c) ID 参照に『何の話か』1 行添えたか?
- 違反していたら書き直し。enforce ではないが必須の self-check。

### 詳細

詳しい原則と例 (病理の typology / 例外ケース / 良い例・悪い例) は CORE doc `entry-writing-principle` (doc_id `F3ZkqT0pKS6JpR8dn70n`) 参照。ただし本 Skill では上記 4 項目を **常に top of mind** で適用する (CORE 参照は補足、principal は本文埋め込み)。

---

## 起動ポリシー (重要、CORE doc `PU9HG2IVQdW3tLiAJvix` / `4AS5ehyJc8mGU1gsiFvz` 準拠)

このSkillは **ユーザーが明示的に呼んだ時だけ動く**。`/beacon-init` などからの **自動チェーンはしない**。

- Beacon の北極星 (Philosophy) は「最低限の情報でまずアウトプット、FB で質を上げる」
- vision の 6 セクション対話は構造化が欲しくなったユーザーのための機能 (default off)
- 新規 init 後は `/beacon-roadmap` (minimal) → 即実装、が default
- 「ビジョン整理したい」「ターゲットや成功基準を詰めたい」とユーザーが望んだ時にだけ価値を出す

## 前提条件チェック

Bash ツールで以下を実行（cwd=$PROJECT_DIR、または現在のcwd）:
```bash
beacon-find-root >/dev/null && echo "OK" || echo "NO_BEACON"
```
- `NO_BEACON` の場合、このSkillは何もせず終了する。

**重要**: 以降の Bash 呼び出しはすべて `cwd=$PROJECT_DIR` を指定する（/beacon-init から呼ばれた場合、Claude Code の cwd と異なる可能性）。

## Step 0a: 既存ドキュメントの確認

```bash
beacon doc show project-vision 2>/dev/null
```

既に存在する場合、確認:
```
プロジェクトビジョンドキュメントがあります。

[既存内容のサマリーを2-3文で]

今回は:
  1) 既存を更新する（変えたい部分・追加したい部分を会話で話す）
  2) ゼロから書き直す
  3) 何もしない

どうしますか？
```

ユーザーが「2」または「ゼロから」を選んだ場合、または存在しない場合は Step 0b に進む。

## Step 0b: モード判定（Fresh / Existing）

並列に project state をスキャン:

```bash
# 既存コミット数
git log --oneline 2>/dev/null | wc -l | tr -d ' '
# README の有無と内容
cat README.md 2>/dev/null | head -10
# package.json / pyproject.toml description
cat package.json 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('description',''))" 2>/dev/null
```

### モード判定基準

| 条件 | モード |
|---|---|
| commits >= 10 + README または description あり | **Existing**（成熟リポ向け、直接質問スタイル） |
| 上記以外 | **Fresh**（新規向け、Socratic スタイル） |

判定結果を `$VISION_MODE = Fresh / Existing` として内部保持。

---

## Step 1-Fresh: オープニング（Fresh モード）

**フォーム式の質問は禁止。** 「大目的は？」「ターゲットは？」のような直接質問は **絶対にしない**。

代わりに、こう切り出す:
```
やりたいこと、つくりたいもの、変えたいこと——思いついたまま話してください。「○○みたいなやつ」「△△をなんとかしたい」くらいの粒度で大丈夫です。一緒に少しずつ形にしていきましょう。
```

ユーザーの最初の発言を待つ。

## Step 1-Existing: オープニング（Existing モード）

既存の README / description から **大目的を推定** し、提示する:

```
このリポジトリの README から、こう理解しました：

【大目的】
[READMEの先頭 or package.json description から抽出した1〜2文]

合ってますか？間違ってたら教えてください。違うところを直したあと、
ターゲット・成功基準・スコープなどを順に整理していきましょう。
```

ユーザーが「あってる」「OK」等で承認、または修正を入力したら次へ。

## Step 2: 対話駆動の精緻化（モード別）

### 共通: 6セクション（内部追跡用、ユーザーには見せない）

```
vision_draft = {
  "大目的":         "<unknown | vague: ... | fill: ...>"
  "ターゲット":     "<unknown | vague: ... | fill: ...>"
  "問題":           "<unknown | vague: ... | fill: ...>"
  "成功基準":       "<unknown | vague: ... | fill: ...>"
  "制約":           "<unknown | vague: ... | fill: ...>"
  "やらないこと":    "<unknown | vague: ... | fill: ...>"
}
```

Existing モードでは `大目的` は Step 1-Existing で承認済み（推定 + ユーザー確認）。

### Step 2-Fresh: Socratic 対話

#### 対話原則

1. **一度に1問だけ** ユーザーが処理しきれない量を投げない
2. **最も曖昧 or 重要な空白を掘る** unknown ＞ vague の順で優先
3. **ユーザーの言葉を使う** 専門用語・PM用語（KPI、ペルソナ、スコープ等）は使わない
4. **解決策に飛ばない** 問題理解に留める
5. **自然な角度から聞く** 「ターゲットは？」ではなく「これ困ってるの自分だけ？周りもいる？」
6. **「わからない」への対応** 選択肢を2〜3個提示して反応をもらう

#### Socratic prompts

| 掘りたい部分 | 自然な聞き方の例 |
|---|---|
| 大目的 | 「なんでこれやりたくなった？」「これがあったら世界どう変わる？」 |
| ターゲット | 「自分だけが困ってる？周りも？」「思い浮かべてる人いる？」 |
| 問題 | 「具体的にどういうとき詰まる？」「一番イラッとした瞬間は？」 |
| 成功基準 | 「もし完璧に動いたら、どんな流れになってると嬉しい？」 |
| 制約 | 「お金・時間・技術で縛りある？」 |
| やらないこと | 「逆にこれだけは絶対やりたくないこと、ある？」 |

10〜15ターン程度で6セクション中 4 以上が fill になる目安。

### Step 2-Existing: 直接質問 + ギャップ埋め

開発者前提なので **直接質問でOK**。専門用語も使ってよい。  
大目的は承認済みなので、残り5セクションを順に直接質問する。

#### 質問の進め方

1問ずつ、ただし Fresh モードより直接的に:

| 順番 | 質問例 |
|---|---|
| 1. ターゲット | 「想定ターゲットは具体的にどんな人？自分だけ／個人開発者／社内チーム など、思いつくユーザー像を教えてください」 |
| 2. 問題 | 「そのユーザーが今直面している具体的な問題・痛みは何ですか？」 |
| 3. 成功基準 | 「成功したと判断できる状態は？定量的でも定性的でもOK。例: 月間アクティブ100人 / 自分が継続利用できる」 |
| 4. 制約 | 「制約は？技術スタック・予算・運用上の縛りがあれば。なければ "特になし"」 |
| 5. やらないこと | 「スコープ外として明示しておきたいことは？混同されがちだけど対象外、というもの」 |

5〜6ターン目安で全セクション埋まる。

### 推測でセクションを埋めるとき（両モード共通）

ユーザーの発言から推測可能な部分は、内部状態を「推測:〜」として埋めてOK。  
**後で確認フェーズで明示する**（推測した、と分かるように）。

## Step 3: 終了条件の判定

以下のいずれかを満たしたら Step 4（確認フェーズ）に進む:

- 6セクション中 **4つ以上** が `fill` 状態（推測含む）
- ユーザーが「もうこれくらいで」「だいたいわかったでしょ」と打ち切る発言をした
- 同じ部分を掘ろうとして、ユーザーから新しい情報が出てこない状態が2ターン続いた

## Step 4: ビジョン draft 構築 + 即記録 (Act first)

CORE doc `AeN9aPpjvh6URTQlFmb6` の「Act first, confirm next-step」に従い、**事前確認なしでビジョンを記録する**。`beacon doc update project-vision` で後から編集可能なので、まず形にして見せるほうが対話を引き伸ばすより goal への最短経路。

これまでの会話を踏まえ、構造化された 6 セクションの draft を内部生成 → そのまま Step 5 で `beacon doc add` 実行。

```
# プロジェクトビジョン

## 大目的
[1〜2文]

## ターゲットユーザー
[具体的な像を1〜2文]

## 解決する問題
- ...

## 成功基準
- ...

## 制約・前提
- ...

## やらないこと
- ...
```

事前に「これでいいですか？」とは聞かない (CORE doc アンチパターン)。記録後に短い報告 + 次手提案。

**ms-68 / e-1643 補足 (= entry-writing principle の draft 表示例外)**: ビジョン doc は本文全体を事前 draft として書き上げる性質上、書き込み前のユーザー touchpoint を 1 つ挟むと CORE doc `AeN9aPpjvh6URTQlFmb6`「Act first, confirm next-step」と衝突する。そのため beacon-vision Skill は **「Act first 原則の制約下にある自律パス」として扱い、書き込み前の draft 提示は省略**。代わりに以下 2 点で原則違反を防ぐ:

1. **Step 4 で内部 draft を生成し終えた直後に self-review (4 原則) を必須化**: 読み手目線 1 行 / 横文字 3 段階 / ID 参照に文脈 / 尻切れトンボ禁止 をその場で 1 度自問し、違反があれば書き込み前に直す。特に「ターゲットユーザー」section は非開発者を含む読み手描写なので、その層に伝わる言葉になっているかを必ず点検する
2. **書き込み後は `beacon doc update project-vision` で forward-only に直せる**: 違反に気付いたユーザーは過去 doc を遡及修正せず、その場で update を指示する

→ ms-68 SPEC (`HQvN4Gimw3n1UKwrk6o1`) の「自律パスは self-review のみ」と整合。beacon-spec / beacon-log と同じ扱い。

## Step 5: 書き込み (Act)

**heredoc は必ず quoted EOF (`<<'EOF'` または `<< 'EOF'`) を使う**: 非引用 `<<EOF` だと shell が中身の backtick (`` ` ``) を command substitution として展開し、本文が silent corrupt する (2026-06-10 LPS dogfood で観察された病理、e-1401)。

Bash ツールで実行:

```bash
beacon doc add "プロジェクトビジョン" --scope core --id project-vision --stdin <<'EOF'
# プロジェクトビジョン

## 大目的

[Step 4 で確定した内容]

## ターゲットユーザー

[Step 4 で確定した内容]

## 解決する問題

[Step 4 で確定した内容]

## 成功基準

[Step 4 で確定した内容]

## 制約・前提

[Step 4 で確定した内容]

## やらないこと

[Step 4 で確定した内容]
EOF
```

**既存ドキュメントを更新する場合** (Step 0 で「更新」を選んだ場合):
```bash
echo "..." | beacon doc update project-vision --stdin
```

## Step 6: 次のステップ案内（モード別）

### Fresh モード → /beacon-roadmap にチェイン

保存先の案内を **mode 別に分岐**:

**cloud mode の場合**:
```
プロジェクトビジョンを記録しました。
🔗 https://beacon-ai.dev/?project=<project_id>#doc/project-vision
   (Web UI の Documents タブ → 「プロジェクトビジョン」)
   気になれば見てください、推測で埋めた部分は `beacon doc update project-vision` で直せます。

次は、このビジョン (大目的) に到達するまでの道のりを 3〜7 個のマイルストーンに分けて整理します
(マイルストーン = 「ここまで進んだら一区切り」と呼べる単位)。
順序や依存関係も一緒に考えて、最初のマイルストーンから着手できる状態を作ります。

進めますか？ (内部的には /beacon-roadmap Skill を起動します)
```

**local mode の場合** (Beacon Desktop App 起動中):
```
プロジェクトビジョンを記録しました。
📄 Beacon Desktop App の Documents タブ → 「プロジェクトビジョン」 で確認できます。
   気になれば見てください、推測で埋めた部分は `beacon doc update project-vision` で直せます。

次は、このビジョン (大目的) に到達するまでの道のりを 3〜7 個のマイルストーンに分けて整理します
(マイルストーン = 「ここまで進んだら一区切り」と呼べる単位)。
順序や依存関係も一緒に考えて、最初のマイルストーンから着手できる状態を作ります。

進めますか？ (内部的には /beacon-roadmap Skill を起動します)
```

`project_id` は `.beacon/cloud.json` の `project_id` フィールドから取得。`<project_id>` プレースホルダは実値で置換する。

ユーザー承認なら `/beacon-roadmap` を起動。

**重要 (CORE doc `AeN9aPpjvh6URTQlFmb6` 準拠)**:
- メッセージは必ず「**何をするか**」を平易な言葉で述べてから、技術用語 (Skill 名) は補足として括弧内に置く
- Beacon 独自用語 (マイルストーン、SPEC、Operation 等) は **初出時に短い説明を併記**
- 上記の hand-off テンプレでは「マイルストーン = 『ここまで進んだら一区切り』と呼べる単位」のような形で初出説明している

### Existing モード → /beacon-session-start に直接チェイン（roadmap スキップ）

```
プロジェクトビジョンを記録しました。

既存リポジトリなので、ロードマップは過去の開発履歴から構造化します。
→ /beacon-session-start で Project Archaeology が走ります
```

`/beacon-roadmap` を **スキップ**して、`/beacon-session-start` を `cwd=$PROJECT_DIR` で起動。

## 制約

- **対話スタイルはモードに従う**:
  - Fresh: Socratic、間接質問、ユーザーの言葉を使う
  - Existing: 直接質問OK、開発者前提の表現使ってよい
- **フォーム入力は禁止**: 「大目的を1文で書いてください」は両モードでNG
- **一度に1問**: ユーザーが処理しきれない情報量を投げない
- **解決策に飛ばない**: 「こういうツール作るんですね？」のような決め付けをせず、問題理解に集中
- **すべての Bash 呼び出しで `cwd=$PROJECT_DIR` を指定**（/beacon-init から呼ばれた場合に必須）
- **推測した部分は明示**: AIが補完した部分は「推測」と書き、ユーザーが訂正できる状態にする
