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)

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

Phase 3: Document Findings

For each symptom in the issue, record:

Severity Classification

• Confirmed (Reproducible): The exact bug described in the issue was reproduced
• Partially Confirmed: The symptom appears but under different conditions than described
• Not Reproduced: Could not reproduce despite following the described steps
• Related Issue Found: A different but related problem was discovered during testing

Phase 4: Investigate Root Cause (if reproduced)

If the issue was reproduced, do a targeted codebase analysis:

1. Identify the affected components — which files/hooks/components are involved?
2. Read the relevant source code — understand the current implementation
3. Trace the data flow — where does the data come from? SSE? REST? React Query? useState?
4. Identify the root cause — what specifically causes the observed behavior?
5. Check for similar patterns — are other components vulnerable to the same issue?

Phase 5: Recommendations

Provide multiple fix options with trade-offs:

Option Format

For each recommendation:

### 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

Provide at least 2-3 options ranging from quick fix to comprehensive solution.

Phase 6: Cleanup

# 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

Phase 7: Summary Report

Present a final summary to the user:

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

Execution Notes

• Always use agent-browser (Vercel Agent Browser CLI), NOT Playwright
• Load the /agent-browser skill if you need a command reference
• Take screenshots at EVERY significant test point — these are your evidence
• Read screenshots with the Read tool to visually verify what the UI shows
• If reproduction requires long-running operations, be patient — wait for workflows to complete
• Cross-reference browser state with API responses (curl) to distinguish UI bugs from backend bugs
• If the issue cannot be reproduced, document what you tried and suggest possible reasons
• Close the browser when finished: agent-browser close