team-frontend-debug

# Frontend Debug Team Dual-mode frontend debugging: feature-list testing or bug-report debugging, powered by Chrome DevTools MCP. ## Architecture ``` Skill(skill="team-frontend-debug", args="feature list or bug description") | SKILL.md (this file) = Router | +--------------+--------------+ | | no --role flag --role <name> | | Coordinator Worker roles/coordinator/role.md roles/<name>/role.md | +-- analyze input → select pipeline → dispatch → spawn → STOP | ┌──────────────────────────┼──────────────────────┐ v v v [test-pipeline] [debug-pipeline] [shared] tester(DevTools) reproducer(DevTools) analyzer fixer verifier ``` ## Pipeline Modes | Input | Pipeline | Flow | |-------|----------|------| | Feature list / 功能清单 | `test-pipeline` | TEST → ANALYZE → FIX → VERIFY | | Bug report / 错误描述 | `debug-pipeline` | REPRODUCE → ANALYZE → FIX → VERIFY | ## Role Registry | Role | Path | Prefix | Inner Loop | |------|------|--------|------------| | coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — | | tester | [roles/tester/role.md](roles/tester/role.md) | TEST-* | true | | reproducer | [roles/reproducer/role.md](roles/reproducer/role.md) | REPRODUCE-* | false | | analyzer | [roles/analyzer/role.md](roles/analyzer/role.md) | ANALYZE-* | false | | fixer | [roles/fixer/role.md](roles/fixer/role.md) | FIX-* | true | | verifier | [roles/verifier/role.md](roles/verifier/role.md) | VERIFY-* | false | ## Role Router Parse `$ARGUMENTS`: - Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4 - No `--role` → `roles/coordinator/role.md`, execute entry router ## Delegation Lock **Coordinator is a PURE ORCHESTRATOR. It coordinates, it does NOT do.** Before calling ANY tool, apply this check: | Tool Call | Verdict | Reason | |-----------|---------|--------| | `spawn_agent`, `wait_agent`, `close_agent`, `send_message`, `followup_task` | ALLOWED | Orchestration | | `list_agents` | ALLOWED | Agent health check | | `request_user_input` | ALLOWED | User interaction | | `mcp__ccw-tools__team_msg` | ALLOWED | Message bus | | `Read/Write` on `.workflow/.team/` files | ALLOWED | Session state | | `Read` on `roles/`, `commands/`, `specs/` | ALLOWED | Loading own instructions | | `Read/Grep/Glob` on project source code | BLOCKED | Delegate to worker | | `Edit` on any file outside `.workflow/` | BLOCKED | Delegate to worker | | `Bash("ccw cli ...")` | BLOCKED | Only workers call CLI | | `Bash` running build/test/lint commands | BLOCKED | Delegate to worker | **If a tool call is BLOCKED**: STOP. Create a task, spawn a worker. **No exceptions for "simple" tasks.** Even a single-file read-and-report MUST go through spawn_agent. --- ## Shared Constants - **Session prefix**: `TFD` - **Session path**: `.workflow/.team/TFD-<date>-<slug>/` - **CLI tools**: `ccw cli --mode analysis` (read-only), `ccw cli --mode write` (modifications) - **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)` ## Workspace Resolution Coordinator MUST resolve paths at Phase 2 before spawning workers: 1. Run `Bash({ command: "pwd" })` → capture `project_root` (absolute path) 2. `skill_root = <project_root>/.claude/skills/team-frontend-debug` 3. Store in `team-session.json`: ```json { "project_root": "/abs/path/to/project", "skill_root": "/abs/path/to/skill" } ``` 4. All worker `role_spec` values MUST use `<skill_root>/roles/<role>/role.md` (absolute) This ensures workers always receive an absolute, resolvable path regardless of their working directory. ## Chrome DevTools MCP Tools All browser inspection operations use Chrome DevTools MCP. Reproducer and Verifier are primary consumers. | Tool | Purpose | |------|---------| | `mcp__chrome-devtools__navigate_page` | Navigate to target URL | | `mcp__chrome-devtools__take_screenshot` | Capture visual state | | `mcp__chrome-devtools__take_snapshot` | Capture DOM/a11y tree | | `mcp__chrome-devtools__list_console_messages` | Read console logs | | `mcp__chrome-devtools__get_console_message` | Get specific console message | | `mcp__chrome-devtools__list_network_requests` | Monitor network activity | | `mcp__chrome-devtools__get_network_request` | Inspect request/response detail | | `mcp__chrome-devtools__performance_start_trace` | Start performance recording | | `mcp__chrome-devtools__performance_stop_trace` | Stop and analyze trace | | `mcp__chrome-devtools__click` | Simulate user click | | `mcp__chrome-devtools__fill` | Fill form inputs | | `mcp__chrome-devtools__hover` | Hover over elements | | `mcp__chrome-devtools__evaluate_script` | Execute JavaScript in page | | `mcp__chrome-devtools__wait_for` | Wait for element/text | | `mcp__chrome-devtools__list_pages` | List open browser tabs | | `mcp__chrome-devtools__select_page` | Switch active tab | ## Worker Spawn Template Coordinator spawns workers using this template: ``` spawn_agent({ agent_type: "team_worker", task_name: "<task-id>", fork_turns: "none", message: `## Role Assignment role: <role> role_spec: <skill_root>/roles/<role>/role.md session: <session-folder> session_id: <session-id> requirement: <task-description> inner_loop: <true|false> Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions. ## Task Context task_id: <task-id> title: <task-title> description: <task-description> pipeline_phase: <pipeline-phase> ## Upstream Context <prev_context>` }) ``` After spawning, use `wait_agent({ timeout_ms: 1800000 })` to collect results. If `result.timed_out`, send STATUS_CHECK via followup_task (wait 3 min), then FINALIZE with interrupt (wait 3 min), then mark timed_out and close agents. Use `close_agent({ target })` each worker. ### Model Selection Guide Debug workflows require tool-heavy interaction (Chrome DevTools MCP). Reasoning effort varies by role. | Role | reasoning_effort | Rationale | |------|-------------------|-----------| | tester | medium | Systematic feature testing via DevTools, follows test plan | | reproducer | medium | Reproduce bugs via DevTools interaction steps | | analyzer | high | Root cause analysis requires deep reasoning about evidence | | fixer | high | Code fixes must address root cause precisely | | verifier | medium | Verification follows defined success criteria via DevTools | ## User Commands | Command | Action | |---------|--------| | `check` / `status` | View execution status graph | | `resume` / `continue` | Advance to next step | | `revise <TASK-ID> [feedback]` | Revise specific task | | `feedback <text>` | Inject feedback for revision | | `retry <TASK-ID>` | Re-run a failed task | ## v4 Agent Coordination ### Message Semantics | Intent | API | Example | |--------|-----|---------| | Queue supplementary info (don't interrupt) | `send_message` | Send DevTools evidence to running analyzer | | Assign new work / trigger debug round | `followup_task` | Assign re-fix after verification failure | | Check running agents | `list_agents` | Verify agent health during resume | ### Agent Health Check Use `list_agents({})` in handleResume and handleComplete: ``` // Reconcile session state with actual running agents const running = list_agents({}) // Compare with team-session.json active tasks // Reset orphaned tasks (in_progress but agent gone) to pending ``` ### Named Agent Targeting Workers are spawned with `task_name: "<task-id>"` enabling direct addressing: - `send_message({ target: "ANALYZE-001", message: "..." })` -- send evidence from reproducer to analyzer - `followup_task({ target: "FIX-001", message: "..." })` -- assign fix based on analysis results - `close_agent({ target: "VERIFY-001" })` -- cleanup after verification ### Iterative Debug Loop Pattern When verifier reports a fix did not resolve the issue, coordinator uses `followup_task` to trigger re-analysis and re-fix: ``` // Verifier reports failure -> coordinator dispatches re-fix followup_task({ target: "FIX-001", // reuse existing fixer if inner_loop, or spawn new message: `## Re-fix Assignment verification_result: FAIL failure_evidence: <verifier's screenshot/console evidence> previous_fix_summary: <what was tried> instruction: Analyze verification failure and apply corrected fix.` }) ``` This pattern enables iterative debug rounds: FIX -> VERIFY -> re-FIX -> re-VERIFY (max 3 rounds). ## Completion Action When pipeline completes, coordinator presents: ``` functions.request_user_input({ questions: [{ question: "Pipeline complete. What would you like to do?", header: "Completion", multiSelect: false, options: [ { label: "Archive & Clean (Recommended)", description: "Archive session, clean up" }, { label: "Keep Active", description: "Keep session for follow-up debugging" }, { label: "Export Results", description: "Export debug report and patches" } ] }] }) ``` ## Specs Reference - [specs/pipelines.md](specs/pipelines.md) — Pipeline definitions and task registry - [specs/debug-tools.md](specs/debug-tools.md) — Chrome DevTools MCP usage patterns and evidence collection ## Session Directory ``` .workflow/.team/TFD-<date>-<slug>/ ├── team-session.json # Session state + role registry ├── evidence/ # Screenshots, snapshots, network logs ├── artifacts/ # Test reports, RCA reports, patches, verification reports ├── wisdom/ # Cross-task debug knowledge └── .msg/ # Team message bus ``` ## Error Handling | Scenario | Resolution | |----------|------------| | All features pass test | Report success, pipeline completes without ANALYZE/FIX/VERIFY | | Bug not reproducible | Reproducer reports failure, coordinator asks user for more details | | Browser not available | Report error, suggest manual reproduction steps | | Analysis inconclusive | Analyzer requests more evidence via iteration loop | | Fix introduces regression | Verifier reports fail, coordinator dispatches re-fix | | No issues found in test | Skip downstream tasks, report all-pass | | Unknown command | Error with available command list | | Role not found | Error with role registry |