running-bug-review-board

Bug Review Board（BRB）のQAパスを実行する

このスキルでは、アプリの実ユーザーQAパスを実施し、その結果をBug Review Boardに反映します。Bug Review Boardは、構造化されたバグレポート、パスごとの実行レポート、単体で完結するHTMLダッシュボード、チームが対応できる最終的なYES／NOの承認で構成されるフォルダーです。エンジニアリングのトラッカー（Linear／GitHub／Jira／ Notion）と双方向に同期し、QAとエンジニアリングの足並みをそろえます。

このスキルは、すでにMokuhoeのフェーズQAで実績のあるワークフローを一般化したもので、手法はリポジトリに依存しません。

このスキルが必要な理由

多くのエンジニアは自分のコードをテストします。自分が書いたものが動くことを確認します。 しかし、それでは実ユーザーが最初につまずくバグを見逃します。フローをまたいだ古い状態、モバイルでのはみ出し、誤解を招く文言、オンボーディング中に404になるパス、認証とルーティング間の競合状態などです。

このスキルでは、実ユーザーをシミュレートします。QAエージェントは、ソースコードを読まずに操作する、注意深く、やや妥協のない顧客のように振る舞います。

2つのワークフロー — Auto QAとInteractive BRB

このスキルでは、成果物を共有しながらも、意図的に別々のセッションで実行する2つの異なるモードに作業を分けています。

• Auto QAパス — エージェントがアプリを操作してシナリオを実行し、バグを登録し、HTMLレポートを生成して、判定を記録します。徹底性とスピードを重視します。
• Interactive BRB — 別のエージェントがユーザーとともに、未対応／対応中／修正済みのバグをトリアージします。まず双方向の取り込みを実行し、パターンベースのヒューリスティックを適用して重複やクラスターを見つけ、各バグを確認し、ステータスを変更して、トラッカーと同期し、HTMLを再生成して、議事録を作成します。判断の共有を重視します。

両者は分けてください。自動QAパスの中でBRBを実行すると、トリアージの偏りが発見作業に影響し、問題の帰属も分かりにくくなります。 references/brb-interactive.mdを参照してください。

3つの役割 — 1回のパスで3つの視点

各パスでは、次の3つの役割すべてを担います。

• プロダクトマネージャー。 ビルドが、製品仕様書またはフェーズドキュメントに記載されたユーザー向けの約束を果たしているか確認します。果たしていない場合、それはバグではなくプロダクトの不足です。実行レポートに記載してください。
• QA。 主要なサポート対象ビューポートで、実ユーザーの視点からすべてのシナリオを実行します。証拠（スナップショット、コンソール、必要に応じてサーバーデータ）を記録します。合格／不合格／ブロック。
• エンジニア。 前提が無効になっていないか確認します。フェーズドキュメントには「Xは関数Yを使う」とあるのに、Yの名前が変更されている。ドキュメントではサーバー主導とされているフローに、新たなクライアント側のオーケストレーションが加わっている。仕様書にないフィールドがUIに存在する、などです。不足を見つけることが目的です。バグのある動作に合わせてドキュメントをリバースエンジニアリングしないでください。

ユーザーから明示的に依頼されない限り、プロダクトコードを修正しないでください。テストし、記録し、バグを登録して、引き継いでください。

まずアプリを理解する（さもないと、質の悪いテストを書くことになります）

テストを1つでも書く前に、アプリの意図、つまり顧客がそのアプリを使って何をするために雇われるのかを理解してください。調査の全手順については、references/discovering-the-app.mdを参照してください。概要は次のとおりです。

1. アプリが何を約束しているかを、製品仕様書／README／ランディングページ／ピッチデックの順に確認します。

2. フェーズのドキュメント（または現在のスプリント計画）を読み、直近で作られたものを確認します。

3. 過去のQAゲート／チェックリストを読み、以前に何が合格したかを確認します。リグレッションの発見は最も価値があります。

