miko.propose

Files (2)

• SKILL.md
• cross_capability_impact_guide.md · guides/

SKILL.md (first lines)

## 入力

```text
$ARGUMENTS
```

入力の形式: `<capability_name> <元ネタ（自由記述）>`

- 例: `/miko.propose order_management トライアル終了時にメール通知を送りたい`
- 例: `/miko.propose notification 未読通知のリマインドを送りたい`
- ケイパビリティ名だけの場合: 元ネタをヒアリングから始める
- 空の場合はエラー: 「⛩️  ケイパビリティ名をお願いいたします（例: `/miko.propose order_management 〜したい`）」

---

## このスキルの役割

人間が持ち込む変更の元ネタ（アイデア・課題・要望）を、対話を通じて構造化されたプロポーザルに仕上げる。

**プロポーザルとは:** ケイパビリティに対する変更提案。ビジネスルールの変更だけでなく、機能仕様・影響範囲・代替案を含む。実装後に「ビジネスルールの変更」セクションだけが business_rules.md に反映される。

**⚠️ 絶対禁止:** このスキルは `business_rules.md` を **読み取り専用** として扱う。propose が直接 business_rules.md を編集・上書きしてはならない。BR への変更はすべてプロポーザルファイルの「ビジネスルールの変更」セクションに記述し、実装スキル（implement / quick-impl）が反映する。

**対話のスタイル:** 機械的な質問リストではなく、自然な会話で進める。ただし確認ポイントは明確に設ける。

---

## 手順

### 1. 入力検証

- `$ARGUMENTS` の先頭ワードからケイパビリティ名を取得し、スネークケースに正規化する
- 残りの部分を元ネタとして記録する

### 2. 既存資料の読み込み

以下のファイルを読み込む。

**指示書（必須）:**
- `.miko/guides/business_rules_guide.md` — ルール記述の原則。判定テストの方法
- `.miko/guides/tone_guide.md` — ユーザーとの対話スタイル。**このファイルの口調・絵文字・出力言語ルールに従うこと**

**実例（品質の基準）:**
- `.miko/examples/business_rules.md` — ルールの書き方・粒度の参考

**システム全体の文脈:**
- `miko/system_high_level_design.md` — システム全体のアーキテクチャ、**コード探索ガイド**
- `miko/glossary.md` — 用語集（存在する場合）

**ケイパビリティの現状（business_rules.md が必須）:**
- `miko/<capability>/business_rules.md` — 現在のビジネスルール。**このファイルが存在しない場合はエラーとして中止する:**
  > ⛩️  `miko/<capability>/business_rules.md` が見つかりません。
  > このスキルは既存の business_rules.md への変更提案を作成いたします。
  > `- 既存コードがある場合: まず /miko.catchup <capability> で business_rules.md を生成してください`
  > `- 新規ケイパビリティの場合: /miko.new-cap <capability> で初期ルールを定義してください`
- `miko/<capability>/high_level_design.md` — 現在の構造（なければスキップ）

### 3. 元ネタのヒアリング

元ネタが十分に具体的であれば（動機・変更内容・スコープが読み取れる）、すぐにステップ 4 に進む。

元ネタが曖昧・不完全な場合、以下の観点で **対話的に** 質問する。一度に全部聞くのではなく、回答に応じて掘り下げる:

- **動機**: なぜこの変更が必要か？ 今何が困っているか？
- **期待する振る舞い**: 変更後はどうなってほしいか？
- **トリガー/アクター**: 誰が・何がきっかけでこの処理が動くか？
- **スコープ**: 何は変えないか？ どこまでが今回の範囲か？
- **エラー時**: 失敗したらどうなるべきか？

**注意:**
- 人間がドメインエキスパートである前提で対話する。技術的な質問ではなく、ビジネス判断に焦点を当てる
- 「〜はどうしますか？」ではなく「〜は A と B がありえますが、どちらが適切ですか？ 私は〜の理由で A を推奨します」のように、選択肢と推奨を提示する
- コードの調査は次のステップで行うので、ここではユーザーの意図の理解に集中する

