/replicate-issue

name: replicate-issue
description: |
  Replicate and validate a GitHub issue by spinning up Archon, analyzing the issue,
  and systematically testing all described symptoms using browser automation.
  Use when: User wants to reproduce a bug, validate a GitHub issue, confirm a reported problem,
  or investigate whether an issue is real before working on a fix.
  Triggers: "replicate issue", "reproduce issue", "validate issue", "confirm bug",
            "test issue", "can you reproduce", "try to replicate", "verify the bug".
  Capability: Checks out main, pulls latest, starts Archon, reads the GitHub issue,
  then uses agent-browser to systematically test every symptom and produce a findings report.
  NOT for: Fixing issues (use /archon or /exp-piv-loop:fix-issue), general UI testing (use /validate-ui).
argument-hint: "[issue-number]"
disable-model-invocation: true
allowed-tools: Bash, Read, Grep, Glob, WebFetch, Agent

Replicate GitHub Issue

Systematically reproduce and validate a GitHub issue against the live Archon application. The goal: determine whether the reported behavior is real, identify exact reproduction steps, discover any related issues, and provide actionable fix recommendations.

**Issue number**: `$ARGUMENTS`

If `$ARGUMENTS` is empty, ask the user for the issue number before proceeding.

---

Phase 0: Prepare Environment

0.1 Switch to Main Branch and Pull Latest

Ensure you are testing against the latest code on `main` so results are accurate.

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 Kill Existing Archon Processes

Free up ports 3090 (backend) and 5173 (frontend) so Archon starts cleanly.

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 Start Archon Backend + Frontend

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

**Note**: If port 5173 is taken, Vite auto-increments (5174, 5175, etc.). Check the `bun run dev` output for the actual frontend port and use that throughout.

---

Phase 1: Analyze the Issue

1.1 Read the GitHub Issue

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

Parse the issue carefully. Extract:

• **Title and summary**: What is the reported problem?
• **Reproduction steps**: What specific actions trigger the bug?
• **Expected behavior**: What should happen?
• **Actual behavior**: What happens instead?
• **Environment details**: Any specific conditions (browser, OS, timing)?
• **Labels and priority**: How severe is this?
• **Comments**: Any additional context, workarounds, or related issues?

1.2 Build a Test Plan

Based on the issue content, create a checklist of specific things to test. For each symptom described in the issue, define: 1. The exact user journey to reproduce it 2. What to look for (expected vs actual) 3. Screenshots to capture as evidence

---

Phase 2: Reproduce with Browser Automation

Use the `agent-browser` CLI (NOT Playwright) for all browser interactions.

Core Workflow

# 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

Testing Guidelines

• **Take screenshots liberally** — before and after each action, save to `/tmp/issue-$ARGUMENTS-*.png`
• **Read every screenshot** — use the Read tool to visually inspect each screenshot and verify what you see
• **Test the happy path first** — confirm the feature works under normal conditions before testing the bug
• **Follow the exact reproduction steps** from the issue — don't shortcut
• **Test variations** — try the same flow with slight differences (different data, different timing, page refresh)
• **Test adjacent flows** — if the issue is about workflow X, also check workflows Y and Z for similar problems
• **Use curl for API verification** — cross-reference UI state with direct API calls to confirm data accuracy
• **Check after page refresh** — many SSE/real-time bugs only manifest after navigation or refresh
• **Check across conversations** — if the issue involves conversations, test with multiple open conversations
• **Wait for async operations** — use `agent-browser wait` commands for network-dependent operations

Triggering Workflows (if needed)

If the issue involves workflow execution, use the REST API to trigger background workflows:

# 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\"}"

Triggering Chat Messages (if needed)