4. バグ報告のインデックスを確認します。未解決のバグは、最初に再テストしなければならないシナリオです。

5. プロジェクトの種類を判定します。 リポジトリに複数のアプリが含まれることがあります。Web＋iOSのモノレポはよくあるため、最初に見つかったものだけで止めず、シグナルがあるすべてのサーフェスを収集します。次の2つの判別ルールは、単一のアプリ内でシグナルが重複する場合に適用されるものであり、実際に別個のサーフェスを除外する理由にはなりません。

   • 同じアプリでは、WebアプリよりElectron／Tauriを優先します。 Electron／Tauriプロジェクト（package.json内にelectron、@electron/、@tauri-apps/がある、またはelectron-builder.yml／tauri.conf.jsonがあるプロジェクト）には、package.jsonとWebフレームワークの依存関係も含まれますが、それらはデスクトップアプリに属します。デスクトップアプリとして一度だけ数え、別個のWebアプリとしても数えないでください。
   • 共有の*.xcodeproj／*.xcworkspaceにおけるmacOSとiOSの判別。 Xcodeプロジェクト単体は両者で共有されるため、それだけで分類してはいけません。プラットフォーム固有のマーカー（以下を参照）が必要です。

   サーフェスと、それぞれで有効になるプレイブックは次のとおりです。

   • Electron／Tauriデスクトップアプリ → computer-use-playbook.mdを使用します。（Computer Useを利用できないmacOS以外のホストでは、プレイブックの段階的な縮退表に従い、代わりにブラウザプレイブック経由でアプリの開発サーバーURLを操作します。）
   • Webアプリ（Electron／Tauriのマーカーを含まないWebフレームワークの依存関係）→ browser-playbook.mdを使用します。
   • iOS／iPadOSアプリ（iOS固有のマーカー（.iOS(...)、platform :ios、UIDeviceFamily、またはios/ディレクトリ）がある場合）→ ios-simulator-playbook.mdを使用します。
   • ネイティブmacOSアプリ（macOS固有のマーカー（.macOS(...)、.appバンドル、またはLSMinimumSystemVersion）があり、iOSマーカーがない場合）→ computer-use-playbook.mdを使用します。
   • 混在（モノレポ） — 上記の2つ以上の異なるサーフェスのシグナルがある場合（例：Webフレームワークの依存関係とiOSマーカー）→ 該当するすべてのプレイブックを実行します。テスト計画にはプラットフォームごとのシナリオブロックを含めます。Webに該当しても、同じリポジトリにあるiOS（またはmacOS）のテストを省略してはいけません。
   • その他（UIのシグナルがない場合）→ UIプレイブックは有効になりません。

   Codex Computer Useが利用可能かどうかも確認してください（macOSのみ）。利用できると、Webアプリを人間の操作に近い形でテストでき、ネイティブMacアプリやElectron／Tauriアプリにアクセスする唯一の手段となります。ほとんどのVM（Cursor cloud、CI）では利用できないため、テストをこれに依存させないでください。

6. 課題トラッカー（Linear、GitHub、Jira、Notion、またはなし）を判定します。見つかったシグナルをすべて提示し、qa-config.jsonを書く前にユーザーに確認を求めてください。issue-trackers.mdを参照してください。

7. 公開されているルート／サーフェス／エントリーポイントを一覧にし、新規ユーザーが実際にアクセスするものを判断します。

ユーザーが「このアプリをQAして」と言ってもドキュメントがない場合は、質問してください。references/discovering-the-app.md § Asking the userを参照してください。

ワークフロー（すべてのフェーズ、すべてのリポジトリ）

1. Scope        → which surface / phase / build
2. Discover     → product intent + recent change + open bugs
                + project type + issue tracker (confirmed)