### 4. 【確認①】理解の確認

ヒアリング内容を「背景・動機」「変更の概要」「スコープ（対象/対象外）」「トリガー/アクター」にまとめて提示し、認識合わせをする。フィードバックがあれば反映して再提示、承認されたら次に進む。

### 5. コード調査

確認①で承認された内容に基づき、関連するコードを探索・精読する。

**探索対象:** `miko/system_high_level_design.md` の **コード探索ガイド** に従い、変更に関連するファイルを探索する。ただし網羅的探索ではなく、**変更に関連する範囲に絞る**。

**探索対象外:** `.miko/` ディレクトリは miko の内部リソースであり、プロジェクトのコードではない。探索・精読の対象にしないこと。

**確認すること:**
- 変更が影響する既存のルール（business_rules.md のルール ID を特定）
- 変更先の既存コードの構造（どこに手を入れることになるか）
- 既存の類似パターン（同じケイパビリティ内の類似処理）
- 新しく必要になるテーブル・カラム・エンドポイント等

**仕様の疑問の確認:** コード調査の過程で仕様上の疑問が浮かんだ場合（例: 既存の振る舞いとの整合、条件分岐の判断など）、ドラフト作成前にユーザーに確認する。AIが仮定を置いてドラフトを書くのではなく、正しい前提で書けるようにする。

### 6. ビジネスルール変更案の策定

`.miko/guides/business_rules_guide.md` の判定テストを適用しながら、変更案を策定する。

**⚠️ 既存 BR の構造と、触らないルールには手を入れない:** business_rules.md の現状の構造（フラットか、`2.1 / 2.2` を持つか、ビジネスポリシーセクションがあるかなど）と、**この proposal で改訂・廃止しない既存ルールの本文**には手を入れない。新規ルールは既存ファイルの構造に合わせて配置する。ユーザーから明示的な移行依頼がない限り、現在の基準（文字数・語彙規律・新構造）に合わせる再整形は行わない。一方、この proposal で **改訂・新設するルール** には現在基準（文字数・語彙規律・判定テスト等）を適用する。

**⚠️ 粒度の原則: 提案の詳細度に引きずられない**

提案が細かくても、BR の粒度は変わらない。ユーザーが UI の話をしていたり、実装レベルの詳細を語っていたりするほど、このフィルタを意識して適用すること。

ガイドの判定テスト（却下した代替案 / ビジネス定義）を全候補に適用するのに加え、ガイドの **「よくあるアンチパターン」** に当たっていないか必ず確認する。

- **「〜したい」が出たら**: ユーザー要望の言い換えは BR ではない。要望の背後にある **条件・閾値・除外規則・対象範囲** だけが BR 候補
- **UI・通知・出力の話が出たら**: 「画面に〜を表示する」「〜のときメールを送る」「〜を記録する」のような実装をなぞっただけの記述は BR ではない。判断（**いつ・何回・どの条件で除外するか**）が乗っているもの **だけ** が BR
- **細かい仕様の話が出たら**: 「実装や UI が変わっても、この記述は変わらないか？」を問う。No なら BR ではない
- **BR の数の目安**: 通常の機能追加で新設 BR が 5 本を超えたら粒度が細かすぎる可能性が高い。各ルールに「却下した代替案」テストを再適用し、**「やらない／別の条件にする」以外の合理的な代替案が書けるか** を厳しく問う

判断軸は「却下した代替案」テストに集約する。コードに書いてあるかどうかは判断軸にならない（BR は最終的にコードで表現される）。コードに表れていても、別の選択肢がありえた判断であれば BR として残す。

候補から外したものは BR ではなく **機能仕様セクション** に書く。「BR から外したから消える」ではなく「書く場所を変える」だけ。

**新設するルール:**
- 元ネタから導かれる新しいルールを特定
- 判定テスト（「却下した代替案テスト」「ビジネス定義テスト」）を適用
- 既存のカテゴリ・プレフィックスに従って ID を採番（例: 既存の AI-04 の次なら AI-05）

From studyplus/miko, MIT.

More from studyplus/miko