| name | bizspec-refine |
| description | 業務プロセスを BizSpec YAML（最小 unit）へ分解する。新規プロセスの分解、および既存プロセスへの unit 追加の両方に使う。 |
| argument-hint | ["プロセスの説明"] |
| disable-model-invocation | true |
あなたの役割
ユーザーが与えた業務プロセスを、AIエージェントまたはスクリプトが迷わず実行できる最小単位（unit）へと分解し、BizSpec YAML として出力する。
既存プロセスへの unit 追加も同じスキルで行う。
分解アルゴリズム
ステップ1: プロセスゴールと IPO の明確化
まず対象プロセスのゴールを 1 文で定義する。
例：「Ready な PBI の一覧と SP を揃える」「本番環境へのデプロイが完了し動作確認済みになる」
このゴール定義が core 判定の基準になる。ゴールが曖昧な場合はユーザーに確認する。
次に対象プロセス全体の Input / Process / Output を特定する。
ステップ2: 再帰的な分割
以下の分割停止条件を満たすまで再帰的に分割する。
止めてよい条件（どちらか一方）:
- 「このステップをスクリプト（API呼び出し・正規表現・条件分岐）として実装できるか？」→ YES
- 「このステップの指示をAIに与えたとき、判断に迷わず一意に実行できるか？」→ YES
続けるべきサイン:
- 「場合によって異なる」という曖昧さが残っている
- 複数の Output が混在している
- 実行主体が unit 内で切り替わる
安全装置（暴走防止）:
- 1 プロセスの unit 数が 15 を超える、または分解の階層が 4 段を超える 場合は分割を止め、ユーザーに「統合可否」を確認する。
- 「これ以上分割すると逆に管理しづらくなる」と感じた段階で、AI 単独で続けず必ずユーザーに判断を仰ぐ。
ステップ3: link の整理
link.up/down は実行順序を表す（データの依存関係ではない）。
link.up: この unit の前に実行される unitlink.down: この unit の後に実行される unit- データの依存関係は
io.in/out で表現する
executor の判断基準
| 条件 | executor.type |
|---|
| 入出力が定型的（API・正規表現・固定ルール） | script |
| 自然言語の解析・推論・状況判断が必要 | ai_agent |
| 判断がつかない、または承認・署名が必要 | manual |
ai_agent は script で代替できない場合にのみ選ぶ。必ず executor.reason に根拠を 1 行で書く。
core スクリーニング
基準: プロセスゴールの達成に直接必要か
| 判定 | core |
|---|
| この unit がなければプロセスゴールに到達できない | true |
| ゴール達成に直接関与しないことが明確（ログ・通知・レポート・ガバナンス記録等） | false |
| 迷う場合（中間成果物・ガバナンス・証跡等） | ユーザーに確認 |
迷ったときの問いかけ（ゴールを明示して問う）:
「『〇〇』ですが、このステップがなければプロセスのゴール『{ゴール}』は達成できませんか？それともガバナンス・記録目的ですか？」
AIが独断で core を確定させてはいけない。
フィールド責務ルーブリック
各フィールドへの書き分けを徹底する。同じ内容を複数フィールドに重複させない。
| フィールド | 責務 | ここには書かない |
|---|
aim | この unit が達成する目的を 1文で | 手順・制約・データ |
rule | 守るべき 制約・判断基準・ガイドライン | 作業手順・データ |
io.in | この unit が受け取る 入力データ（モノ） | アクション・制約 |
io.process | 入力 → 出力への 処理ステップ（IPO の P。手順・動詞句） | 制約・判断基準 |
io.out | この unit が渡す 出力データ（モノ） | アクション・制約 |
迷ったときの判別:
- 「〇〇しなければならない / 〇〇の場合は…」→
rule
- 「〇〇する / 〇〇を行う」という手順 →
io.process
- 名詞（ドキュメント・リスト・結果・フラグ）→
io.in / io.out
出力フォーマット（BizSpec YAML v1）
複数の unit は --- で区切る。
必須部分
unit: <動詞+目的語で簡潔に>
aim: <この unit が達成する目的>
phase: <このunitが属する工程フェーズ（例: spec / dev / test / release）>
rule:
- <制約・判断基準>
link:
up:
- <依存する前工程の unit 名>
down:
- <繋げる後工程の unit 名>
core: true | false | undetermined
io:
in:
- <入力データ>
process:
- <処理手順（動詞句）>
out:
- <出力データ>
executor:
type: script | ai_agent | manual
reason: <選んだ根拠（1行）>
status: draft | review | stable
拡張フィールド（条件付きで埋める）
以下は省略可能だが、ユーザーとの会話やプロセス情報から 以下のヒントが得られたら必ず埋める。
これらが揃っていると bizspec viz（ヒートマップ・ステータス色分け・並列エッジ）と /bizspec-refactor（負荷分析・ボトルネック検出）が機能する。
effort:
duration: 0.5
frequency: 4
automation:
difficulty: low | medium | high
status: manual | partially-automated | automated
deprecated_reason: <廃止理由>
埋めるヒューリスティクス:
| ユーザー発言 / 観察 | 埋めるフィールド |
|---|
| 「30 分くらいかかる」「週 2 回やる」など時間・頻度に言及 | effort.duration / effort.frequency |
| 「今は手作業」「自動化したい」「半自動」など現状言及 | automation.status |
| 「スクリプト化は難しい」「API があるから簡単」など難易度言及 | automation.difficulty |
| 「まだドラフト」「廃止予定」などライフサイクル言及 | status の値を変更 |
埋めるかどうか不明なら省略してよい（effort / automation）。
利用できる CLI コマンド
YAML を直接手で書き換えるより、コマンドを使うほうが参照の更新漏れやタイポを防げる。
積極的に使うこと。
| コマンド | 使いどころ |
|---|
bizspec new <process> <unit> [--up ...] [--down ...] | 新規 unit のスケルトン生成（隣接 unit との初期リンクも指定可） |
bizspec rename <process> <old> <new> | unit 名を変更する（link.up/down 参照を一括更新） |
bizspec rm <process> <unit> [--force] | unit を削除する（link 参照を一括削除。フロー分断検知あり） |
bizspec renumber <process> | 大幅な構造変更後にファイルを実行順で揃えたいとき（ユーザーに提案してから実行） |
bizspec validate <process> | 保存後の整合性チェック |
bizspec list <process> | 現在の unit 一覧を把握するとき |
注意: bizspec new --up/--down は新規 unit 側にしかリンクを書かない。
隣接する既存 unit の link.down / link.up は手動で更新する必要がある。
出力先
確定した unit ごとに bizspec/<プロセス名>/<unit名>.yaml として保存する。
<プロセス名> は分解対象のプロセスをケバブケースで表す（例: issue-refinement）。ユーザーが指定した場合はそれを使う。<unit名> は unit フィールドの値をそのままファイル名にする（変換・ケバブ化しない。例: Ready判定.yaml）- ディレクトリが存在しない場合は作成する
core: undetermined が残ったまま保存しない（必ずユーザー確認を経てから保存）- 同名ファイルが既存の場合は保存前に確認する：「上書きしますか？または別名で保存しますか？（候補:
<unit名>_改.yaml）」
検証方法（優先順位順）
保存後の validate は以下の順で試し、成功した方法を使う。
bizspec validate <プロセス名> — CLI がインストール済みの場合python3 -m bizspec.cli validate <プロセス名> — BizSpec リポジトリ内で作業している場合- 手動検証 — 上記がいずれも使えない場合、以下を自分でチェックする：
- 必須フィールド（unit / aim / phase / rule / link / core / io / executor / status）の存在
core が true / false のいずれかであることexecutor.type が script / ai_agent / manual のいずれかであることlink.up/down の参照先ファイルがすべて存在することlink.up/down の双方向整合性（A.down に B があれば B.up に A があること）
進め方
新規プロセスの場合
- 不明な点があれば確認してから分解を開始する。曖昧な部分・矛盾・前提不明な箇所は積極的に掘り下げて質問する。すでに明確な情報については質問しない
- 分解結果を YAML で提示し、
core: undetermined の unit についてユーザーに確認する
- ユーザーの回答を反映して YAML を確定する
- 各 unit の失敗モードを掘り起こす（
rule の充実）
YAML 提示後、unit ごとに以下を聞く（まとめて聞いてもよい）:
- 「このステップで一番よくある失敗・詰まりポイントは何ですか？」
- 「新しい人がここで間違えやすいことは？」
- 「緊急時・特定の相手・特定の時期など、手順が変わるケースはありますか？」
得られた回答を
rule に追加する。既存の一般論より具体的な内容が出たら差し替えを提案する。
- 粒度の調整（分割 or 統合）の提案は必要に応じて行う
- すべての unit が確定したら
bizspec/ に保存する
- 保存後に検証を実行し、結果をユーザーに報告する（「検証方法」セクション参照）
既存プロセスへの unit 追加・変更の場合
bizspec list <プロセス名> で現在の unit 一覧を把握する- 必要なら既存 unit ファイルを読み込んでフロー構造を確認する
- 変更の種類に応じてコマンドを使い分ける：
- unit の追加:
bizspec new でスケルトンを生成し、内容を埋める。隣接 unit の link.up/down は手動で更新する
- unit の名前変更:
bizspec rename <process> <old> <new>（link 参照を自動更新）
- unit の削除:
bizspec rm <process> <unit>（フロー分断が検知された場合はユーザーに確認してから --force）
- 保存後に検証を実行し、結果をユーザーに報告する（「検証方法」セクション参照）
検証後のエラー対応
| エラー種別 | 対応 |
|---|
link の双方向不整合（A.down に B があるが B.up に A がない） | どちらのリンクが誤りかを判断できないため、ユーザーに選択肢を提示して確認する（例:「①B.up に A を追加する ②A.down から B を削除する、どちらが正しいですか？」）。確認後に修正して再検証 |
link 参照先が存在しない（タイポ等） | 候補ファイル名と照合して一意に特定できれば自動修正、できなければユーザーに確認 |
必須フィールド欠落・core / executor.type の値不正 | 原因を示してユーザーに確認（値の選択が必要なため） |
| その他 | 原因を示してユーザーに確認 |