3. Plan         → manual test plan (scenarios, IDs, expected, gates)
4. Prepare      → env, build, test accounts, viewport / device matrix
5. Mode         → parallel coordinator OR sequential wrap-up
6. Execute      → real-user scenarios with evidence
7. File bugs    → P0/P1/P2 with reproduction steps
8. Merge        → results + verdict (YES/NO + open P0/P1)
9. Generate HTML → apply html-report-style-guide.md
10. Hand off    → next QA agent (if NO) or engineering (if blockers)
11. Schedule BRB → separate session for interactive triage

詳細はreferences/workflow.mdを参照してください。

モードの選択

状況	モード	参照
フェーズを最初からすべて確認する場合。複数エージェントの使用が可能	並列コーディネーター	references/parallel-coordinator.md
フェーズを最初からすべて確認し、waves / waves-codex スキルがインストールされている場合	並列コーディネーター。範囲を限定したウェーブとして実行します（カバレッジゲート、構造化された引き継ぎ、段階的な検証、低コストモデルでの分割処理）	references/parallel-coordinator.md § Run the pass as a wave
以前の並列実行が停滞または部分的なままの場合	順次仕上げ	references/sequential-wrapup.md
単独のエージェントで、対象範囲が小さい場合	上から順に確認する逐次方式	references/sequential-wrapup.md
エンジニアリングチームが修正をリリースした後、修正済みのバグ1～3件を再テストする場合	バグのテスト ID に範囲を絞った逐次方式	references/sequential-wrapup.md
担当者と未解決のバグのバックログをトリアージする必要がある場合	対話型 BRB（別セッション）	references/brb-interactive.md
リポジトリがネイティブ macOS アプリである場合、または実際にサインインしたアプリを担当者と同じように確認したい場合	自動確認＋Computer Use プレイブック（macOS）	references/computer-use-playbook.md
リポジトリが iOS / iPadOS アプリである場合	自動確認＋iOS プレイブック（入力にはコンパニオンスキルを使用）	references/ios-simulator-playbook.md
テスト計画がまだない場合	まず計画を作成	references/test-plan.md
フェーズのドキュメントに、コードにまだ実装されていない機能が記載されている場合	中止してください。ユーザーに伝えてください。QA には動作するビルドが必要です	—

サーフェス — 有効になるプレイブック

検出ステップで判定します。リポジトリのシグナルを、該当するすべてのサーフェスのプレイブックに照合してください。通常は1つですが、モノレポでは複数に該当することがあります（下記の複合を参照）。後続のパスで再検討する必要がないよう、選択内容をdocs/qa/qa-config.jsonに記録してください。

サーフェス	シグナル	プレイブック
Electron / Tauri デスクトップアプリ (最初に確認 — Web アプリより優先)	package.json内のelectron、@electron/、または@tauri-apps/、electron-builder.yml、tauri.conf.json	computer-use-playbook.md
Web アプリ	Web フレームワークの依存関係を含むpackage.json（Electron / Tauri のシグナルなし）、app/ / pages/ / src/routes/、Vercel / Netlify / Cloudflare のデプロイ設定	browser-playbook.md（Mac で人間の操作に近い動作確認を行う場合は、Computer Useを追加）
iOS / iPadOS アプリ	.iOS(...)を含むPackage.swift、platform :iosを含むPodfile、UIDeviceFamilyを含むInfo.plist、ios/ディレクトリ（.xcodeproj / .xcworkspaceのみの場合はmacOSと共用のため、iOS固有のシグナルが少なくとも1つ必要です）	ios-simulator-playbook.md
ネイティブ macOS アプリ	.macOS(...)を含むPackage.swift、.appバンドル、LSMinimumSystemVersionを含むInfo.plist	computer-use-playbook.md
複合（モノレポ）	上記の異なるサーフェスが2つ以上のシグナル（例：Web + iOS） — Web に該当しても iOS / macOS の確認を省略してはいけません	該当するすべてのプレイブックを実行します — テスト計画にはプラットフォームごとのシナリオブロックが追加されます
CLI / ライブラリ / バックエンド	UI のシグナルなし	どちらの UI プレイブックも使用しません。QA では統合テストとエラーパスに重点を置きます

