Writing Spec Skill

Brainstorming ノートを入力として、軽量 Markdown 形式の Spec ファイルを生成する skill です。本プロジェクトのワークフロー (docs/workflow.md) における Spec ステージを担います。

用語: 「Project Phase」「Workflow Stage (ステージ)」「Release Phase」「Spec」の定義は docs/glossary.md を参照してください。

1. 役割と位置づけ

ワークフロー上の位置:

Brainstorming → [DAG 構築 (複数 Spec 時)] → [writing-spec (本 skill)] → Spec Review → [DAG 構築 (確定)] → Isolate → ...

Brainstorming ノートで解像度の上がった要件を、後続の Plan / Implement ステージが参照可能な構造化された Spec ファイルに落とし込むことが役割です。単なる転記ではなく、実装可能な粒度への具体化 を目指します。

2. 起動トリガー

以下のフレーズで自動的に起動してください。

• 「Spec 書いて」「Spec 作って」
• 「仕様書作って」「仕様書起こして」
• 「Spec 化して」「Brainstorming を Spec に起こして」
• 「ブレストの内容を仕様にして」

また、以下の状況で 自動起動を提案 してください。

• specs/<spec-name>.brainstorm.md に status: brainstorming-complete が付与され、対応する specs/<spec-name>.md が未作成
• ユーザーから Spec ステージへの移行承認を得た直後 (brainstorming skill の完了判定基準 3 を満たした後)

3. 前提条件の確認

skill 起動直後、以下を必ず確認してください。

• 入力 Brainstorming ノートの存在 (specs/<spec-name>.brainstorm.md)
• frontmatter status が brainstorming-complete であること
• 対応する specs/<spec-name>.md がまだ存在しないこと (上書き防止)
• specs/dag.md の存在確認 (単一 / 複数にかかわらず必須、2026-04-22 改修)

前提条件を満たさない場合、以下のエラー対応を行ってください。

• Brainstorming ノート未存在: 「Brainstorming ステージが完了していません。先に brainstorming skill を起動してください」と返して終了
• status が brainstorming-complete でない: 現在の status を表示し、Brainstorming ステージが完了するまで待つよう指示
• spec.md が既に存在: 「既存 Spec の編集」か「新規作成 (上書き)」のどちらかを明示的に確認、ユーザー承認なしに上書きしない

4. Spec ファイルの章構成

生成する specs/<spec-name>.md の章構成 (7 章):

---
name: <spec-name>
status: spec-complete
created: YYYY-MM-DD
brainstorming_archive: specs/archive/<spec-name>.brainstorm.md
depends_on: [...]          # Brainstorming ノートから引き継ぎ (ない場合は省略)
parallel_group: N          # Brainstorming ノートから引き継ぎ (ない場合は省略)
---

# Spec: <spec-name>

## 1. 目的

<なぜこの機能 / 変更が必要なのか。ビジネス価値や解決する課題を簡潔に記述>

## 2. スコープ

### 2.1 含むもの
- <今回の Spec で実装・変更する対象 1>
- <対象 2>

### 2.2 含まないもの
- <明示的に除外する項目 1>
- <項目 2>

## 3. 機能要件

### 3.1 <機能名 1>

<機能の詳細な挙動>

**入力**:
- <入力項目と型 / 制約>

**出力**:
- <出力項目と型 / 制約>

**エラーハンドリング**:
- <エラーケースと挙動>

### 3.2 <機能名 2>
<同上>

### 3.X 技術表現の検証ルール (2026-04-24 Phase 6 バッチ 2 (c) learn Try 6.2 改修)

Spec 本文に以下を記載する際は、**必ず 1 例以上を実機で動作検証してから書く** こと。机上設計の regex / shell コマンドは spec-review や Plan 段階で「自分の正規例を受け付けない」等の致命的欠陥として指摘されやすい (Phase 6 バッチ 2 (c) で実際に発生した事例あり)。

- **正規表現**: `bash` の `[[ =~ ]]` / `grep -E` / `awk` 等で 1 正例 + 1 負例を実行して期待動作を確認
- **shell コマンド / パイプライン**: echo / ダミーファイル等で実機実行
- **bash 組み込み機能** (`printf -v` / `BASH_REMATCH` / `declare -A` 等): 最低 1 例の動作確認
- **ANSI エスケープ / 特殊文字**: `cat -v` や `printf %q` で表示確認

検証方法を Spec 本文に含める必要はないが、**検証済み** と暗黙に保証する責任を writing-spec 側が負います。検証未実施のまま Spec に書くと、spec-review の feasibility / consistency 観点で Critical 指摘される可能性が高いです。

## 4. 非機能要件

| 項目 | 要件 |
|---|---|
| パフォーマンス | <応答時間・スループット等> |
| セキュリティ | <認証・認可・データ保護等> |
| 可用性 | <稼働率・障害時の挙動等> |
| 拡張性 | <将来の拡張余地> |
| 保守性 | <ログ / モニタリング / ドキュメント要件> |

## 5. 受け入れ基準 (Acceptance Criteria)

- [ ] <具体的で検証可能な基準 1>
- [ ] <基準 2>
- [ ] <基準 3>

