bizspec-refine

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 の前に実行される unit
• link.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 を埋める
effort:
  duration: 0.5      # 1回あたりの所要時間（時間単位、フィボナッチ: 0/0.25/0.5/1/2/3/5/8/13/21）
  frequency: 4       # 月間実行回数（1以上の整数）

# 自動化の現状と難易度が分かるとき → automation を埋める
automation:
  difficulty: low | medium | high                          # 自動化の技術的難しさ
  status: manual | partially-automated | automated         # 現在の対応状況

# status: deprecated のときのみ
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 は以下の順で試し、成功した方法を使う。

1. bizspec validate <プロセス名> — CLI がインストール済みの場合
2. python3 -m bizspec.cli validate <プロセス名> — BizSpec リポジトリ内で作業している場合
3. 手動検証 — 上記がいずれも使えない場合、以下を自分でチェックする：
   • 必須フィールド（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 があること）

進め方

新規プロセスの場合

1. 不明な点があれば確認してから分解を開始する。曖昧な部分・矛盾・前提不明な箇所は積極的に掘り下げて質問する。すでに明確な情報については質問しない
2. 分解結果を YAML で提示し、core: undetermined の unit についてユーザーに確認する
3. ユーザーの回答を反映して YAML を確定する
4. 各 unit の失敗モードを掘り起こす（rule の充実） YAML 提示後、unit ごとに以下を聞く（まとめて聞いてもよい）:
   • 「このステップで一番よくある失敗・詰まりポイントは何ですか？」
   • 「新しい人がここで間違えやすいことは？」
   • 「緊急時・特定の相手・特定の時期など、手順が変わるケースはありますか？」 得られた回答を rule に追加する。既存の一般論より具体的な内容が出たら差し替えを提案する。
5. 粒度の調整（分割 or 統合）の提案は必要に応じて行う
6. すべての unit が確定したら bizspec/ に保存する
7. 保存後に検証を実行し、結果をユーザーに報告する（「検証方法」セクション参照）

既存プロセスへの unit 追加・変更の場合

1. bizspec list <プロセス名> で現在の unit 一覧を把握する
2. 必要なら既存 unit ファイルを読み込んでフロー構造を確認する
3. 変更の種類に応じてコマンドを使い分ける：
   • unit の追加: bizspec new でスケルトンを生成し、内容を埋める。隣接 unit の link.up/down は手動で更新する
   • unit の名前変更: bizspec rename <process> <old> <new>（link 参照を自動更新）
   • unit の削除: bizspec rm <process> <unit>（フロー分断が検知された場合はユーザーに確認してから --force）
4. 保存後に検証を実行し、結果をユーザーに報告する（「検証方法」セクション参照）

検証後のエラー対応

エラー種別	対応
link の双方向不整合（A.down に B があるが B.up に A がない）	どちらのリンクが誤りかを判断できないため、ユーザーに選択肢を提示して確認する（例:「①B.up に A を追加する ②A.down から B を削除する、どちらが正しいですか？」）。確認後に修正して再検証
link 参照先が存在しない（タイポ等）	候補ファイル名と照合して一意に特定できれば自動修正、できなければユーザーに確認
必須フィールド欠落・core / executor.type の値不正	原因を示してユーザーに確認（値の選択が必要なため）
その他	原因を示してユーザーに確認