iOS アプリの QA では、このスキルが（検出、テスト計画、バグの登録、BRB を）統括し、シミュレーターの操作は iOS コミュニティ向けに特化して構築されたスキル（AXe（Cameron Cooke）、XcodeBuildMCP（Cameron Cooke / Sentry）、ios-simulator-skill（Conor Luddy）、ios-build-verify（Josh Adams）、baguette（tddworks）、ios-idb-skill（Hao Wu）、serve-sim-skill（malopezr7）、swiftui-autotest-skill（Yusuf Karan）、xcode-build-skill（pzep1）、および TestFlight への引き継ぎ用の App Store Connect CLI + skills（Rudrank Riyam））に委ねます。推奨スタックの表はプレイブックを参照してください。

イシュートラッカーとの連携

このスキルは検出して確認を求めます — 決めつけることはありません。検出の手順では、シグナル（LINEAR_API_KEY、gh auth status、Atlassian URL、登録済み MCP サーバーなど）を調査し、docs/qa/qa-config.jsonに書き込む前に、判明した内容をすべてユーザーに提示します。確認後、エージェントはバグをローカルに登録し、トラッカーと同期します（設定に応じて登録時またはBRB時にプッシュ）。また、エンジニアリング側のステータス変更を取得します（BRB開始時はデフォルトでON）。双方向の調整ルールはリファレンスに明記されており、差異は上書きされることなく、必ずユーザー判断を求める差分として提示されます。

トラッカー ID はバグのフロントマターに保存されます — Tracker / Linear、Tracker / GitHub、Tracker / Jira、Tracker / Notion、Tracker / lastSyncedAt。HTML レポートでは、各バグカードにタグとして表示されます。

ヘルパー： scripts/bugs-needing-sync.shは、トラッカー ID がなく、プッシュ候補となるバグを一覧表示します。 scripts/bugs-needing-pull.shは、Tracker / lastSyncedAtが古く、プル候補となるバグを一覧表示します。

HTML レポート（Zite + Dieter Rams）

各パスおよび各 BRB セッションの終了時に、html-report-style-guide.md を適用して docs/qa/report/index.html と、バグごとおよび実行ごとの詳細ページを再生成します。

レポートはカンバンボードではなく、雑誌のような読み心地にします。タイポグラフィで表現します。優先度は小型大文字の P0、ステータスは Open という語、判定はディスプレイ書体の単語 1 つ（YES または NO）で示します。本文にはインク色を 1 色、リンクと CTA には控えめなテラコッタ色を 1 色使い、区切りには極細の罫線を使います。色付きチップやピル、影は使いません。画面サイズを問わず、読みやすい横幅は 640px にします。デスクトップでは、バグ詳細ページにメタデータ用の控えめな右サイドレールを追加します。モバイルでは、読者が上に戻ってスクロールせずに済むよう、画面下部の親指が届く範囲に主要なアクションを重複して表示します。

情報の階層は、エンジニアのレビュアーが素早く確認できるように設計されています。タイトル → デック → 影響 → 実際の動作／期待される動作 → 修正時のリスク → 手順 → 証拠。v0.3 ではバグテンプレートに Impact と Risk to fix のセクションが追加されました（既存のバグは、これらのセクションがなくても問題なく表示されます）。

Markdown が唯一の信頼できる情報源です。 HTML は読み取り専用で、再生成されます。バグの状態を変更するために HTML を編集してはいけません。Markdown を編集してから再生成してください。BRB やリリースのレビューで関係者が開くのはダッシュボードです。

パターンベースのトリアージ提案

インタラクティブ BRB は、triage-heuristics.md にある名前付きヒューリスティックのカタログを使って表示する Suggestions カードから始まります。同じ疑わしいファイル、手順の接頭辞の重複、同じコンソールエラー、同じペルソナ＋サーフェス＋結果、フェーズの連鎖、見た目に関するクラスター、リグレッションのマーカー、同じ担当者が対象です。各提案にはヒューリスティック名と一致したテキストが示されるため、ユーザーは常に、何が理由でフラグ付けされたのかを確認できます。埋め込み表現も、LLM API も、自動マージもありません。エージェントが提案し、ユーザーが判断します。