## 6. 非対象 (スコープ外)

- <明示的に含めないもの 1 (理由付き)>
- <2>

## 7. リスクと緩和策

### 7.1 <リスク 1>
- **内容**: <リスクの具体的内容>
- **緩和策**: <対応方針>

### 7.2 <リスク 2>
<同上>

5. Brainstorming ノートからの統合

Brainstorming ノートの各セクションを Spec ファイルの対応セクションに統合します。単なる転記ではなく、実装判断に必要な粒度まで具体化 してください。

5.1 セクション対応表

5.2 具体化のガイドライン

Brainstorming ノートは要件レベル、Spec ファイルは実装判断可能レベルで記述します。具体化の例:

• Brainstorming: 「在庫が 10 個を切ったら通知」
• Spec: 「在庫数が 10 未満 (< 10) になった瞬間 (在庫更新イベント直後、100ms 以内) に通知をトリガーする。既に 10 未満状態が継続している場合は重複通知しない (last_notified_at フィールドで制御、冷却期間 1 時間)。」

未解決事項はこの段階で 具体化してください。具体化できない場合は Spec Review で相談する前提で「TBD (要議論)」とマークし、status: spec-writing のまま残します。

6. frontmatter の引き継ぎ

Brainstorming ノートの frontmatter から以下を引き継ぎます。

• name: そのまま
• depends_on: そのまま引き継ぎ (未設定なら省略)
• parallel_group: そのまま引き継ぎ (未設定なら省略)

新規に設定する項目:

• status: spec-complete (Spec 書き終わり、Spec Review 待ち)
• created: 当日の日付 (YYYY-MM-DD 形式)
• brainstorming_archive: specs/archive/<spec-name>.brainstorm.md (移動後のパス)

7. Brainstorming ノートの archive への移動

Spec ファイル生成と承認完了後、以下の手順で Brainstorming ノートを archive に移動します。

1. specs/archive/ ディレクトリが存在しなければ作成
2. specs/<spec-name>.brainstorm.md の frontmatter status を archived に更新
3. specs/<spec-name>.brainstorm.md を specs/archive/<spec-name>.brainstorm.md に移動 (git mv 相当)
4. 移動したことをユーザーに報告

7.1 移動しない場合

以下の場合は archive 移動を 行わない でください。

• ユーザーが明示的に「brainstorm.md を残したい」と指示した場合
• Spec 書き出しが途中で中断された場合 (status: spec-writing)
• Spec Review で差戻された場合 (Brainstorming ノートを参照して再編集が必要な可能性)

7.2 archive 移動の意義

• spec-dag-builder skill が再実行された際、specs/archive/ 配下は対象外として扱える (重複解析防止)
• 過去の要件経緯を参照可能な形で保管
• specs/ 配下の見通しを維持 (進行中の Spec のみ表示)

8. 複数 Spec 処理時の DAG 順走査

specs/dag.md は単一 / 複数 Spec にかかわらず常に存在する前提 (spec-dag-builder が 1 ノード DAG も生成、2026-04-22 改修)。本 skill は DAG 順に処理 します。

8.1 処理順序の決定

1. specs/dag.md を読み込み、parallel_group の小さい順にソート
2. 同一 parallel_group 内は、ユーザーと相談して処理順を決定 (通常は名前順または重要度順)
3. status: brainstorming-complete の Brainstorming ノートのみを対象とする (archived / spec-complete 以上はスキップ)

8.2 並列 vs 順次

本 skill は対話型のため、並列起動はせず 順次処理 します。1 つの Spec を書き終えてユーザー承認を得てから次の Spec に進みます。並列化は Phase 5 の orchestrator skill が担当する責務です。

8.3 中断時の状態

複数 Spec 処理の途中で中断した場合、それまでに書き出した Spec は status: spec-complete で保存済み、未処理の Brainstorming ノートは brainstorming-complete のまま残ります。再開時は未処理分のみを対象に本 skill を再起動してください。

9. ユーザー承認フロー

Spec ファイル生成は対話的に進めます。

1. ドラフト提示: Brainstorming ノートから推測・具体化した Spec ドラフトを提示
2. 修正要望の受付: ユーザーから修正指示があれば反映
3. 最終確認: 全 7 章が適切に埋まっているか、受け入れ基準が検証可能か、ユーザーと確認
4. 承認後に保存: specs/<spec-name>.md に保存 + Brainstorming ノートを archive に移動
5. 次ステージへの引き継ぎ: Spec Review ステージに進む旨を伝える

承認なしに spec.md を保存してはいけません。Brainstorming ノートの archive 移動も同様です。

10. 失敗時の対応

以下の状況では、無理に Spec を完成させずユーザーに相談してください。

• 要件が Spec に起こすには曖昧すぎる: Brainstorming ステージへの差戻しを提案
• 受け入れ基準が検証不可能: ユーザーと相談して検証方法を確定してから継続
• リスクの緩和策が思い浮かばない: リスクを明示して Spec Review で対応方針を議論する前提で進行
• 他 Spec との整合性問題を発見: 該当 Spec の書き出しを保留し、全体見直しを提案

