hideki5123 ui-spec-sim — UIスペック+シミュレーターの設計レビューループ
チケット1枚から、レビュー可能な2つのHTML成果物を作り、ユーザーの指摘を 決定ログ (D番号) として積み上げながら確定させる。実装者は文言一覧と シミュレーターの遷移をそのまま実装すればよい状態がゴール。
成果物の型 (2 artifacts・別URL)
| 成果物 | 役割 |
|---|---|
| スペックHTML | 要件ごとのセクション+実UI忠実なモック+決定ログ (D1..)+未決Qカード (案A/B+推奨)+文言一覧 (全UIストリング) |
| シミュレーターHTML | 決定を実装した状態機械。遷移カバレッジ自動チェック (触った遷移にチェック=確認漏れが残る)・遷移ログ・障害注入トグル・in-flight遅延 |
言語規則: 注釈=ユーザーの言語 / 製品UI文言=製品の言語 (両成果物とも)。 UI文言はスペックの文言一覧が唯一の正で、モック・シミュレーターは一字一句同じ文字列を使う。
Phase 0: グラウンディング
- チケット→親チケット→親スペック (Confluence等) の順に読む。
- 実UIコードを読んで見た目を掴む — 対象アプリの実コンポーネント (ボタン様式・ フィールド様式・テーマ色) をリポジトリから確認し、モックはそれに寄せる。 汎用デザインの再発明をしない。
- enum・status値など仕様の土台になる値は実コードで裏取りする (存在しない値を スペックに書かない)。
Phase 1: スペックHTML
構造とスケルトンは references/deliverable-templates.md を参照 (WHEN TO READ: このPhaseとPhase 2 の執筆時のみ)。要点:
- 決定ログ: D番号は増えるのみ。改訂は「D5改」と書き、旧番号は再利用しない (チャット・チケットからの参照を壊さない)。各決定に不採用案と理由を併記。
- 未決Qカード: 案A/案B+推奨を明示。解決したら「決定」欄を追記して残す (履歴が消えない)。
- 文言一覧: モックに見えるUIストリング全部に key を振る。「全ストリング」を 名乗る以上、モックとの完全一致を検証で担保する (下記Phase 3)。
- artifactとして公開し、以後同じURLで再公開し続ける。
Phase 2: シミュレーターHTML
- スペックの決定を全部実装した状態機械。1ファイル・vanilla JS。
- カバレッジ一覧が肝: 設計済み遷移を列挙し、操作すると自動チェック。 「未チェック=未確認」がユーザーへの価値。ガード (disabled化・拒否) も 観測ベースでチェックする。
- 障害注入 (Slack失敗等)・異常系再現ボタン・RPC遅延+spinner (二重クリック防止) を 入れて、正常系以外も触れるようにする。
- シミュレーター都合の要素 (再現ボタン等) は「(シミュレーション)」と明示し、 製品UIと区別する。
Phase 3: レビューラウンド (何巡でも)
1ユーザー指摘 = 1ラウンド。毎回:
- 指摘を新D番号 (または D改) に落とし、スペック・シミュレーター・文言一覧の 3点を同時に更新する。片方だけ直すと必ず矛盾が残る。
- シミュレーターは headlessブラウザで実挙動を検証 (構文チェック+主要フロー)。 references/verify-round.md のスニペットを使う (WHEN TO READ: 各ラウンド)。
- 敵対的整合検証: 検証agentにスペック⇔シミュレーター⇔文言表⇔決定ログの 矛盾・古い記述の残骸を探させる (プロンプト雛形は references/verify-round.md)。 must/should/nit で受け取り、main loopで取捨して反映。
- 同じURLで再公開し、報告は「今回のD/Q差分」を先頭に。
「効かない」系の報告は、まずheadlessで再現を試みる — 再現しなければ操作上の罠 (状態リセット・分かりにくい既存挙動) を疑い、罠自体を設計で潰す。
Phase 4: 外部同期 (求められたときだけ)
- 実装Ticket: 蒸留したテキスト (state flowサマリー+要件+文言一覧への参照) と スクショ (シミュレーター専用の絵は除外)。添付はjira-cliスキルのREST フォールバック参照。
- 親スペック (Confluence): 変更された決定だけを外科的に反映。confluenceスキルの 「Surgical edits — safety rules」に従う (literal-textアンカー・update直前再fetch)。
- Figma: figma-shot-board スキルに委譲 (スクショ→ラベル付きボード)。
鉄則 (過去の失敗から)
- チーム向けドキュメントにシミュレーションの内容を書かない。チームに見せるのは Ticket上の最低限テキスト+製品状態のスクショだけ。シミュレーター・録画・探索物は チャット/artifactに留める。
- artifactリンクは共有設定するまで本人しか開けない — チーム共有前提の場所に貼るとき は一言添える。
- 破壊的操作なしのUI (押せるのに失敗するボタン) を作らない — ガードはUIで先取りし、 server側はバックストップ。
References
- references/deliverable-templates.md — スペック/シミュレーターの構造スケルトンと 実装パターン。WHEN TO READ: Phase 1-2 の執筆時のみ。
- references/verify-round.md — 整合検証agentのプロンプト雛形+headless検証スニペット。 WHEN TO READ: Phase 3 の各ラウンド。
- references/scenarios.feature — BDD spec。スキル自体の監査・改修時のみ読む。 通常実行では不要。
Feedback Check
実行開始前に、この SKILL.md の隣の feedback/log.md が存在し5件以上あれば直近10件を 読む。同一キーワードの問題が3件以上、または直近10件の平均評価が3未満なら、ユーザーに 日本語で伝える: 「過去のフィードバックで類似パターンを検出: [簡潔に]。 /skill-improve --skill ui-spec-sim で改善案を分析できます。」いずれでも実行は続行。 log.md がなければ黙ってスキップ。
Retrospective
ワークフロー完了後に振り返る:
- 途中の是正 (却下された設計・方針転換・検証で見つかったバグ) があったか確認。
- ユーザーに日本語で聞く: 「今回のスペック/シミュレーター作成のフィードバック (1-5の評価、気になった点、または何もなければEnter)」 評価が5未満なら必ず追問: 「なぜその評価ですか？ (改善のために具体的に教えてください)」 回答を Rating reason として逐語記録。auto-modeでもこの追問は省略しない。
- フィードバックがある、または是正が実際にあった場合:
a. feedback/ ディレクトリがなければ作成 (この SKILL.md の隣。skillのソースdirは
git rev-parse --show-toplevel から解決)。
b. feedback/log.md を読み (なければ
# Feedback Logヘッダー+空行+<!-- Append new entries at the top. Do not edit previous entries. -->で作成)、 ヘッダー直後に新エントリを追加 (Skill Version / Task / Outcome / Rating / Rating reason / Corrections / Issues / User Note)。 c. 一文の日本語で記録完了を伝える。 - スキップかつ是正なしなら記録せず終了。