同じヒューリスティックは、ファイル作成時の自動パスでもオプトインで実行できます（triage.runHeuristicsOnFile、デフォルトは false）。これにより、パスは二重に登録する代わりに、「新しく登録するか、それとも BUG-007 を更新するか」を確認できます。

フォルダー構成がない場合はスキャフォールドを作成

対象のリポジトリに QA フォルダー構成がまだない場合は、同梱のスキャフォルダーを実行して作成します。

bash <skill>/scripts/scaffold-qa.sh "$REPO_ROOT" PHASE_NUM [SLUG]

次のものが作成されます（冪等で、既存のファイルは上書きされません）。

<repo>/docs/qa/
├── README.md                         # how QA works in this repo
├── qa-config.json                    # stub; discovery rewrites once user confirms
├── phase-NN-<slug>-manual-test-plan.md  # filled-in skeleton (if PHASE_NUM given)
├── report/                           # HTML report destination (agent generates)
├── bug-reports/
│   ├── README.md                     # index + status workflow
│   ├── _template.md                  # bug template
│   └── assets/                       # screenshots (incl. ios/ for iOS QA)
└── runs/                             # per-shard + coordinator merges + BRB minutes

リポジトリにすでに別の構成（例：tests/manual/、qa/、イシュートラッカー）がある場合は、その構成を採用してください。重複して作成してはいけません。

常に

• 実際のユーザーの視点で確認します。 ソースコードではなく、アプリを操作します。convex/users.ts や API レイヤーだけを見るのではなく、URL とクリック（またはシミュレーターでのタップ）でテストします。
• モバイル、タブレット、デスクトップでテストします。 実際のユーザーはどのデバイスからもアクセスします。レイアウト、オーバーフロー、タップ対象の不具合は、確認を省いたブレークポイントで見つかることがあります。Web アプリでは 3 つのモードすべてを確認します。基準サイズは モバイル 375 × 812、タブレット 768 × 1024、デスクトップ 1280 × 800 です（仕様のブレークポイントに合わせて調整してください）。アプリの主要な対象から着手します。製品仕様を確認し、仕様が曖昧なら、どのモードを最も重視すべきかユーザーに尋ねます。ユーザーに確認できない場合は、リポジトリで見つかった情報（レスポンシブ CSS／ブレークポイント、フレームワークの既定値、マーケティング文言）から最も可能性の高い主要対象を推定し、その前提を記録します。後続のパスで同じ議論を繰り返さないよう、モードと選択した主要対象を qa-config.json#platforms.web に記録します。iOS アプリの場合、デバイスマトリックスは qa-config.json#platforms.ios.devices で指定します。
• エージェントごとにブラウザータブは 1 つにします。 共有タブを複数のエージェントで並行して使うと、認証プロバイダーのレート制限や古いセッションが発生します。
• 証拠を記録します。 不具合が発生した時点のスナップショットまたはスクリーンショット、コンソールエラーの原文、該当する場合はサーバーのデータ行を保存します。
• FAIL になったら直ちにバグを登録します。references/bug-filing.md を参照してください。パスの終了まで待たないでください。
• テストアカウントの手順に従います。 references/test-accounts.md を参照してください。手順が記載されていない場合は、推測する前にユーザーに尋ねてください。
• シナリオ間でセッションを整理します。 references/session-hygiene.md を参照してください。古いストレージ／Cookie／+test メールアドレスの再利用は、新規ユーザーフローを気付かないうちに汚染します。
• バグを登録する前に、リポジトリごとに 1 回、issue-trackers.md の確認手順を実施します。
• html-report-style-guide.md に従い、各パスと各 BRB セッションの終了時に HTML レポートを再生成します。
• iOS アプリの QA では、実際のシミュレーター操作を ios-simulator-playbook.md のコンパニオンスキルに委ねます。 起動／タップ／スクリーンショットの手順を独自に作らないでください。

