Replace strategy

Replace Strategy

「仕様を変えずにアプリケーションをリプレイスする」作業の入口を担う。現行の挙動を証拠として固定し、別実装で再現し、差分ゼロを検証するループの最初の戦略判断を、推測ではなく実測に基づいて行わせる。

自分では実装しない。 測定し、戦略を決めさせ、機能に分解し、姉妹スキルへ振り分ける役割に徹する。

使い方

replace-strategy setup
replace-strategy issues [--feature <slug>...]
replace-strategy status

モード	内容	実行タイミング
setup	依存確認 → 対話セットアップ → 測定 → 戦略決定 → レジストリ作成 → 機能インベントリ	最初に 1 回
issues	対象機能を選択して Issue 起票。未起票の機能だけが候補に出る	何度でも
status	Issue の状態とリポジトリ内の成果物から現況を導出し、未検証領域の一覧を出す	何度でも。切替判断の前に

• issues は --feature <slug>... で対象機能を選択できる。省略時は未起票の機能から対話選択する
• モード未指定時はどのモードかをユーザーに確認する（setup 未完了なら setup を提案する）
• 自然文でも発動する:「リプレイス戦略を立てて」「リプレイスを始めたい」「現行アプリを測定して」

前提

• ツール: gh（GitHub CLI）, git
• 前提スキル: issue-create（issues モードの起票委譲先）、browser-test（現行アプリのブラウザ操作の作法）
• MCP: chrome-devtools MCP（セマンティクス測定に必須）
• 固定の技術スタック前提（スキル群共通。ここに列挙したもの以外は固定しない）:
  • 新側フロントエンド・バックエンド: TypeScript
  • パリティスイート: Playwright（TypeScript）
  • golden-dataset の投入ツール: TypeScript（SQL 可）
  • テキスト成果物: Git
  • Issue・PR・委譲先: GitHub（gh）
• 利用者が選ぶもの（設定・references で受け取る。スキル本体に固有名を書かない）: 新 UI コンポーネントライブラリと design token、現行・新の DB とその型・意味論の差、静的解析ツール一式、環境変数の用意方法。現行アプリのスタックは測定で把握する

厳守の制約（禁止事項）

• 測定せずに戦略を語らない。 測れない場合は戦略へ進まず停止する。推測は「未測定」と明記する
• LLM に「差分があるか」を聞かない。 差分の検出は決定論的ツールの仕事、LLM の仕事は分類（要対応／許容／環境ノイズ）
• モデルの主観（「同じに見えます」）を収束根拠にしない。 収束判定は決定論的ツールが行う
• 振る舞い保存と品質改善を同じフェーズで狙わない。 忠実な移植は良い性質も悪い性質も等しく運ぶ
• id・name を比較のアンカーにしない。 原則は role ＋アクセシブルネーム
• カタログサイトを比較の正解にしない。 カタログは「確認すべき状態の網羅リスト」の生成源であり、正解は動いている現行アプリ
• 現行アプリを変更しない。 比較のために現行アプリのコード変更（ログ挿入・SMTP 迂回・プロキシ挿入など）が必要なもの、または比較自体が現実的でないものはスコープ外とし、gaps に「手動検証が必要」として記録する（確認済みにしない）
• シークレットの値をログ・標準出力・成果物・設定ファイルに出さない。 設定ファイルには環境変数名だけを持つ。ユーザーが値を提示してきた場合も復唱しない（コマンド例にも埋め込まず、環境変数名で置き換える）

プロジェクト設定の解決

現・新のリポジトリ／URL、DB 接続の環境変数名、成果物の保存方針、意図的差異レジストリ、references（利用者が選ぶ知識の注入）はリポジトリごとに異なる。 設定ファイル .config/skills/shoji9x9/skills.yml の skills.replace-strategy のスキーマと解決手順は references/project-config.md を参照する。

設定は対象プロジェクトに 1 つで全スキルが読めるため、下流スキル（姉妹スキル）はこのキーを直接読む（転記しない）。

setup モード

依存確認 → 対話セットアップ → 測定 → 戦略決定 → レジストリ作成 → 機能インベントリ、の順に進める。

