Claude-Code-Workflow/.codex/skills/team-frontend-debug/instructions/agent-instruction.md

Agent Instruction Template -- Team Frontend Debug

Base instruction template for CSV wave agents. The orchestrator dynamically customizes this per role during Phase 1, writing role-specific versions to role-instructions/{role}.md.

Purpose

Phase	Usage
Phase 1	Coordinator generates per-role instruction from this template
Phase 2	Injected as instruction parameter to spawn_agents_on_csv

---

Base Instruction Template

## TASK ASSIGNMENT -- Team Frontend Debug

### MANDATORY FIRST STEPS
1. Read shared discoveries: <session-folder>/discoveries.ndjson (if exists, skip if not)
2. Read project context: .workflow/project-tech.json (if exists)

---

## Your Task

**Task ID**: {id}
**Title**: {title}
**Role**: {role}
**Pipeline Mode**: {pipeline_mode}
**Base URL**: {base_url}
**Evidence Dimensions**: {evidence_dimensions}

### Task Description
{description}

### Previous Tasks' Findings (Context)
{prev_context}

---

## Execution Protocol

1. **Read discoveries**: Load <session-folder>/discoveries.ndjson for shared exploration findings
2. **Use context**: Apply previous tasks' findings from prev_context above
3. **Execute task**: Follow role-specific instructions below
4. **Share discoveries**: Append exploration findings to shared board:
   ```bash
   echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> <session-folder>/discoveries.ndjson

5. Report result: Return JSON via report_agent_job_result

Discovery Types to Share

• feature_tested: {feature, name, result, issues} -- Feature test result
• bug_reproduced: {url, steps, console_errors, network_failures} -- Bug reproduction outcome
• evidence_collected: {dimension, file, description} -- Evidence artifact saved
• root_cause_found: {category, file, line, confidence} -- Root cause identified
• file_modified: {file, change, lines_added} -- Code fix applied
• verification_result: {verdict, original_error_resolved, new_errors} -- Verification outcome
• issue_found: {file, line, severity, description} -- Issue discovered

---

Output (report_agent_job_result)

Return JSON: { "id": "{id}", "status": "completed" | "failed", "findings": "Key discoveries and implementation notes (max 500 chars)", "artifacts_produced": "semicolon-separated paths of produced files", "issues_count": "", "verdict": "", "error": "" }

---

## Role-Specific Customization

The coordinator generates per-role instruction variants during Phase 1.

### For Tester Role (test-pipeline)

3. Execute:
   • Parse feature list from task description
   • For each feature: a. Navigate to feature URL: mcp__chrome-devtools__navigate_page({ type: "url", url: "<base_url>" }) b. Wait for page load: mcp__chrome-devtools__wait_for({ text: [""], timeout: 10000 }) c. Explore page structure: mcp__chrome-devtools__take_snapshot() d. Generate test scenarios from UI elements if not predefined e. Capture baseline: take_screenshot (before), list_console_messages f. Execute test steps: map step descriptions to MCP actions
     • Click: take_snapshot -> find uid -> click({ uid })
     • Fill: take_snapshot -> find uid -> fill({ uid, value })
     • Hover: take_snapshot -> find uid -> hover({ uid })
     • Wait: wait_for({ text: ["expected"] })
     • Navigate: navigate_page({ type: "url", url: "path" })
     • Press key: press_key({ key: "Enter" }) g. Capture result: take_screenshot (after), list_console_messages (errors), list_network_requests h. Evaluate: console errors? network failures? expected text present? visual issues? i. Classify: pass / fail / warning
   • Compile test report: /artifacts/TEST-001-report.md
   • Compile issues list: /artifacts/TEST-001-issues.json
   • Set issues_count in output

### For Reproducer Role (debug-pipeline)

3. Execute:
   • Verify browser accessible: mcp__chrome-devtools__list_pages()
   • Navigate to target URL: mcp__chrome-devtools__navigate_page({ type: "url", url: "" })
   • Wait for load: mcp__chrome-devtools__wait_for({ text: [""], timeout: 10000 })
   • Capture baseline evidence:
     • Screenshot (before): take_screenshot({ filePath: "/evidence/before-screenshot.png" })
     • DOM snapshot (before): take_snapshot({ filePath: "/evidence/before-snapshot.txt" })
     • Console baseline: list_console_messages()
   • Execute reproduction steps:
     • For each step, parse action and execute via MCP tools
     • Track DOM changes via snapshots after key steps
   • Capture post-action evidence:
     • Screenshot (after): take_screenshot({ filePath: "/evidence/after-screenshot.png" })
     • DOM snapshot (after): take_snapshot({ filePath: "/evidence/after-snapshot.txt" })
     • Console errors: list_console_messages({ types: ["error", "warn"] })
     • Network requests: list_network_requests({ resourceTypes: ["xhr", "fetch"] })
     • Request details for failures: get_network_request({ reqid: })
     • Performance trace (if dimension): performance_start_trace() + reproduce + performance_stop_trace()
   • Write evidence-summary.json to /evidence/

### For Analyzer Role

3. Execute:
   • Load evidence from upstream (reproducer evidence/ or tester artifacts/)
   • Console error analysis (priority):
     • Filter by type: error > warn > log
     • Extract stack traces, identify source file:line
     • Classify: TypeError, ReferenceError, NetworkError, etc.
   • Network analysis (if dimension):
     • Identify failed requests (4xx, 5xx, timeout, CORS)
     • Check auth tokens, API endpoints, payload issues
   • DOM structure analysis (if snapshots):
     • Compare before/after snapshots
     • Identify missing/extra elements, attribute anomalies
   • Performance analysis (if trace):
     • Identify long tasks (>50ms), layout thrashing, memory leaks
   • Cross-correlation: build timeline, identify trigger point
   • Source code mapping:
     • Use mcp__ace-tool__search_context or Grep to locate root cause
     • Read identified source files
   • Confidence assessment:
     • High (>80%): clear stack trace + specific line
     • Medium (50-80%): likely cause, needs confirmation
     • Low (<50%): request more evidence (set findings to include "need_more_evidence")
   • Write RCA report to /artifacts/ANALYZE-001-rca.md
   • Set issues_count in output

### For Fixer Role

3. Execute:
   • Load RCA report from analyzer output
   • Extract root cause: category, file, line, recommended fix
   • Read identified source files
   • Search for similar patterns: mcp__ace-tool__search_context
   • Plan fix: minimal change addressing root cause
   • Apply fix strategy by category:
     • TypeError/null: add null check, default value
     • API error: fix URL, add error handling
     • Missing import: add import statement
     • CSS/rendering: fix styles, layout
     • State bug: fix state update logic
     • Race condition: add async handling
   • Implement fix using Edit tool (fallback: mcp__ccw-tools__edit_file)
   • Validate: run syntax/type checks
   • Document changes in /artifacts/FIX-001-changes.md

### For Verifier Role

3. Execute:
   • Load original evidence (reproducer) and fix changes (fixer)
   • Pre-verification: check modified files contain expected changes
   • Navigate to same URL: mcp__chrome-devtools__navigate_page
   • Execute EXACT same reproduction/test steps
   • Capture post-fix evidence:
     • Screenshot: take_screenshot({ filePath: "/evidence/verify-screenshot.png" })
     • DOM snapshot: take_snapshot({ filePath: "/evidence/verify-snapshot.txt" })
     • Console: list_console_messages({ types: ["error", "warn"] })
     • Network: list_network_requests({ resourceTypes: ["xhr", "fetch"] })
   • Compare evidence:
     • Console: original error gone?
     • Network: failed request now succeeds?
     • Visual: expected rendering achieved?
     • New errors: any regression?
   • Determine verdict:
     • pass: original resolved AND no new errors
     • pass_with_warnings: original resolved BUT new issues
     • fail: original still present
   • Write verification report to /artifacts/VERIFY-001-report.md
   • Set verdict in output

---

## Chrome DevTools MCP Reference

### Common Patterns

**Navigate and Wait**:

mcp__chrome-devtools__navigate_page({ type: "url", url: "" }) mcp__chrome-devtools__wait_for({ text: [""], timeout: 10000 })

**Find Element and Interact**:

mcp__chrome-devtools__take_snapshot() // Get uids mcp__chrome-devtools__click({ uid: "" }) mcp__chrome-devtools__fill({ uid: "", value: "" })

**Capture Evidence**:

mcp__chrome-devtools__take_screenshot({ filePath: "" }) mcp__chrome-devtools__list_console_messages({ types: ["error", "warn"] }) mcp__chrome-devtools__list_network_requests({ resourceTypes: ["xhr", "fetch"] })

**Debug API Error**:

mcp__chrome-devtools__list_network_requests() // Find request mcp__chrome-devtools__get_network_request({ reqid: }) // Inspect details

---

## Quality Requirements

All agents must verify before reporting complete:

| Requirement | Criteria |
|-------------|----------|
| Files produced | Verify all claimed artifacts exist via Read |
| Evidence captured | All planned dimensions have evidence files |
| Findings accuracy | Findings reflect actual observations |
| Discovery sharing | At least 1 discovery shared to board |
| Error reporting | Non-empty error field if status is failed |
| Verdict set | verifier role sets verdict field |
| Issues count set | tester/analyzer roles set issues_count field |

---

## Placeholder Reference

| Placeholder | Resolved By | When |
|-------------|------------|------|
| `<session-folder>` | Skill designer (Phase 1) | Literal path baked into instruction |
| `{id}` | spawn_agents_on_csv | Runtime from CSV row |
| `{title}` | spawn_agents_on_csv | Runtime from CSV row |
| `{description}` | spawn_agents_on_csv | Runtime from CSV row |
| `{role}` | spawn_agents_on_csv | Runtime from CSV row |
| `{pipeline_mode}` | spawn_agents_on_csv | Runtime from CSV row |
| `{base_url}` | spawn_agents_on_csv | Runtime from CSV row |
| `{evidence_dimensions}` | spawn_agents_on_csv | Runtime from CSV row |
| `{prev_context}` | spawn_agents_on_csv | Runtime from CSV row |