禁止事項

• コードの確認だけでシナリオを PASS にしないでください。ユーザーが体験するのはソースコードではなく、アプリです。
• 証拠（スナップショット、サーバーのデータ行、エラーのないコンソール）なしでフェーズゲートに ☑ を付けないでください。
• 指示なしに製品コードを修正しないでください。記録し、登録し、引き継ぎます。
• フェーズ文書の既知の問題／延期事項セクションを省略しないでください。このセクションが作業範囲の指針となり、誤ったバグ報告を防ぎます。
• 不具合のある動作に合わせてフェーズ文書や仕様の名前を変更しないでください。リグレッションが見えなくなります。
• 1 つの cursor-ide-browser タブで、複数の QA ブラウザーサブエージェントを実行しないでください。
• 以前失敗したテスト用メールアドレスを、実行タグのサフィックスを変更せずに再利用しないでください。
• ユーザーに尋ねずに課題トラッカーを決めつけないでください。 明らかな手掛かりがある場合も同様です。
• 自動 QA パスと同じセッションで Interactive BRB を実行しないでください。 トリアージによる発見への偏りを防ぐため、意図的に分けています。
• ユーザーに尋ねずに、トラッカーだけにあるバグをローカルの Markdown に自動インポートしないでください（既定値は pull.createLocalForUntracked: "ask" です）。
• ヒューリスティクスで重複の可能性が示されたバグを自動マージしないでください。 すべてのマージ／重複排除には、ユーザーの確認が必要です。
• バグの状態を変更するために HTML を編集しないでください。 Markdown を編集して再生成します。
• Web アプリの QA に iOS シミュレータープレイブックを使用しないでください。 iOS アプリのプロジェクト専用です。モバイル Web の QA ではブラウザープレイブックを使用します。

バグの優先度（BRB 分類）

レベル	定義	対応
P0	主要フローを妨げる、データ損失、認証の回避、セキュリティ	フェーズをリリースできません。トリアージが完了するまで QA パスを中断します
P1	機能が壊れている、または誤っている。回避策はある	現在のフェーズの承認を妨げます
P2	外観上の問題、エッジケース、アクセシビリティ、開発者コンソールのノイズ	仕上げフェーズまたはリリース前の安定化まで延期します

P0 と P1 の判断に迷った場合、ユーザーが回復不能な状態に陥ったり、データを失ったりする可能性があるなら、P0 を選びます。

合格基準（各フェーズ共通）

• フェーズの手動テスト計画に記載されたすべてのシナリオが PASS であること（または、フェーズのドキュメントに理由を明記して 延期 されていること）。
• フェーズゲート／チェックリストがすべて完了していること。
• このフェーズに関する未解決の P0 または P1 バグがないこと。
• 認証／招待／通知に関わるフェーズでは、回帰テストマトリクスがすべて完了していること。

完了の定義

各パスの最後に、コーディネーターがマージ用ドキュメントを作成し、その冒頭行を次のようにします。

Phase N ready? YES — すべてのゲートが ☑、未解決の P0/P1 はありません。 Phase N ready? NO — 未解決の P0/P1 と未実施のシナリオを列挙し、次の QA エージェントに引き継ぐための1段落のプロンプトを記載します。

NO の場合、マージ用ドキュメントは新しい会話にそのまま貼り付けられる状態にしてください。 次のエージェントが状況を再確認する必要がないようにします。references/gate-merge.md を参照してください。

HTML レポート（docs/qa/report/index.html）も再生成してコミットします。

ブラウザツール（Cursor 優先、フォールバック順）

Cursor 内で実行する場合は、デフォルトで cursor-ide-browser MCP を使用します。別のツールでセッションを実行している場合、またはブラウザ MCP が利用できない場合は、references/browser-playbook.md に記載された順にフォールバックします。