1. 依存の確認: 前提スキル（issue-create / browser-test）のインストール状況と chrome-devtools MCP の有効性を確認する。未導入・無効なら導入手順（gh skill install shoji9x9/skills <name>、MCP の設定）を示す。MCP が無いままでは測定できないため、手順を示したうえで停止する
2. 対話セットアップ: 現・新のリポジトリ／URL、DB 接続（環境変数名のみ）、環境、禁止操作、起動ラッパーを対話で確認し設定ファイルへ保存する。技術スタックはスキル本体に書かず、設定で受け取る。 シークレットの扱いは references/project-config.md の「シークレットの扱い」に従い、接続確認を最初に行い、繋がらなければ早期に失敗する
3. 測定: すべて実測する。手順は references/measurement.md。 セマンティクス測定（同梱の scripts/role-probe.mjs を使用）・DB 復元可否・現行コードの入手性・副作用の棚卸し・既存テストの評価を行い、.replace/survey.md に記録する。測れない場合はここで停止する
4. 戦略の提示とユーザー承認: 測定結果から、パリティスイート戦略・ゴールデンデータセットの作り方・フロント／バックの非対称設計（バックエンドは現行コードからの直接移植、フロントエンドはパリティスイート＋ベースライン駆動）・未検証領域の扱いを提示し、承認を得て .replace/strategy.md に記録する
5. 成果物の扱いの決定（設定ファイルへ）: 保持方針（ワークツリーは最新のみ。履歴は Git が持つ）・保存先（local（既定・コミットしない）／git／git-lfs に限る。それ以外の外部保管は対象外とし、選ぶ場合はポインタ記録のみで検証しないことを明示する）・容量閾値を決める。ここで決めるのは既定値であり、機能ごとに上書きできる
6. 意図的差異レジストリの作成（設定ファイルへ）: 「変えない」「変えてよい」「保留（測定結果で決める）」の 3 分類。references（ui_library / db_semantics）から注入された差（例: 空文字と NULL の扱い、collation による並び順）もレジストリに落とし込む。references の下書きは DDL・測定結果・技術スタックから生成し、人間がレビューして確定する
7. 機能インベントリ: 現アプリを機能単位に分解し、各機能のページ・API・テーブル・副作用出力、横断 API の fan-out、slug を .replace/features.md に記録する。規則は references/features-issues.md

issues モード

.replace/features.md の未起票の機能・横断 API リソース・バッチから対象を選択し、Issue を起票して Issue 番号をインベントリへ書き戻す。 手順・Issue 種類（ゴールデンデータセット／横断 API／機能／バッチの 4 種）・本文構成は references/features-issues.md を参照する。

• .replace/features.md が無い（setup 未完了）場合は起票せず停止し、setup の実行を促す
• 起票は issue-create スキルへ委譲する。起票対象を提示してまとめて承認を得てから 1 件ずつ委譲する（issue-create は 1 件ずつ承認を得る設計のため、本モードで先にまとめて承認を得る）
• 重複チェックはページネーションに留意する（既定件数で打ち切らない）

status モード

自前の状態を持たず、GitHub Issue の状態とリポジトリ内の成果物から毎回導出する（ブランチのマージ後でも動くようにするため）。手順は references/status.md を参照する。

• .replace/features.md が無ければ setup 未実施と報告し、setup の実行を案内する
• Issue の状態は features.md に記録された番号を個別取得する。番号を列挙できない取得はページネーションを処理する（指定件数で打ち切らない）
• 機能ごとのパリティスイートの有無・強度・データセットバージョンの陳腐化・未検証領域（gaps）を導出する
• 横断 API に変更があった場合の影響範囲（利用側の機能一覧）を fan-out から導出する

成果物

すべて対象プロジェクト側に置く。成果物スキーマの正本は生産側スキルが定義する——本スキルは設定・survey.md・strategy.md・features.md の正本を定義し（テンプレート: assets/）、下流スキルの成果物（.replace/parity/<slug>/ や .replace/dataset/ の形式）は各スキルが定義する。同じ形式を複数スキルで重複定義しない。

成果物	場所	内容
設定	.config/skills/shoji9x9/skills.yml	現・新のリポジトリ／URL／環境／DB 接続の環境変数名／起動ラッパー／禁止操作／成果物の保持方針・保存先・容量閾値／パリティスイートの配置／意図的差異レジストリ／references
測定レポート	.replace/survey.md	セマンティクス測定値、DB 復元可否、コード入手性、副作用棚卸し、既存テスト評価。すべて実測値
戦略書	.replace/strategy.md	非対称設計、パリティスイート戦略、ゴールデンデータセットの方針、未検証領域の扱い
機能インベントリ	.replace/features.md	機能一覧、依存順、ページ／API／テーブル／副作用出力、横断 API の fan-out とリソースグルーピング、slug、Issue 化の状態
Issue	GitHub	選択した機能分（issues モード）

姉妹スキルと依存順

スキル	役割
golden-dataset	現行と新側に投入する共通テストデータの投入ツール（フェーズ A: 現行、フェーズ B: 新側）。全機能横断
parity-suite	パリティスイート（新旧どちらにも当てられる実行可能な合否判定基準）の構築と強度検証
parity-replace	新側実装の薄い層。ページ単位の分割・新側マッピングの充填・敵対的レビュー。実装フローは issue-start に委譲
parity-diff	決定論的差分器（画素＋特性照合＋aria）→ LLM トリアージ

全体の依存順: replace-strategy（setup）→ golden-dataset（フェーズ A）→ 各機能で〔parity-suite → parity-replace → golden-dataset（フェーズ B）→ parity-diff（parity-replace と往復）〕。横断 API Issue は機能 Issue より先。

姉妹スキルが未インストールでも本スキル（測定・戦略・起票）は動くが、起票した Issue の実施には必要になる。issues モードの完了時に案内する。