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

$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.

bash

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.

bash

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

bash

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

bash

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:

The exact user journey to reproduce it
What to look for (expected vs actual)
Screenshots to capture as evidence

Phase 2: Reproduce with Browser Automation

Use the

agent-browser

CLI (NOT Playwright) for all browser interactions.

Core Workflow

bash

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

bash

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

bash

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:

Symptom	Reproduced?	Evidence	Notes
{symptom from issue}	YES / NO / PARTIAL	Screenshot path	{details}

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:

Identify the affected components — which files/hooks/components are involved?
Read the relevant source code — understand the current implementation
Trace the data flow — where does the data come from? SSE? REST? React Query? useState?
Identify the root cause — what specifically causes the observed behavior?
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:

markdown

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

bash

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

markdown

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

replicate-issue

NPX Install

Tags

SKILL.md Content

Replicate GitHub Issue

Phase 0: Prepare Environment

0.1 Switch to Main Branch and Pull Latest

0.2 Kill Existing Archon Processes

0.3 Start Archon Backend + Frontend

Phase 1: Analyze the Issue

1.1 Read the GitHub Issue

1.2 Build a Test Plan

Phase 2: Reproduce with Browser Automation

Core Workflow

Testing Guidelines

Triggering Workflows (if needed)

Triggering Chat Messages (if needed)

Phase 3: Document Findings

Severity Classification

Phase 4: Investigate Root Cause (if reproduced)

Phase 5: Recommendations

Option Format

Phase 6: Cleanup

Phase 7: Summary Report

Execution Notes