1. cursor-ide-browser MCP（Cursor / Claude Code）
2. Chrome DevTools for agents（chrome-devtools-mcp） — 結果を自動で待機し、DevTools レベルのネットワーク／コンソール／Lighthouse／a11y の検査を追加します。実際にサインイン済みの Chrome に接続できるため、認証フローでボット判定されるのを防げます
3. browser-use MCP（プロバイダーに依存しません）
4. Playwright（CLI または MCP）
5. Codex Computer Use（macOS） — 実際にサインイン済みのアプリで、人間の操作を忠実に再現して確認します。computer-use-playbook.md を参照してください
6. 手動で操作し、コンソールエラーやスクリーンショットをユーザーに貼り付けてもらう

使用するツールにかかわらず、プレイブックは同じです。移動 → スナップショット → 最新の参照に基づく操作 → 証拠の取得 → 完了したらロック解除、の順に進めます。参照ドキュメントでは、ボット検出やタイミング競合をアプリに引き起こさない、人間らしい操作方法を含め、各ツールの詳細を説明しています。環境で利用できるツールを使ってパスを成功させてください。ほとんどの VM では利用できない Computer Use に依存しないでください。

パスごとの成果物

パス	内容
docs/qa/qa-config.json	トラッカー + トリアージ + レポート + プラットフォーム設定（ディスカバリーでスタブを書き換えます）
docs/qa/phase-NN-<slug>-manual-test-plan.md	（新たに生成した場合）
docs/qa/runs/QA-<shard>-run-YYYY-MM-DD.md	シャードごとの結果
docs/qa/runs/COORDINATOR-MERGE-YYYY-MM-DD.md	マージ + 判定
docs/qa/runs/BRB-YYYY-MM-DD.md	（インタラクティブ BRB のみ）セッション議事録
docs/qa/bug-reports/BUG-NNN-*.md + assets/BUG-NNN/	各不具合
docs/qa/report/index.html + bugs/ + runs/ + assets.css	Apple 風の文言を使った HTML ダッシュボード
docs/QA_GATES.md（またはリポジトリ内の同等ファイル）	ゲートのチェックボックスを更新
フェーズのドキュメント § QA ステータス	承認メモ + マージへのリンク
トラッカーの課題（Linear / GitHub / …）	syncOnFile が有効な場合、または BRB 後

対象リポジトリで既に使用されているパスに合わせてください。

参考資料（必要に応じて読み込む）

• references/workflow.md — PM／QA／Eng の完全な意思決定ツリー
• references/discovering-the-app.md — 意図の調査と、ドキュメントがない場合にユーザーに確認する方法
• references/test-plan.md — 仕様書、フェーズのドキュメント、ゲートからフェーズの手動テスト計画を作成する方法
• references/test-accounts.md — Clerk／Auth0／Supabase／カスタム、および「ユーザーに確認する」パターン
• references/session-hygiene.md — 古いストレージ、レート制限、ペルソナのサフィックス付け
• references/browser-playbook.md — cursor-ide-browser、Chrome DevTools MCP、browser-use、Playwright のレシピと、人間のように操作する方法（ウェブアプリ）
• references/computer-use-playbook.md — ウェブアプリとネイティブ macOS アプリでの Codex Computer Use（macOS。その他の環境ではブラウザードライバーに適切にフォールバック）
• references/ios-simulator-playbook.md — iOS／iPadOS アプリの QA、厳選されたコンパニオンスキルの段階的な利用方法（AXe、baguette、XcodeBuildMCP、ios-simulator-skill、ios-build-verify など）
• references/parallel-coordinator.md — シャードマップ、書き込みパス優先のルール、コピー＆ペースト用シャードプロンプト、waves／waves-codex がインストールされている場合に、範囲を限定したウェーブとしてパスを実行する方法
• references/sequential-wrapup.md — 単一エージェントでの完了処理、コピー＆ペースト用プロンプト
• references/bug-filing.md — バグのテンプレート、重大度、証拠に関するルール、ステータスの遷移
• references/gate-merge.md — シャードレポートをゲートと判定結果に統合する方法
• references/issue-trackers.md — 検出・確認の手順、Linear／GitHub／Jira／Notion アダプター、双方向同期
• references/brb-interactive.md — インタラクティブなバグレビュー委員会（別セッション）のワークフロー
• references/triage-heuristics.md — 重複／クラスターの検出に使う、名前付きヒューリスティックのカタログ
• references/html-report-style-guide.md — Apple の言葉遣い、コンポーネント、レンダリングのルール
• references/extending-the-skill.md — 書き換えずにトラッカー、ヒューリスティック、対象領域、モードを追加する方法
• references/templates/ — bug-report、test-plan、run-report、coordinator-merge、brb-interactive-prompt、brb-minutes、qa-config.example.json、html-report/ のひな形

