replicate-issue

GitHub イシューの再現

稼働中の Archon アプリケーションで GitHub イシューを体系的に再現し、検証します。 目的は、報告された動作が実際に発生するかを判断し、正確な再現手順を特定し、関連するイシューを見つけ、実行可能な修正案を提示することです。

イシュー番号: $ARGUMENTS

$ARGUMENTS が空の場合は、先にイシュー番号をユーザーに尋ねてください。

---

フェーズ 0：環境の準備

0.1 Main ブランチに切り替えて最新の状態を取得する

結果の正確性を確保するため、main の最新コードをテストしていることを確認します。

cd /path/to/archon

# Stash any local changes to avoid conflicts
git stash 2>/dev/null || true

# Switch to main and pull latest
git checkout main
git pull origin main

echo "On branch: $(git branch --show-current)"
echo "Latest commit: $(git log --oneline -1)"

0.2 実行中の Archon プロセスを終了する

Archon をクリーンな状態で起動できるように、ポート 3090（バックエンド）と 5173（フロントエンド）を解放します。

pkill -f "bun.*dev:server" 2>/dev/null || true
pkill -f "bun.*dev:web" 2>/dev/null || true
pkill -f "bun.*packages/server" 2>/dev/null || true
pkill -f "bun.*packages/web" 2>/dev/null || true
fuser -k 3090/tcp 2>/dev/null || true
fuser -k 5173/tcp 2>/dev/null || true
sleep 2

# Verify ports are free
! fuser 3090/tcp 2>/dev/null && ! fuser 5173/tcp 2>/dev/null && echo "Ports 3090 and 5173 are free" || echo "WARNING: Ports still in use"

0.3 Archon のバックエンドとフロントエンドを起動する

cd /path/to/archon

# Start both backend and frontend together
bun run dev &
sleep 8

# Verify backend is healthy
curl -s http://localhost:3090/api/health | head -c 200
echo ""

# Verify frontend is serving (port may vary if 5173 is taken)
curl -s http://localhost:5173 | head -c 100 || curl -s http://localhost:5174 | head -c 100

注: ポート 5173 が使用中の場合、Vite はポート番号を自動的に増やします（5174、5175 など）。bun run dev の出力で実際のフロントエンドのポートを確認し、以降はそのポートを使用してください。

---

フェーズ 1：イシューを分析する

1.1 GitHub イシューを読む

gh issue view $ARGUMENTS --json title,body,labels,comments,state

イシューを注意深く読み解き、以下を抽出します。

• タイトルと概要：報告されている問題は何ですか？
• 再現手順：どのような具体的な操作でバグが発生しますか？
• 期待される動作：本来どのように動作するべきですか？
• 実際の動作：代わりに何が起きますか？
• 環境の詳細：特定の条件（ブラウザー、OS、タイミングなど）はありますか？
• ラベルと優先度：深刻度はどの程度ですか？
• コメント：追加の背景情報、回避策、関連イシューはありますか？

1.2 テスト計画を作成する

イシューの内容に基づいて、テスト項目を具体的にまとめます。 イシューに記載されている各症状について、以下を定義します。

1. 再現するための正確なユーザーフロー
2. 確認する内容（期待される動作と実際の動作）
3. 証拠として撮影するスクリーンショット

---

フェーズ 2：ブラウザー自動化で再現する

すべてのブラウザー操作には agent-browser CLI を使用してください（Playwright は使用しないでください）。

基本的なワークフロー

# 1. Navigate to the page
agent-browser open http://localhost:5173

# 2. Get interactive elements
agent-browser snapshot -i

# 3. Interact using refs from the snapshot
agent-browser click @e1
agent-browser fill @e2 "text"

# 4. Re-snapshot after navigation or DOM changes
agent-browser snapshot -i

# 5. Take screenshots at every significant point
agent-browser screenshot /tmp/issue-$ARGUMENTS-{step-name}.png

テストのガイドライン

• スクリーンショットを積極的に撮影する — 各操作の前後に /tmp/issue-$ARGUMENTS-*.png へ保存します
• すべてのスクリーンショットを読む — Read ツールを使って各スクリーンショットを目視で確認し、見えている内容を検証します
• まず正常系をテストする — バグをテストする前に、通常の条件で機能が動作することを確認します
• イシューに記載された正確な再現手順に従う — 手順を省略しないでください
• 条件を変えてテストする — 同じフローを少しずつ変えて試します（異なるデータ、異なるタイミング、ページの再読み込みなど）
• 関連するフローもテストする — イシューがワークフロー X に関する場合、同様の問題がないかワークフロー Y と Z も確認します
• API 検証に curl を使用する — UI の状態を直接 API 呼び出しと照合し、データの正確性を確認します
• ページの再読み込み後も確認する — SSE やリアルタイムのバグは、画面遷移や再読み込み後にのみ発生することがあります
• 複数の会話で確認する — イシューが会話に関する場合、複数の会話を開いてテストします
• 非同期処理の完了を待つ — ネットワークに依存する操作には agent-browser wait コマンドを使用します