11. 次ステージへの自動引き継ぎ (Spec Review)

Spec ファイル生成 + archive 移動 + ユーザー承認がすべて完了したら、`spec-review` skill を自動起動 してください。手動提案ではなく、本 skill の責務の一部として自動呼び出しを行います。

11.1 自動起動の手順

1. 生成した specs/<spec-name>.md のパスをユーザーに提示
2. Spec Review ステージで確認すべきポイント (未解決事項の TBD / リスク緩和策 / 受け入れ基準の検証可能性等) を簡潔にリスト化
3. `spec-review` skill を自動起動 (ユーザーに追加承認を求めない)
4. spec-review 側が specs/<spec-name>.review.md を生成し、verdict (pass / needs-fix / reject) を返す

11.2 複数 Spec を DAG 順に処理する場合

1 Spec ごとに以下を実行します (バッチ化しない)。

1. 当該 Spec の writing-spec 実行 (生成 + archive 移動 + 承認)
2. 即 spec-review 起動 (当該 Spec のレビュー)
3. verdict が pass → 次 Spec の writing-spec へ進む
4. verdict が needs-fix / reject → 当該 Spec のレビュー指摘対応モード (§13) に入り、他 Spec の生成は一時停止

12. 失敗・障害事例 (アンチパターン)

以下を行ってはいけません。

• ❌ Brainstorming ノートを読まずに Spec を書き始める
• ❌ ユーザー承認なしに spec.md を保存する
• ❌ ユーザー承認なしに brainstorm.md を archive に移動する
• ❌ Brainstorming ノートに記述のない内容を勝手に追加する (推測による補完は明示して確認を求める)
• ❌ 受け入れ基準を検証不可能な曖昧な文言にする (例: 「適切に動作する」「高速である」)
• ❌ 未解決事項を放置したまま spec-complete にする (必ず具体化するか TBD マークで Spec Review に持ち込む)
• ❌ 複数 Spec 処理時に DAG 順を無視してランダム処理する
• ❌ specs/dag.md を書き換える (本 skill は読み取り専用、更新は spec-dag-builder の責務)
• ❌ Spec 生成後に spec-review を起動せずユーザーに手動確認を委ねる (§11 自動起動が必須)
• ❌ 動作未確認の regex / shell コマンド / bash 機能を Spec に書く (2026-04-24 Try 6.2、§3.X 検証ルール準拠。spec-reviewer が実機検証で Critical 検出 → 手戻り発生。本バッチ (c) で実際に発生したため明示化)

13. レビュー指摘対応モード

spec-review skill が verdict needs-fix または reject を出した場合、同 skill は本 skill をレビュー指摘対応モードで自動再起動 します。このモードは通常の新規 Spec 生成とは異なり、既存 Spec ファイルへの修正適用が責務です。

13.1 起動判定

以下を引き渡されて起動した場合、本モードとして処理してください。

• 対象 Spec ファイルパス (specs/<spec-name>.md、既に status: spec-complete で存在)
• レビューファイルパス (specs/<spec-name>.review.md)
• 指示文言に「レビュー指摘対応モード」「review.md の指摘項目を反映」等を含む

13.2 処理手順

1. status を spec-writing に戻す: specs/<spec-name>.md の frontmatter status を spec-complete から spec-writing に変更 (レビュー中/対応中の状態であることを明示)
2. review.md を読み込み、指摘を優先度順に整理: Critical → Major → Minor の順に対応リストを作成
3. 各指摘に対して spec.md を修正:

• Critical: 必ず反映 (放置すると実装で手戻り)
• Major: 原則反映。妥当な理由があれば Spec 内にコメントで理由を明記
• Minor: 品質改善。反映推奨だが、優先度や工数を踏まえて省略可

1. ユーザー承認: 修正内容をユーザーに提示、修正方針に問題がないか確認 (spec.md 上書きは承認後)
2. status を spec-complete に戻す: 修正反映と承認が完了したら frontmatter status を spec-complete に戻す
3. spec-review の再レビューをトリガー: 自動再起動される (spec-review §8 / §11 参照)

13.3 循環防止

同一 Spec で 3 回連続して pass にならない場合、本 skill ではなく spec-review 側が自動再起動を停止してユーザーに相談します (spec-review §8.3)。本 skill はレビュー指摘対応モードで呼ばれるたびに、直前の review.md 内容を参照して対応すれば十分です。

13.4 brainstorm.md の archive への影響

レビュー指摘対応モードでは brainstorm.md の archive 移動は再実行しません (既に §7 で archive 移動済)。本モードは spec.md のみを対象とします。

13.5 レビュー指摘対応モードのアンチパターン

• ❌ 既存 spec.md を無視して Brainstorming ノートから再生成する (archive 済の brainstorm.md は参考程度、主たる入力は spec.md + review.md)
• ❌ review.md の Critical 指摘を「反映困難」として省略する (必ず反映するか、ユーザーと議論してから省略判断)
• ❌ status: spec-writing に戻さずに修正を開始する (状態管理の一貫性が崩れる)
• ❌ 修正内容をユーザー承認なしに spec.md に上書きする