スクリプト

• scripts/scaffold-qa.sh REPO_ROOT PHASE_NUM [SLUG] — 任意のリポジトリに QA フォルダーの構成、qa-config のひな形、レポートフォルダーを作成します。
• scripts/bugs-needing-sync.sh REPO_ROOT [--tracker …] — トラッカー ID が未設定のバグを一覧表示します。エージェントが一覧を読み取り、 issue-trackers.md に従って登録します。
• scripts/bugs-needing-pull.sh REPO_ROOT [--threshold 24h] [--tracker …] — Tracker / lastSyncedAt が古いバグを一覧表示します。エージェントが一覧を読み取り、 issue-trackers.md に従って取得します。

このスキルの拡張

新しいイシュートラッカー、トリアージヒューリスティック、対象領域のプレイブック、モードは追加方式で拡張できます。セクションをコピーして記入すれば、次のセッションでエージェントが取り込みます。前方互換性のある qa-config.json スキーマ（version: 1、不明なフィールドは無視）、バグのフロントマターへの追加、バージョン付き HTML レポートマーカーに対応しています。references/extending-the-skill.md を参照してください。

避けるべきアンチパターン

しないこと	理由
コードを調べただけでシナリオをPASSにする	ユーザーはソースコードを体験するわけではありません
P0のバグを「次のフェーズ」に先送りする	基盤のバグはあらゆるところに波及します
新規ビルドで再実行せず、以前のPASS判定を信頼する	無関係な作業によってリグレッションが発生することがあります
1つのブラウザータブで複数のQAエージェントを実行する	認証プロバイダーによってアクセスが制限され、セッションが混線します
バグのある挙動に合わせてフェーズのドキュメントを編集する	リグレッションを隠すことになります。代わりにバグを報告してください
再現手順なしでバグを報告する	エンジニアが対応できません
正常系のパスだけをテストする	正常系のパスは、すでにエンジニアがテストしています
同じセッションでBRBと自動パスを実行する	トリアージの偏りが発見結果に影響します
qa-config.jsonを設定せずにバグをトラッカーに同期する	重複や編集内容の消失につながります
iOSプレイブックを使ってMobile Safari上のWebアプリをテストする	対象範囲外です。iOSプレイブックはiOSアプリのプロジェクト専用です
ヒューリスティックによる提案を自動マージする	重複排除には毎回ユーザーの確認が必要です
トラッカーにしかないバグをローカルのMarkdownとして自動インポートする	エンジニアが報告したバグで、QAが管轄すべきでない場合があります
バグの状態を変えるためにHTMLを編集する	正とする情報はMarkdownです。HTMLは再生成してください

QA実施中に、QAの範囲を超える作業が見つかった場合

実施中に次の問題が見つかった場合：

• フェーズで存在するとされている機能が未実装（コードパスがまったくない）
• 複数のシナリオにわたってスキーマが仕様から逸脱している
• 残りのすべてのシナリオを妨げるP0

テストを中断し、問題を提示してください。エンジニアリングにエスカレーションするか、フェーズの範囲を縮小するかはユーザーが判断します。置き換えが必要な基盤に対してテストを続けても、時間の無駄になります。