ワークフローの実行（必要な場合）

イシューがワークフローの実行に関する場合は、REST API を使用してバックグラウンドワークフローを実行します。

# Create a conversation
CONV_ID=$(curl -s -X POST http://localhost:3090/api/conversations \
  -H "Content-Type: application/json" -d '{}' | jq -r '.conversationId')

# Trigger a workflow (archon-assist is a good general-purpose one)
curl -s -X POST http://localhost:3090/api/workflows/archon-assist/run \
  -H "Content-Type: application/json" \
  -d "{\"conversationId\":\"$CONV_ID\",\"message\":\"Your test message here\"}"

チャットメッセージの送信（必要な場合）

curl -s -X POST "http://localhost:3090/api/conversations/$CONV_ID/message" \
  -H "Content-Type: application/json" \
  -d '{"message":"Your test message"}'

---

フェーズ 3：調査結果を記録する

イシューに記載された各症状について、以下を記録します。

症状	再現したか？	証拠	備考
{イシューに記載された症状}	YES / NO / PARTIAL	スクリーンショットのパス	{詳細}

深刻度の分類

• 確認済み（再現可能）：イシューに記載されたバグを正確に再現できました
• 部分的に確認済み：症状は発生しますが、記載されているものとは異なる条件で発生します
• 再現できず：記載された手順に従っても再現できませんでした
• 関連イシューを発見：テスト中に、異なるものの関連する問題が見つかりました

---

フェーズ 4：根本原因を調査する（再現できた場合）

問題を再現できた場合は、対象を絞ってコードベースを分析します。

1. 影響を受けるコンポーネントを特定する — 関連するファイル／フック／コンポーネントはどれですか？
2. 関連するソースコードを読む — 現在の実装を理解します
3. データの流れを追跡する — データはどこから来ていますか？SSE？REST？React Query？useState？
4. 根本原因を特定する — 観察された動作の具体的な原因は何ですか？
5. 類似するパターンを確認する — 同じ問題がほかのコンポーネントでも発生する可能性はありますか？

---

フェーズ 5：推奨事項

トレードオフを含む複数の修正案を提示します。

提案の形式

各提案について：

### Option N: {Short title}

**Approach**: {1-2 sentence description}

**Changes required**:
- {file}: {what changes}
- {file}: {what changes}

**Pros**:
- {benefit}

**Cons**:
- {drawback}

**Complexity**: Low / Medium / High
**Risk**: Low / Medium / High

簡単な修正から包括的な解決策まで、少なくとも 2〜3 個の選択肢を提示します。

---

フェーズ 6：クリーンアップ

# Close the browser
agent-browser close

# Stop Archon (optional — leave running if user wants to continue testing)
# fuser -k 3090/tcp 2>/dev/null
# fuser -k 5173/tcp 2>/dev/null

---

フェーズ 7：サマリーレポート

最終的なサマリーをユーザーに提示します。

# Issue #$ARGUMENTS Replication Report

## Issue: {title}
**Status**: Reproduced / Not Reproduced / Partially Reproduced
**Tested on**: main @ {commit hash}

## Reproduction Summary
{2-3 sentences describing what was tested and the outcome}

## Findings
{Detailed findings with screenshot references}

## Root Cause
{If identified — what causes the bug and why}

## Related Issues Discovered
{Any additional problems found during testing}

## Recommendations
{Summary of fix options with recommended approach}

---

実行時の注意事項

• 必ず Playwright ではなく、agent-browser（Vercel Agent Browser CLI）を使用します
• コマンドの参照が必要な場合は、/agent-browser スキルを読み込みます
• 重要なテストポイントごとに必ずスクリーンショットを撮影します。これらが証拠になります
• Read ツールでスクリーンショットを読み取り、UI の表示を目視で確認します
• 再現に長時間の操作が必要な場合は、ワークフローが完了するまで待ちます
• ブラウザーの状態を API レスポンス（curl）と照合し、UI の問題かバックエンドの問題かを切り分けます
• 問題を再現できない場合は、試した内容を記録し、考えられる理由を提示します
• 作業が終わったら、ブラウザーを閉じます：agent-browser close