Run Parallel Agents Feature Debug

<EXTREMELY-IMPORTANT> This skill orchestrates real Agent tool executions. Non-negotiable rules: 1. Prove the failures do not share a root cause before parallelizing them. 2. Write a complete prompt for every spawned agent because fresh subagent_type agents do not inherit task context. 3. Launch all parallel agents in a single assistant message with multiple Agent(...) tool uses. 4. Use run_in_background: true for independent debug lanes and do not poll background output. 5. Use isolation: "worktree" for debug lanes that may modify code. </EXTREMELY-IMPORTANT>

Run Parallel Agents Feature Debug

Inputs

• $request: Optional problem set, failure list, or user direction such as debug these three failing suites in parallel or split these bugs across agents.

Goal

Exploit Claude Code's real parallel agent runtime to diagnose and fix independent failures concurrently without splitting one root cause into multiple conflicting investigations.

Step 0: Resolve the candidate debug lanes

Identify the failure set:

• explicit user bug list
• failing test groups
• broken subsystems
• grouped compile, lint, runtime, or performance failures

Then determine:

• failure count
• likely subsystem boundaries
• whether each failure is a symptom or a standalone issue
• whether the lanes are debug/fix work rather than planning or broad exploration

Do not use this skill if:

• there are fewer than 3 independent lanes
• the failures may share one root cause
• one broken dependency, config value, schema change, or deploy event could explain multiple symptoms
• the work still needs decomposition before execution

Use AskUserQuestion only if safe clustering depends on user clarification.

Success criteria: You have a concrete set of candidate debug lanes worth triaging for independence.

Step 1: Prove independence and reject shared-root-cause traps

For each candidate lane, check:

• whether the failure started at the same time as other lanes
• whether the same dependency, config, migration, environment, or upstream service appears in multiple traces
• whether one fix could plausibly collapse several symptoms
• whether the write scope is disjoint if multiple lanes reach the fix stage

Parallelize only when:

• root cause is plausibly distinct
• reproduction is lane-local
• expected fixes do not overlap heavily

If there is meaningful doubt, do not parallelize yet. Diagnose the shared root cause first.

Load references/debug_patterns.md for root-cause heuristics and framework-specific failure patterns. Load references/agent-runtime-semantics.md for the runtime rules that make or break parallel debug execution.

Success criteria: Every selected lane is likely independent at both diagnosis and fix time.

Step 2: Match each debug lane to the right agent

Choose the most appropriate specialized agent for each lane based on:

• framework and language
• failing files and directories
• error signatures
• whether the lane is runtime, test, build, or performance focused

Load references/agent_matching_logic.md for detailed matching rules and edge cases.

Practical defaults:

• use the most specific framework/domain agent available
• use general-purpose only when no stronger fit exists
• do not invent agent types

Success criteria: Every lane has a justified debug agent assignment.

Step 3: Build full debugging briefs

Because fresh subagent_type agents start without the main thread's task context, every prompt must contain:

• the exact problem statement
• the concrete error or symptom
• reproduction steps, if known
• affected files or directories
• likely scope boundaries
• what counts as success
• required verification command or test
• whether the lane should only diagnose or both diagnose and fix

Prefer real evidence over summaries:

• failing command output
• stack trace excerpts
• failing test names
• impacted file paths

Do not hand a fresh agent vague instructions like "fix this suite" without the actual failure surface.

Success criteria: Each lane prompt is complete enough for a fresh agent to diagnose without basic follow-up questions.

Step 4: Launch all agents in one parallel batch

Launch every lane in a single assistant message containing multiple Agent(...) tool uses.

Required launch semantics for fix-capable debug lanes:

• subagent_type: matched agent type
• description: short 3-5 word description
• prompt: full debugging brief
• run_in_background: true
• isolation: "worktree"

Runtime-specific rules:

• do not split the launches across multiple assistant messages if the user asked for parallel debugging
• do not rely on target-agent defaults for async or isolation when parallel safety matters
• do not use read-only forks here; this skill is for fresh specialized debug agents

Load references/agent-runtime-semantics.md for the exact source-backed reasons behind these rules.

Success criteria: All independent debug lanes are launched concurrently with explicit, safe runtime settings.

Step 5: Aggregate completions without polling

After launch:

• continue with non-overlapping coordination work
• wait for completion notifications instead of polling background transcripts
• trust returned agent summaries unless there is a concrete reason to inspect deeper

When each lane completes, capture:

• status
• diagnosed root cause
• files touched
• verification result
• blockers or unresolved scope

If a lane concludes the issue was not independent after all, stop pretending the original clustering was valid and reframe the remaining work.

Success criteria: Every spawned lane has a tracked outcome without unnecessary transcript noise.

Step 6: Validate fixes and check for conflicts

Before treating the parallel debug session as complete:

• rerun the original failing test or validation command for each lane
• confirm the original symptom is actually gone
• check for overlapping file edits or contradictory fixes
• confirm one lane did not silently re-break another lane's subsystem

If conflicts exist:

• stop automatic aggregation
• identify the overlapping files or contradictory fixes
• merge intentionally or escalate to the user

If multiple lanes converged on the same root cause:

• say so explicitly
• consolidate the result instead of pretending they were independent wins

Success criteria: The final result reflects real fixes, not just parallel patch attempts.

Step 7: Report the consolidated result

Summarize:

• which debug lanes ran
• which agents handled them
• root cause and fix status per lane
• verification result per lane
• conflicts, converged root causes, or remaining blockers

Be explicit about partial success. Debugging is only finished when the original failures are actually resolved or clearly re-scoped.

Success criteria: The user gets a concise but accurate parallel-debug summary.

Guardrails

• Do not use this skill for fewer than 3 genuinely independent lanes.
• Do not parallelize symptoms that may share a root cause.
• Do not keep giant examples, scorecards, or framework catalogs inline in SKILL.md.
• Do not assume fresh agents know the surrounding task context.
• Do not poll or tail background agent output unless the user explicitly asks.
• Do not rely on default agent background or isolation settings when explicit launch parameters are safer.
• Do not add disable-model-invocation; this skill should remain available when the user asks for parallel debugging.
• Do not add context: fork; this workflow coordinates fresh specialized agents, not read-only skill forks.
• Do not add paths:; this is a generic orchestration skill.

When To Load References

• references/agent-runtime-semantics.md

Use for source-backed Agent runtime rules: fresh context, single-message parallel launch, background behavior, worktree isolation, and explicit parameter precedence.

• references/debug_patterns.md

Use for shared-root-cause heuristics, framework-specific error patterns, and triage guidance.

• references/agent_matching_logic.md

Use for detailed agent-selection rules and framework-specific edge cases.

Output Contract

Report:

1. resolved debug lane set 2. agent assignment per lane 3. launch status 4. root cause and fix status per lane 5. verification results 6. conflicts, shared-cause discoveries, or remaining blockers

Agent Matching Logic Reference

This document provides detailed rules, patterns, and edge cases for matching features, tasks, and file types to the appropriate specialized agent.

Agent Type Catalog

laravel-senior-engineer

Primary Expertise:

• Laravel 12.x backend development
• Eloquent ORM and database operations (MySQL, Redis, DynamoDB)
• Queue systems with Horizon
• Service layer patterns
• RESTful API development
• Artisan commands and migrations

Technology Indicators:

• File extensions: *.php
• Directory patterns: /app/, /routes/, /database/, /config/
• Framework files: artisan, composer.json with Laravel dependencies
• Code patterns: Eloquent models, namespace App\, Laravel facades

Common Task Patterns:

• "Build API endpoint for..."
• "Create Eloquent model for..."
• "Implement queue job for..."
• "Add migration for..."
• "Create service class for..."

Edge Cases:

• Pure PHP without Laravel → Use general-purpose instead
• Magento PHP code → Use laravel-senior-engineer (Magento is PHP/Composer-based; closest match)
• WordPress PHP → Use general-purpose (no WordPress agent)

---

nextjs-senior-engineer

Primary Expertise:

• Next.js 14/15 with App Router
• React Server Components (RSC)
• Server Actions
• Client and server-side rendering strategies
• Advanced caching (revalidation, static generation)
• API routes and middleware

Technology Indicators:

• File extensions: *.tsx, *.jsx
• Directory patterns: /app/, /pages/, /components/
• Framework files: next.config.js, next.config.ts, package.json with next dependency
• Code patterns: 'use client', 'use server', Server Actions, RSC patterns

Common Task Patterns:

• "Build page for..."
• "Create React component for..."
• "Implement server action for..."
• "Add API route for..."
• "Build dashboard/UI for..."

Edge Cases:

• Pure React without Next.js → Use react-vite-tailwind-engineer for Vite/Tailwind setups, or nextjs-senior-engineer if it lives in a Next.js project
• Remix app → Use nextjs-senior-engineer (closest full-stack React framework agent) or react-vite-tailwind-engineer for UI-heavy work
• React Native → Use expo-react-native-engineer

---

react-vite-tailwind-engineer

Primary Expertise:

• React with Vite bundler
• Tailwind CSS styling
• TypeScript frontend development
• SPA architecture
• Component libraries and design systems
• Client-side routing (React Router, TanStack Router)

Technology Indicators:

• File extensions: *.tsx, *.jsx, *.css
• Directory patterns: /src/, /components/, /pages/
• Framework files: vite.config.ts, tailwind.config.ts, postcss.config.js, package.json with vite + react dependencies
• Code patterns: Tailwind utility classes, import.meta.env, Vite-specific patterns

Common Task Patterns:

• "Build React component with Tailwind for..."
• "Create Vite-based frontend for..."
• "Style component with Tailwind..."
• "Implement client-side routing for..."
• "Build design system component..."

Edge Cases:

• Next.js project with Tailwind → Use nextjs-senior-engineer (Next.js takes priority)
• React without Vite or Tailwind → Still use if it's a standalone React SPA
• Storybook components → Good match for component-focused work

---

express-senior-engineer

Primary Expertise:

• Express.js framework
• Middleware architecture
• RESTful API development
• Queue systems with Bull
• Logging with Pino
• Node.js server-side development
• NestJS projects (Express-based under the hood)

Technology Indicators:

• File extensions: *.js, *.ts
• Dependencies: package.json with express or @nestjs/*
• Code patterns: app.use(), app.get(), express.Router(), middleware functions, @Injectable(), @Controller()

Common Task Patterns:

• "Build Express API for..."
• "Create middleware for..."
• "Add REST endpoint for..."
• "Implement Express route handler for..."
• "Build NestJS module for..."
• "Create service with DI for..."

Edge Cases:

• NestJS projects → Use express-senior-engineer (NestJS uses Express under the hood)
• Fastify without Express → Use express-senior-engineer (closest Node.js API agent)
• Serverless functions → Use general-purpose unless explicitly Express-based

---

nodejs-cli-senior-engineer

Primary Expertise:

• Node.js CLI tool development
• commander.js / yargs argument parsing
• Interactive prompts (inquirer, prompts)
• File system operations
• Process management and child processes
• npm package publishing

Technology Indicators:

• File extensions: *.js, *.ts
• Framework files: package.json with commander or yargs dependency, bin field in package.json
• Directory patterns: /bin/, /cli/, /commands/
• Code patterns: #!/usr/bin/env node, program.command(), process.argv

Common Task Patterns:

• "Build CLI tool for..."
• "Add CLI command for..."
• "Implement interactive prompt for..."
• "Create npm CLI package for..."
• "Parse CLI arguments for..."

Edge Cases:

• Node.js script (not a CLI tool) → Use general-purpose
• Express-based server with CLI entry point → Use express-senior-engineer for the server, nodejs-cli-senior-engineer for the CLI

---

python-senior-engineer

Primary Expertise:

• Python backend development
• Django web framework
• Data pipelines and ETL
• SQLAlchemy and database operations
• Testing with pytest
• Package management (pip, poetry, uv)

Technology Indicators:

• File extensions: *.py
• Framework files: requirements.txt, pyproject.toml, setup.py, manage.py (Django)
• Directory patterns: /app/, /src/, /<project_name>/
• Code patterns: Django models, Python imports, decorators

Common Task Patterns:

• "Build Django view for..."
• "Create Python data pipeline for..."
• "Implement SQLAlchemy model for..."
• "Add pytest tests for..."
• "Build Python script for..."

Edge Cases:

• FastAPI project → Use fastapi-senior-engineer instead
• Jupyter notebooks / data science → Use general-purpose or python-senior-engineer depending on scope
• Pure scripting (no framework) → Use python-senior-engineer for Python-heavy work

---

fastapi-senior-engineer

Primary Expertise:

• FastAPI framework specifically
• Async database operations (SQLAlchemy async, Tortoise ORM)
• JWT authentication and OAuth2
• Pydantic models and validation
• Background tasks and Celery
• OpenAPI/Swagger documentation

Technology Indicators:

• File extensions: *.py
• Framework files: requirements.txt or pyproject.toml with fastapi dependency
• Directory patterns: /app/, /routers/, /schemas/, /models/
• Code patterns: @app.get(), @app.post(), async def, Pydantic BaseModel, Depends()

Common Task Patterns:

• "Build FastAPI endpoint for..."
• "Create Pydantic schema for..."
• "Implement JWT auth for..."
• "Add async database query for..."
• "Build background task for..."

Edge Cases:

• Django project → Use python-senior-engineer instead
• Flask project → Use python-senior-engineer (closest general Python agent)
• Python script with no web framework → Use python-senior-engineer

---

go-senior-engineer

Primary Expertise:

• Go backend services and APIs
• HTTP servers (net/http, Gin, Echo, Fiber)
• Database operations (database/sql, GORM, sqlx)
• Concurrency patterns (goroutines, channels)
• gRPC services
• Middleware and routing

Technology Indicators:

• File extensions: *.go
• Framework files: go.mod, go.sum
• Directory patterns: /cmd/, /internal/, /pkg/, /api/
• Code patterns: package main, func main(), http.HandleFunc, Go struct definitions

Common Task Patterns:

• "Build Go API for..."
• "Create HTTP handler for..."
• "Implement gRPC service for..."
• "Add database layer for..."
• "Build Go microservice for..."

Edge Cases:

• Go CLI tool → Use go-cli-senior-engineer instead
• Go library (no main) → Use go-senior-engineer for API/service libraries
• Go with AWS Lambda → Use go-senior-engineer for the Go code, devops-aws-senior-engineer for infra

---

go-cli-senior-engineer

Primary Expertise:

• Go CLI tool development
• Cobra command framework
• Viper configuration management
• Interactive terminal UIs (bubbletea, lipgloss)
• File system operations in Go
• Cross-platform binary distribution

Technology Indicators:

• File extensions: *.go
• Framework files: go.mod with cobra or viper dependency
• Directory patterns: /cmd/, /internal/
• Code patterns: cobra.Command{}, viper.Get*(), os.Args

Common Task Patterns:

• "Build Go CLI tool for..."
• "Add cobra command for..."
• "Implement CLI configuration with viper..."
• "Create terminal UI for..."
• "Build cross-platform CLI..."

Edge Cases:

• Go web server → Use go-senior-engineer instead
• Simple Go script (no cobra) → Use go-senior-engineer or go-cli-senior-engineer based on whether it's a CLI tool
• Go tool that is both CLI and server → Split: CLI parts to go-cli-senior-engineer, server parts to go-senior-engineer

---

ios-macos-senior-engineer

Primary Expertise:

• Swift and SwiftUI development
• Xcode project management
• Swift Package Manager (SPM)
• AVFoundation (audio/video)
• StoreKit (in-app purchases)
• Core Data and SwiftData
• iOS and macOS app development

Technology Indicators:

• File extensions: *.swift, *.xib, *.storyboard
• Framework files: Package.swift, *.xcodeproj, *.xcworkspace, Podfile
• Directory patterns: /*.xcodeproj/, /Sources/, /Tests/
• Code patterns: import SwiftUI, import UIKit, @Observable, struct ContentView: View

Common Task Patterns:

• "Build iOS screen for..."
• "Create SwiftUI view for..."
• "Implement StoreKit purchase for..."
• "Add AVFoundation player for..."
• "Build macOS menu bar app for..."

Edge Cases:

• Objective-C project → Use ios-macos-senior-engineer (Swift/ObjC interop is common)
• Cross-platform mobile (iOS + Android) → Use expo-react-native-engineer if React Native, or split: ios-macos-senior-engineer for iOS
• watchOS / tvOS → Use ios-macos-senior-engineer (closest Apple platform agent)

---

expo-react-native-engineer

Primary Expertise:

• Expo React Native development
• Expo Router for navigation
• Expo Modules API
• Cross-platform mobile (iOS/Android/web)
• react-native-logs for logging
• EAS deployment

Technology Indicators:

• File extensions: *.tsx, *.jsx
• Framework files: app.json (Expo config), package.json with expo dependency
• Directory patterns: /app/ (Expo Router)
• Code patterns: Expo modules, expo-router, React Native components

Common Task Patterns:

• "Build mobile screen for..."
• "Create Expo module for..."
• "Implement navigation for..."
• "Add mobile feature for..."
• "Build cross-platform app for..."

Edge Cases:

• Pure React Native without Expo → Use expo-react-native-engineer (still closest mobile agent)
• Web-only React → Use nextjs-senior-engineer or react-vite-tailwind-engineer
• Flutter mobile app → Use expo-react-native-engineer for mobile expertise or general-purpose

---

devops-aws-senior-engineer

Primary Expertise:

• AWS infrastructure and services
• AWS CDK (Infrastructure as Code)
• CloudFormation templates
• Terraform for AWS
• CI/CD pipelines (CodePipeline, GitHub Actions with AWS)
• IAM, VPC, Lambda, ECS, S3, RDS, DynamoDB

Technology Indicators:

• File extensions: *.ts (CDK), *.tf (Terraform), *.yaml/*.yml (CloudFormation)
• Framework files: cdk.json, *.tf, template.yaml, serverless.yml
• Directory patterns: /cdk/, /infra/, /terraform/, /cloudformation/
• Code patterns: new cdk.Stack, resource "aws_", AWS::, CDK constructs

Common Task Patterns:

• "Deploy to AWS..."
• "Create CDK stack for..."
• "Set up Terraform for..."
• "Configure IAM roles for..."
• "Build CI/CD pipeline for..."

Edge Cases:

• GCP or Azure → Use general-purpose (no GCP/Azure-specific agent)
• Docker without AWS → Use devops-docker-senior-engineer
• Kubernetes on AWS → Use devops-aws-senior-engineer for EKS, devops-docker-senior-engineer for container config

---

devops-docker-senior-engineer

Primary Expertise:

• Docker containerization
• Docker Compose multi-service orchestration
• Dockerfile optimization (multi-stage builds)
• Container networking and volumes
• Docker build caching strategies
• Container security best practices

Technology Indicators:

• File extensions: Dockerfile, docker-compose.yml, docker-compose.yaml, .dockerignore
• Directory patterns: /docker/, project root
• Code patterns: FROM, RUN, COPY, EXPOSE, services:, volumes:

Common Task Patterns:

• "Containerize application..."
• "Create Docker Compose for..."
• "Optimize Dockerfile for..."
• "Set up multi-stage build for..."
• "Configure Docker networking for..."

Edge Cases:

• Kubernetes YAML (not Docker) → Use devops-aws-senior-engineer if on AWS, else general-purpose
• Docker + AWS deployment → Split: devops-docker-senior-engineer for container config, devops-aws-senior-engineer for AWS infra

---

general-purpose

Primary Expertise:

• General research and exploration
• Multi-language code analysis
• File system operations
• Tasks not matching specific frameworks

Use When:

• No framework-specific patterns detected
• Exploratory tasks ("find all instances of...")
• Multi-framework analysis
• Configuration file edits
• Documentation generation
• Shell scripting
• Technologies without a dedicated agent (SvelteKit, Vue/Nuxt, Ruby on Rails, Java/Spring, etc.)

Common Task Patterns:

• "Search for..."
• "Analyze these files..."
• "Explore the codebase..."
• "Generate documentation for..."

---

Matching Algorithm

Step-by-Step Process

1. Check for explicit framework mentions in the task description

• If user says "Laravel API", match to laravel-senior-engineer
• If user says "Next.js page", match to nextjs-senior-engineer
• If user says "FastAPI endpoint", match to fastapi-senior-engineer
• If user says "Go service", match to go-senior-engineer
• If user says "iOS app", match to ios-macos-senior-engineer
• If user says "Docker setup", match to devops-docker-senior-engineer

2. Analyze file paths (if provided)

• Check file extensions: .php, .tsx, .py, .go, .swift, .dart, etc.
• Check directory patterns: /app/Http/ (Laravel), /cmd/ (Go), /Sources/ (Swift)

3. Search for framework config files in the workspace

• artisan + composer.json with Laravel → Laravel
• next.config.* → Next.js
• vite.config.* + tailwind.config.* → React Vite Tailwind
• app.json + expo dependency → Expo React Native
• go.mod + cobra dependency → Go CLI
• go.mod (no cobra) → Go
• Package.swift or *.xcodeproj → iOS/macOS
• pyproject.toml with fastapi → FastAPI
• manage.py or pyproject.toml with django → Python
• cdk.json or *.tf → DevOps AWS
• Dockerfile or docker-compose.yml → DevOps Docker
• nest-cli.json or @nestjs/* deps → Express (NestJS uses Express)

4. Analyze code patterns (if code is visible)

• Eloquent, namespace App\ → Laravel
• 'use client', 'use server' → Next.js
• Tailwind classes + Vite imports → React Vite Tailwind
• @app.get(), Depends() → FastAPI
• cobra.Command{} → Go CLI
• http.HandleFunc → Go
• import SwiftUI → iOS/macOS
• @Injectable(), @Controller() → Express (NestJS)
• app.use(), express.Router() → Express

5. Default to general-purpose if no clear match

Multi-Agent Scenarios

When a task requires multiple agent types:

Scenario 1: Full-stack feature

• User: "Build user profile with backend API and frontend page"
• Split into:
• Backend API → laravel-senior-engineer or express-senior-engineer or fastapi-senior-engineer
• Frontend page → nextjs-senior-engineer or react-vite-tailwind-engineer

Scenario 2: Backend microservices

• User: "Build payment service (Go) and notification handler (Express)"
• Split into:
• Payment service → go-senior-engineer
• Notification handler → express-senior-engineer

Scenario 3: Cross-platform

• User: "Build mobile app (Expo) and web dashboard (Next.js)"
• Split into:
• Mobile → expo-react-native-engineer
• Web → nextjs-senior-engineer

Scenario 4: Native + API

• User: "Build iOS app and Go backend API"
• Split into:
• iOS app → ios-macos-senior-engineer
• Backend API → go-senior-engineer

Scenario 5: Infra + App

• User: "Containerize the app and deploy to AWS"
• Split into:
• Docker setup → devops-docker-senior-engineer
• AWS deployment → devops-aws-senior-engineer

Scenario 6: CLI + Backend

• User: "Build a CLI tool that manages the Express API"
• Split into:
• CLI tool → nodejs-cli-senior-engineer or go-cli-senior-engineer
• API work → express-senior-engineer

---

File Pattern Detection Matrix

---

Edge Case Handling

Ambiguous File Extensions

Problem: TypeScript (.ts, .tsx) is used by Next.js, React Vite, NestJS, Express, and Expo

Solution:

1. Check for framework config files first 2. Look at directory structure 3. Examine import statements 4. Default to most common for the project if uncertain

Mixed Technology Stacks

Problem: Project uses both Laravel backend and Next.js frontend

Solution:

• Analyze which part of the stack the task targets
• If task spans both, split into two agents
• Use file paths to determine context

NestJS Projects

Problem: NestJS is a distinct framework but has no dedicated agent

Solution:

• Use express-senior-engineer (NestJS is built on Express)
• The Express agent handles TypeScript Node.js APIs, middleware, and dependency injection patterns
• NestJS decorators (@Injectable(), @Controller()) are recognizable patterns for the Express agent

Remix Projects

Problem: Remix is a React framework but has no dedicated agent

Solution:

• Use nextjs-senior-engineer for full-stack Remix work (loaders, actions, SSR)
• Use react-vite-tailwind-engineer for UI/component-heavy Remix work
• Both agents understand React patterns that Remix shares

Flutter / Dart Projects

Problem: Flutter has no dedicated agent

Solution:

• For mobile app logic → Use expo-react-native-engineer (closest mobile expertise)
• For general Dart/Flutter → Use general-purpose

Unknown Frameworks

Problem: Encountering a framework not in the agent catalog (e.g., SvelteKit, Nuxt.js, Ruby on Rails)

Solution:

• Use general-purpose agent
• Document the framework for future reference
• Consider requesting a new specialized agent if frequently used

Testing and Build Tasks

Problem: Running tests or builds that span multiple frameworks

Solution:

• If tests are framework-specific (e.g., Laravel PHPUnit tests), use framework agent
• If running global build scripts, use general-purpose
• If parallelizing tests across subsystems, split by framework

---

Confidence Scoring

When matching agents, assign confidence scores:

• High (90-100%): Clear framework indicators, config files present, explicit user mention
• Medium (60-89%): File patterns match, but no config files or some ambiguity
• Low (30-59%): Weak signals, could be multiple frameworks
• Very Low (<30%): No clear indicators, default to general-purpose

Decision Rule:

• High/Medium confidence → Use specialized agent
• Low/Very Low → Use general-purpose OR ask user for clarification

---

Future Agent Types

Potential agents that may be added in the future:

• svelte-senior-engineer - For SvelteKit applications
• vue-senior-engineer - For Vue.js/Nuxt applications
• rails-senior-engineer - For Ruby on Rails applications
• spring-boot-senior-engineer - For Java Spring Boot APIs
• rust-senior-engineer - For Rust backends and CLI tools

When encountering these technologies currently, use general-purpose and note the limitation.

Agent Runtime Semantics

Use this reference when run-parallel-agents-feature-debug/SKILL.md needs the exact Claude Code runtime rules for spawning and coordinating agents in parallel.

Fresh Agent Context

Fresh agents launched with subagent_type do not inherit your task-specific reasoning. Their prompt must include:

• what is broken
• how it fails
• where to look
• scope boundaries
• expected output
• validation requirements

Relevant source anchors:

• claude-code-source/src/tools/AgentTool/prompt.ts
• claude-code-source/src/tools/AgentTool/AgentTool.tsx

Parallel Launch Rule

If the user asks for agents "in parallel", launch them in a single assistant message with multiple Agent(...) tool use blocks.

Why:

• this is the runtime behavior Claude's own Agent tool prompt requires
• splitting launches across multiple assistant messages turns the orchestration into serial work from the coordinator's perspective

Relevant source anchor:

• claude-code-source/src/tools/AgentTool/prompt.ts:258-271

Background Semantics

For independent debug lanes, use run_in_background: true.

Why:

• background agents notify the main thread on completion
• the coordinator should not sleep, poll, or proactively inspect progress

Relevant source anchors:

• claude-code-source/src/tools/AgentTool/prompt.ts:260-264
• claude-code-source/src/tools/AgentTool/AgentTool.tsx:420-422
• claude-code-source/src/tools/AgentTool/AgentTool.tsx:548-567

Worktree Isolation

For debug lanes that may modify code, prefer isolation: "worktree".

Why:

• worktree isolation gives the agent a temporary git worktree
• it reduces file clobbering across parallel writers
• explicit isolation on the Agent call overrides any default isolation on the target agent definition

Relevant source anchors:

• claude-code-source/src/tools/AgentTool/prompt.ts:271-273
• claude-code-source/src/tools/AgentTool/AgentTool.tsx:424-431
• claude-code-source/src/tools/AgentTool/AgentTool.tsx:582-590

Explicit Parameters Beat Defaults

Do not rely on agent-file defaults when the orchestration needs predictable semantics.

Important behavior:

• explicit isolation overrides the selected agent's isolation
• run_in_background: true combines with agent defaults and is the safest explicit signal for independent parallel work

Relevant source anchors:

• claude-code-source/src/tools/AgentTool/AgentTool.tsx:424-431
• claude-code-source/src/tools/AgentTool/AgentTool.tsx:548-567

Output Handling

The agent result is returned to the coordinator, not directly to the user.

That means:

• aggregate results yourself
• report concise summaries back to the user
• do not assume the user saw raw agent output

Relevant source anchor:

• claude-code-source/src/tools/AgentTool/prompt.ts:253-256

Debug Patterns Reference

This document provides comprehensive error pattern recognition, debugging strategies for each framework, and root cause analysis techniques for parallel debugging scenarios.

Error Pattern Recognition

Test Failure Patterns

Laravel PHPUnit Tests

Common Patterns:

Failed asserting that false is true
Class 'DatabaseSeeder' not found
SQLSTATE[HY000] [2002] Connection refused
This action is unauthorized
Column not found: 1054 Unknown column

Root Causes:

• Database seeding issues (missing factories, seeders)
• Database connection problems (wrong credentials, service not running)
• Authorization/policy failures
• Migration not run
• Eloquent relationship misconfiguration

Agent Match: laravel-senior-engineer

---

Next.js Jest/Vitest Tests

Common Patterns:

Cannot read properties of undefined (reading 'map')
Component did not render
Hydration failed because the initial UI does not match
Mock function not called
Snapshot test failed

Root Causes:

• Missing mock data or incorrect structure
• Component props not matching expectations
• Server/client hydration mismatch
• Async data not resolved before assertions
• Snapshot outdated after component changes

Agent Match: nextjs-senior-engineer

---

React Vite/Tailwind Tests

Common Patterns:

Cannot find module './Component' from 'src/App.tsx'
ReferenceError: document is not defined
TypeError: Cannot destructure property 'X' of undefined
Tailwind class not applied in test

Root Causes:

• Vite alias not configured in test runner (vitest vs jest)
• Missing jsdom or happy-dom test environment
• Props or context not provided in test wrapper
• Tailwind JIT not processing test files

Agent Match: react-vite-tailwind-engineer

---

Express/NestJS Tests

Common Patterns:

Cannot GET /api/endpoint
Unexpected token < in JSON at position 0
Guard returned false
Nest can't resolve dependencies
Timeout - Async callback was not invoked within 5000ms

Root Causes:

• Route not properly registered
• Response format mismatch (HTML instead of JSON)
• Guard/interceptor blocking request
• Dependency injection configuration missing (NestJS)
• Async operation not awaited or resolved

Agent Match: express-senior-engineer

---

Python/Django Tests

Common Patterns:

django.db.utils.OperationalError: no such table
AssertionError: 404 != 200
ImproperlyConfigured: settings.DATABASES is improperly configured
ModuleNotFoundError: No module named 'app'
PermissionDenied: You do not have permission

Root Causes:

• Test database not migrated
• URL routing misconfiguration
• Django settings not pointed to test config
• Python path / virtual environment issue
• Permission/authentication not set up in test

Agent Match: python-senior-engineer

---

FastAPI Tests

Common Patterns:

422 Unprocessable Entity
starlette.testclient.TestClient: connection refused
pydantic.error_wrappers.ValidationError
sqlalchemy.exc.IntegrityError: UNIQUE constraint failed
RuntimeError: Event loop is closed

Root Causes:

• Pydantic validation failure (wrong request body shape)
• Test server not started or wrong port
• Request/response schema mismatch
• Database constraint violation in test data
• Async event loop mismanagement in tests

Agent Match: fastapi-senior-engineer

---

Go Tests

Common Patterns:

--- FAIL: TestHandler (0.00s)
panic: runtime error: nil pointer dereference
cannot use x (variable of type X) as type Y
undefined: SomeFunction
race detected during execution of test

Root Causes:

• Assertion failure in test case
• Nil pointer not checked before dereference
• Type mismatch or interface not satisfied
• Missing import or unexported function
• Data race in concurrent code

Agent Match: go-senior-engineer or go-cli-senior-engineer

---

Swift/Xcode Tests

Common Patterns:

XCTAssertEqual failed: ("X") is not equal to ("Y")
Thread 1: Fatal error: Unexpectedly found nil
No such module 'PackageName'
Build input file cannot be found
The compiler is unable to type-check this expression

Root Causes:

• Assertion mismatch in XCTest
• Force unwrapping optional that is nil
• SPM dependency not resolved or target not linked
• File removed from disk but still referenced in project
• Complex generic/closure expression exceeding type checker limits

Agent Match: ios-macos-senior-engineer

---

Expo/React Native Tests

Common Patterns:

Invariant Violation: requireNativeComponent
Unable to resolve module './NativeModule'
No component found for view with name "RCTView"
Animated: `useNativeDriver` was not specified
TypeError: Cannot read property 'navigate' of undefined

Root Causes:

• Native module not linked or mocked in tests
• Missing native dependency or Expo module
• React Native bridge not initialized in test environment
• Animation configuration incomplete
• Navigation context not provided in test

Agent Match: expo-react-native-engineer

---

Runtime Error Patterns

Laravel Runtime Errors

Common Patterns:

Class 'App\Models\User' not found
Call to a member function on null
Too few arguments to function
SQLSTATE[42S02]: Base table or view not found
419 Page Expired (CSRF token mismatch)

Root Causes:

• Autoloader cache needs refresh (composer dump-autoload)
• Null check missing (relationship returns null)
• Method signature changed but call sites not updated
• Missing migration
• CSRF protection blocking request

Agent Match: laravel-senior-engineer

---

React/Next.js Runtime Errors

Common Patterns:

Hydration failed
Maximum update depth exceeded
Cannot update during an existing state transition
'X' is not defined
Objects are not valid as a React child

Root Causes:

• Server/client state mismatch
• Infinite re-render loop (setState in render)
• State update during render phase
• Missing import or typo
• Attempting to render object instead of primitive

Agent Match: nextjs-senior-engineer or react-vite-tailwind-engineer

---

Express/NestJS Runtime Errors

Common Patterns:

Cannot find module '@nestjs/...'
Circular dependency detected
Provider not found
Error: listen EADDRINUSE :::3000
UnhandledPromiseRejectionWarning

Root Causes:

• Missing package installation
• Circular module imports (A imports B, B imports A)
• Provider not added to module's providers array
• Port already in use
• Missing try/catch in async middleware

Agent Match: express-senior-engineer

---

FastAPI Runtime Errors

Common Patterns:

422 Unprocessable Entity
Internal Server Error (no detail)
sqlalchemy.exc.OperationalError: connection refused
RuntimeError: no running event loop
AttributeError: 'coroutine' object has no attribute 'X'

Root Causes:

• Request body doesn't match Pydantic model
• Unhandled exception in route handler
• Database connection pool exhausted or service down
• Mixing sync/async incorrectly
• Forgetting to await an async function

Agent Match: fastapi-senior-engineer

---

Go Runtime Errors

Common Patterns:

panic: runtime error: index out of range
fatal error: concurrent map writes
panic: interface conversion: interface {} is nil
goroutine leak detected
context deadline exceeded

Root Causes:

• Array/slice access without bounds check
• Concurrent map access without sync.Mutex or sync.Map
• Type assertion on nil interface
• Goroutine not properly cancelled or cleaned up
• External service timeout or slow response

Agent Match: go-senior-engineer

---

Swift/iOS Runtime Errors

Common Patterns:

Fatal error: Unexpectedly found nil while unwrapping
Thread 1: signal SIGABRT
[LayoutConstraints] Unable to simultaneously satisfy constraints
Publishing changes from within view updates is not allowed
Fatal error: Index out of range

Root Causes:

• Force unwrapping nil optional
• Unhandled exception or failed assertion
• Conflicting Auto Layout constraints
• SwiftUI state mutation during view body evaluation
• Array index out of bounds

Agent Match: ios-macos-senior-engineer

---

Docker/Container Runtime Errors

Common Patterns:

ERROR: Service 'app' failed to build
OCI runtime create failed: container_linux.go
port is already allocated
no space left on device
exec format error

Root Causes:

• Dockerfile syntax error or missing dependency in build
• Container runtime misconfiguration
• Host port conflict
• Docker disk space full (dangling images/volumes)
• Architecture mismatch (ARM image on x86 or vice versa)

Agent Match: devops-docker-senior-engineer

---

AWS/Infrastructure Errors

Common Patterns:

AccessDeniedException: User is not authorized
CREATE_FAILED (CloudFormation)
Error: Error creating IAM Role
CDK synth failed
Terraform plan failed: resource already exists

Root Causes:

• IAM permissions insufficient
• CloudFormation stack in failed state
• IAM role policy misconfiguration
• CDK code has type errors or invalid constructs
• Terraform state drift (resource exists outside Terraform)

Agent Match: devops-aws-senior-engineer

---

TypeScript Compilation Errors

Type Error Patterns

Laravel/PHP: (N/A - PHP is dynamically typed, use PHPStan/Psalm for static analysis)

Next.js / React Vite TypeScript:

Property 'X' does not exist on type 'Y'
Type 'null' is not assignable to type 'string'
Argument of type 'X' is not assignable to parameter of type 'Y'
Cannot find name 'React'

Root Causes:

• Missing type definition for prop
• Null/undefined not handled (use optional chaining or type guards)
• Type mismatch (wrong type passed to function/component)
• Missing import

Agent Match: nextjs-senior-engineer or react-vite-tailwind-engineer

---

Express/NestJS TypeScript:

Property 'user' does not exist on type 'Request'
No overload matches this call
'req' implicitly has type 'any'
Decorator '@Injectable()' is not valid here

Root Causes:

• Need to extend Express Request type
• Middleware type definition incorrect
• Missing @types/express or @types/node
• NestJS decorator on wrong target (class vs method)

Agent Match: express-senior-engineer

---

Performance Issues

Backend Performance (Laravel/Express/FastAPI/Go)

Indicators:

Response time > 2s
Database query count > 50 for single request
Memory usage growing unbounded
CPU spike on specific endpoint

Common Causes:

• N+1 query problem (missing eager loading in Laravel, missing joins in FastAPI/Go)
• Missing database indexes (full table scans)
• Memory leak (not releasing resources, goroutine leaks in Go)
• Synchronous I/O (should be async in FastAPI/Express)
• No caching (repeated expensive computations)

Debugging Approach:

1. Profile with Laravel Telescope, Node profiler, Python cProfile, or Go pprof 2. Check query count and execution time 3. Analyze database EXPLAIN for slow queries 4. Monitor memory usage over time 5. Identify blocking I/O operations

Agent Match: Framework-specific (laravel-senior-engineer, express-senior-engineer, fastapi-senior-engineer, go-senior-engineer)

---

Frontend Performance (Next.js/React)

Indicators:

First Contentful Paint > 2s
Cumulative Layout Shift > 0.1
Large bundle size (>500KB)
Slow component renders (>100ms)

Common Causes:

• Unnecessary re-renders (missing memoization)
• Large bundle (not code-splitting)
• Unoptimized images (not using Next.js Image)
• Blocking JavaScript (not deferring non-critical code)
• Heavy computations in render (should be useMemo)

Debugging Approach:

1. Use React DevTools Profiler 2. Check bundle analyzer for large dependencies 3. Lighthouse audit for Core Web Vitals 4. Identify components re-rendering unnecessarily 5. Check for blocking network requests

Agent Match: nextjs-senior-engineer or react-vite-tailwind-engineer

---

Mobile Performance (iOS/Expo)

Indicators:

Dropped frames / janky scrolling
High memory usage warnings
Slow app launch (> 3s)
Battery drain
Large app bundle size

Common Causes:

• Too many re-renders in React Native (missing memo)
• Large images not optimized or cached
• Heavy computation on main thread (should be on background thread)
• Memory leaks from uncleared subscriptions/listeners
• Too many native bridge calls in React Native

Debugging Approach:

1. Use Xcode Instruments (iOS) or React Native Perf Monitor 2. Profile memory usage and allocations 3. Check for unnecessary re-renders with React DevTools 4. Monitor JS thread frame rate 5. Audit native module usage

Agent Match: ios-macos-senior-engineer or expo-react-native-engineer

---

Framework-Specific Debugging Strategies

Laravel Debugging Strategy

Step 1: Gather Context

• Check error message and stack trace
• Review recent migrations and model changes
• Check .env configuration
• Review logs in storage/logs/

Step 2: Isolate the Issue

• Can you reproduce with php artisan tinker?
• Does it fail in specific environment only?
• Is it related to database, cache, or queue?

Step 3: Common Fixes

• Refresh autoloader: composer dump-autoload
• Clear caches: php artisan cache:clear, config:clear, view:clear
• Run migrations: php artisan migrate
• Re-seed database: php artisan db:seed

Step 4: Deep Dive

• Add dd() or Log::debug() at key points
• Use Laravel Telescope for request tracing
• Check database queries with Query Log
• Review authorization policies if 403 errors

---

Next.js Debugging Strategy

Step 1: Gather Context

• Check browser console for client-side errors
• Check terminal for server-side errors
• Review Network tab for failed requests
• Check React DevTools for component tree

Step 2: Isolate the Issue

• Is it client-side or server-side?
• Does it happen during build or runtime?
• Is it related to data fetching or rendering?

Step 3: Common Fixes

• Clear .next directory: rm -rf .next
• Restart dev server
• Check if data fetching is working (server actions, API routes)
• Verify environment variables are loaded
• Check for hydration mismatches (server vs client state)

Step 4: Deep Dive

• Add console.log in server/client components appropriately
• Use React DevTools Profiler for render issues
• Check Network tab for API failures
• Use Next.js built-in error overlay for diagnostics

---

React Vite/Tailwind Debugging Strategy

Step 1: Gather Context

• Check browser console for errors
• Check terminal for Vite build errors
• Review Tailwind class generation (is the class in the output CSS?)
• Check Vite dev server HMR status

Step 2: Isolate the Issue

• Is it a build error or runtime error?
• Is Tailwind generating the expected classes?
• Is Vite HMR working or stale?
• Is the issue in a specific component or global?

Step 3: Common Fixes

• Restart Vite dev server
• Clear Vite cache: rm -rf node_modules/.vite
• Check tailwind.config.ts content paths
• Verify PostCSS config is correct
• Check Vite aliases match tsconfig paths

Step 4: Deep Dive

• Use browser DevTools to inspect computed styles
• Check Vite bundle with vite-plugin-inspect
• Verify tree-shaking is working correctly
• Profile with React DevTools for render issues

---

Express/NestJS Debugging Strategy

Step 1: Gather Context

• Check terminal for console errors
• Review middleware stack order
• Check request/response logs
• Verify route registration

Step 2: Isolate the Issue

• Does middleware pass control correctly (next())?
• Is route handler registered before wildcard routes?
• Is request body parsed (body-parser)?
• Are CORS headers set correctly?
• For NestJS: Is provider in module's providers array?

Step 3: Common Fixes

• Add console.log in middleware chain
• Verify middleware order (auth before protected routes)
• Check body-parser is configured
• Verify error handling middleware is last
• For NestJS: Check module imports and circular dependencies

Step 4: Deep Dive

• Use morgan for HTTP request logging
• Add debug logs in each middleware
• Test with curl/Postman to isolate client issues
• Check async/await error handling (use try-catch or .catch())
• For NestJS: Use NestJS Logger and REPL mode

---

Python/Django Debugging Strategy

Step 1: Gather Context

• Check terminal for traceback
• Review Django settings and URL configuration
• Check database migrations status
• Review logs

Step 2: Isolate the Issue

• Can you reproduce in Django shell (python manage.py shell)?
• Is it a model/database issue or view/template issue?
• Does it fail in specific environment only?

Step 3: Common Fixes

• Run migrations: python manage.py migrate
• Check virtual environment is activated
• Verify INSTALLED_APPS includes your app
• Clear Django cache
• Check ALLOWED_HOSTS for deployment issues

Step 4: Deep Dive

• Add import pdb; pdb.set_trace() or use breakpoint()
• Use Django Debug Toolbar for request profiling
• Check ORM queries with django.db.connection.queries
• Review middleware order in settings

---

FastAPI Debugging Strategy

Step 1: Gather Context

• Check terminal for Uvicorn/Gunicorn errors
• Review Pydantic validation errors (422 responses)
• Check OpenAPI docs at /docs for schema correctness
• Review async function signatures

Step 2: Isolate the Issue

• Is it a validation error (Pydantic) or logic error?
• Is it sync vs async confusion?
• Is the database connection working?
• Is the dependency injection chain correct?

Step 3: Common Fixes

• Check Pydantic model matches request body
• Ensure async def for async operations, def for sync
• Verify database URL and connection pool settings
• Check Depends() chain resolves correctly

Step 4: Deep Dive

• Add print() or logging.debug() in route handlers
• Use /docs (Swagger UI) to test endpoints directly
• Profile with cProfile or py-spy
• Check for await on all async calls

---

Go Debugging Strategy

Step 1: Gather Context

• Check terminal for panic/error messages
• Review goroutine stack traces
• Check go vet and golangci-lint output
• Review recent changes to interfaces/structs

Step 2: Isolate the Issue

• Is it a compile error or runtime panic?
• Is it a concurrency issue (race condition)?
• Is it a nil pointer or type assertion issue?
• Is an external dependency failing?

Step 3: Common Fixes

• Run go vet ./... for static analysis
• Run go test -race ./... to detect races
• Check nil pointers before dereferencing
• Verify interface implementations are complete
• Check error returns (don't ignore err)

Step 4: Deep Dive

• Use dlv (Delve) debugger
• Add log.Printf at key points
• Use go tool pprof for CPU/memory profiling
• Run with -race flag to detect data races
• Check goroutine leaks with runtime.NumGoroutine()

---

iOS/macOS Debugging Strategy

Step 1: Gather Context

• Check Xcode console for errors and logs
• Review crash logs and stack traces
• Check build errors in Xcode Issue Navigator
• Review recent changes to SwiftUI views or models

Step 2: Isolate the Issue

• Is it a build error or runtime crash?
• Is it a SwiftUI layout issue or data issue?
• Is it related to a specific iOS version or device?
• Is it a threading issue (main thread violation)?

Step 3: Common Fixes

• Clean build folder: Product > Clean Build Folder (Cmd+Shift+K)
• Reset package caches: File > Packages > Reset Package Caches
• Check @MainActor annotations for UI updates
• Verify optional unwrapping (use guard let or if let)
• Check SPM dependency versions in Package.swift

Step 4: Deep Dive

• Use Xcode Instruments (Leaks, Time Profiler, Allocations)
• Add #if DEBUG logging
• Use Xcode breakpoints with conditions
• Check View hierarchy with Xcode Debug View Hierarchy
• Use os_log for structured logging

---

Expo/React Native Debugging Strategy

Step 1: Gather Context

• Check Metro bundler terminal for errors
• Check device/simulator logs
• Review Expo Go or development build console
• Check for native module compatibility

Step 2: Isolate the Issue

• Is it a JavaScript error or native crash?
• Does it happen on iOS only, Android only, or both?
• Is it related to navigation, state, or native modules?
• Does it work in Expo Go but fail in dev build?

Step 3: Common Fixes

• Clear Metro cache: npx expo start --clear
• Reinstall node_modules and pods: rm -rf node_modules && npm install && cd ios && pod install
• Check Expo SDK version compatibility
• Verify native module is in app.json plugins
• Check for missing Expo config plugins

Step 4: Deep Dive

• Use React Native Debugger or Flipper
• Add console.log with React Native LogBox
• Check bridge calls with React Native Perf Monitor
• Profile with Xcode Instruments (iOS) or Android Profiler
• Check for memory leaks with heap snapshots

---

Docker Debugging Strategy

Step 1: Gather Context

• Check docker logs <container> for errors
• Review Dockerfile for build issues
• Check docker-compose logs for multi-service issues
• Verify volume mounts and network configuration

Step 2: Isolate the Issue

• Is it a build error or runtime error?
• Is it a networking issue (containers can't communicate)?
• Is it a volume/permission issue?
• Is it an architecture mismatch (ARM vs x86)?

Step 3: Common Fixes

• Rebuild without cache: docker build --no-cache
• Check port mappings in docker-compose.yml
• Verify environment variables are passed correctly
• Check file permissions on mounted volumes
• Prune unused resources: docker system prune

Step 4: Deep Dive

• Shell into container: docker exec -it <container> sh
• Inspect network: docker network inspect <network>
• Check resource usage: docker stats
• Multi-stage build debugging: build specific stage
• Check image layers: docker history <image>

---

AWS/Infrastructure Debugging Strategy

Step 1: Gather Context

• Check CloudWatch logs for errors
• Review CDK/Terraform output for deployment failures
• Check IAM permissions and policies
• Review CloudFormation events for stack failures

Step 2: Isolate the Issue

• Is it a deployment error or runtime error?
• Is it an IAM/permissions issue?
• Is it a networking issue (VPC, security groups)?
• Is it a resource limit or quota issue?

Step 3: Common Fixes

• Check IAM policy allows required actions
• Verify security group inbound/outbound rules
• Check CloudFormation stack events for failure reason
• Verify CDK bootstrap is up to date: cdk bootstrap
• Check Terraform state: terraform state list

Step 4: Deep Dive

• Use AWS CloudTrail for API call auditing
• Check VPC flow logs for network issues
• Use AWS X-Ray for distributed tracing
• Review CloudWatch metrics for resource health
• Test IAM policies with IAM Policy Simulator

---

Root Cause Analysis Techniques

Single vs Multiple Root Causes

Indicators of Single Root Cause:

• All failures started at the same time
• All errors mention the same dependency/module
• All stack traces share common code path
• Recent single change (commit, deploy, dependency update)

Example:

Scenario: All tests failing after infrastructure change

Error patterns:
- Laravel tests: "Cannot connect to database"
- Next.js tests: "API fetch failed: connection refused"
- Go tests: "dial tcp: connection refused"

Analysis: Single root cause (database service not running)
Decision: DON'T parallelize. Fix database connection first.

---

Indicators of Multiple Independent Root Causes:

• Failures in unrelated subsystems
• Different error messages/patterns
• Different stack traces with no commonality
• Isolated to specific modules/features

Example:

Scenario: Multiple test failures across stack

Error patterns:
- Laravel tests: "Missing factory trait in User test"
- Next.js tests: "Mock data has wrong shape for Product"
- Go tests: "TestPaymentHandler: expected 200 got 500"
- FastAPI tests: "422 Unprocessable Entity on /api/orders"

Analysis: Four independent issues in different subsystems
Decision: CAN parallelize. Each has different root cause.

---

Dependency Analysis

Questions to Ask:

1. If I fix issue A, will issue B automatically resolve? 2. Does issue B require the fix from issue A to work? 3. Do A and B modify the same files/database/state?

Dependency Matrix:

---

Clustering Algorithm

Step 1: Extract Error Metadata For each error, extract:

• Framework/tech stack
• Subsystem/module
• Error type (test failure, runtime error, type error, performance)
• Affected files

Step 2: Group by Similarity Create clusters based on:

• Same tech stack AND same subsystem → Likely related, investigate together
• Different tech stack → Likely independent, can parallelize
• Same file/function → Likely related, investigate together
• Different modules with no overlap → Likely independent

Step 3: Validate Independence For each cluster pair, verify:

• [ ] No shared files being modified
• [ ] No data dependencies
• [ ] No sequential ordering required
• [ ] No common root cause

Step 4: Decision

• If 3+ independent clusters → Proceed with parallel debugging
• If < 3 clusters OR clusters are related → Sequential debugging

---

Common Pitfalls in Parallel Debugging

Pitfall 1: Missing Shared Root Cause

Scenario:

Error 1: Laravel API returns 500
Error 2: Next.js fetch fails
Error 3: Go service returns 503
Error 4: FastAPI returns 500

Assumption: Four independent issues (different services)

Reality: All four fail because shared Redis cache or database is down

Lesson: Always check shared dependencies (database, cache, external APIs) before parallelizing

---

Pitfall 2: Cascading Failures

Scenario:

Error 1: Database migration failed
Error 2: API tests fail (missing table)
Error 3: Frontend tests fail (API returns 500)

Assumption: Three separate issues

Reality: All stem from migration failure (Error 1)

Lesson: Fix foundational issues (DB, infrastructure) before debugging application logic

---

Pitfall 3: Overlapping File Changes

Scenario:

Bug 1: Cart total calculation wrong (CartService.php)
Bug 2: Discount logic broken (CartService.php)

Assumption: Two separate bugs

Reality: Both agents modify CartService.php → merge conflict

Lesson: Check file overlap before parallelizing. If same file, consider sequential or manual coordination

---

Pitfall 4: Ignoring Integration

Scenario:

Fix 1: Go API returns new response format
Fix 2: Next.js expects old API response format

Result: Both fixes work independently but break when integrated

Lesson: After parallel fixes, always run integration tests to verify fixes work together

---

Pitfall 5: Infrastructure Fixes Masking App Bugs

Scenario:

Fix 1: devops-docker-senior-engineer fixes container networking
Fix 2: express-senior-engineer fixes API logic

Result: After Docker fix, the Express bug manifests differently

Lesson: Re-validate application-level fixes after infrastructure changes

---

Validation Checklist Template

Use this checklist after parallel debugging to ensure quality:

Per-Fix Validation

For each fix:

• [ ] Original error no longer reproduces
• [ ] Unit tests pass
• [ ] No new errors introduced
• [ ] Code follows project patterns
• [ ] Performance not degraded

Integration Validation

For all fixes together:

• [ ] No file conflicts
• [ ] No contradictory changes
• [ ] Full test suite passes (not just fixed tests)
• [ ] Integration tests pass
• [ ] Manual smoke testing complete

Documentation

• [ ] Fix documented (what was wrong, why, how fixed)
• [ ] If pattern issue, document prevention strategy
• [ ] Update relevant documentation if needed

---

Advanced Debugging Patterns

Pattern 1: Bisecting Parallel Failures

When facing many failures (e.g., 20+ test failures):

1. Quick triage: Group into categories by agent type 2. Fix easy wins first: Obvious issues (missing imports, typos) 3. Identify patterns: Are 10 failures all in auth? Might be shared root cause 4. Parallelize remainder: After pattern analysis, parallelize truly independent issues

---

Pattern 2: Progressive Parallelization

Start sequential, then parallelize:

1. Fix first issue (understand the codebase) 2. Assess impact (did it fix multiple issues?) 3. Identify remaining independent issues 4. Parallelize remaining (now with context from first fix)

Useful when initial error state is unclear.

---

Pattern 3: Parallel Investigation, Sequential Fix

Use parallel agents for investigation, then apply fixes sequentially:

1. Launch parallel diagnostic agents (gather information only) 2. Aggregate findings (identify root causes) 3. Plan fix order (based on dependencies discovered) 4. Apply fixes sequentially or in parallel (as appropriate)

Useful for complex, interconnected issues where you need full picture first.

---

Pattern 4: Infrastructure-First Debugging

When errors span application and infrastructure:

1. Fix infrastructure first (devops-docker-senior-engineer, devops-aws-senior-engineer) 2. Re-run tests to see which app errors resolve 3. Then parallelize remaining app-level fixes across framework agents

Useful when Docker/AWS issues cause cascading failures in application code.

---

Framework-Specific Error Codes Quick Reference

Laravel HTTP Status Codes

• 419 → CSRF token mismatch
• 403 → Authorization failed (policy/gate)
• 500 → Server error (check logs)
• 404 → Route not found or model not found

Next.js Build Errors

• ENOENT → File not found
• Module not found → Import path wrong or missing dependency
• Hydration error → Server/client mismatch
• Error: Minified React error → Check React error decoder

Express/NestJS Errors

• EADDRINUSE → Port already in use
• Cannot GET /path → Route not registered
• UnauthorizedException → Auth guard blocked (NestJS)
• BadRequestException → Validation failed (NestJS)

FastAPI Status Codes

• 422 → Pydantic validation error
• 401 → JWT token missing or invalid
• 500 → Unhandled exception in route handler

Go Errors

• panic: runtime error → Nil pointer, index out of range, etc.
• fatal error: concurrent map writes → Missing mutex
• context deadline exceeded → Timeout on external call

Swift/Xcode Errors

• SIGABRT → Assertion failure or unhandled exception
• EXC_BAD_ACCESS → Memory access violation
• Build failed → Check Issue Navigator for details

Docker Errors

• ENOSPC → No space left on device
• exec format error → Architecture mismatch
• OCI runtime error → Container configuration issue

AWS/CloudFormation Errors

• CREATE_FAILED → Resource creation failed (check events)
• AccessDeniedException → IAM permissions missing
• LimitExceededException → Service quota reached

---

Recommended Debugging Tools by Framework

Laravel

• Laravel Telescope: Request tracing, query monitoring
• Debugbar: In-browser debugging info
• Tinker: REPL for testing code
• dd() / dump(): Quick variable inspection
• Log::debug(): Logging
• EXPLAIN: Database query analysis

Next.js

• React DevTools: Component tree inspection
• Next.js Error Overlay: Build-time errors
• Network Tab: API request debugging
• Lighthouse: Performance audit
• console.log: Still effective for server components (check terminal)

React Vite/Tailwind

• React DevTools: Component tree and profiler
• Vite Inspector: vite-plugin-inspect for build analysis
• Browser DevTools: Computed styles for Tailwind debugging
• Tailwind CSS IntelliSense: IDE extension for class validation
• Bundle Analyzer: rollup-plugin-visualizer for bundle size

Express/NestJS

• Morgan: HTTP request logger
• Debug module: Namespaced debugging
• Postman/curl: API testing
• Node inspector: Debugger
• NestJS Logger: Built-in NestJS logging
• Swagger: API endpoint testing (NestJS)

Python/Django

• Django Debug Toolbar: Request profiling
• pdb / breakpoint(): Interactive debugger
• Django shell: REPL for testing
• pytest -v: Verbose test output
• logging module: Structured logging

FastAPI

• Swagger UI (/docs): Interactive API testing
• py-spy: Sampling profiler
• logging module: Debug logging
• pdb / breakpoint(): Interactive debugger
• httpx: Async HTTP testing

Go

• Delve (dlv): Go debugger
• go tool pprof: CPU and memory profiling
• go test -race: Race condition detection
• golangci-lint: Comprehensive linting
• log.Printf: Simple but effective

iOS/macOS

• Xcode Instruments: Leaks, Time Profiler, Allocations
• Xcode Debug View Hierarchy: UI layout debugging
• os_log: Structured logging
• LLDB: Command-line debugger in Xcode
• SwiftUI Preview: Rapid UI iteration

Expo/React Native

• React Native Debugger: All-in-one debugging
• Flipper: React Native plugin ecosystem
• Expo Dev Tools: Expo-specific debugging
• Metro Bundler logs: Build and module resolution issues
• Xcode Instruments / Android Profiler: Native performance

Docker

• docker logs: Container log inspection
• docker exec -it: Shell into running container
• docker stats: Resource usage monitoring
• docker inspect: Container/network/volume details
• dive: Docker image layer analysis

AWS

• CloudWatch Logs: Centralized logging
• CloudTrail: API call auditing
• X-Ray: Distributed tracing
• IAM Policy Simulator: Permission testing
• CDK diff / Terraform plan: Preview infrastructure changes

---

Summary

This reference guide provides:

1. Error pattern recognition for quick agent matching across all 14 agent types 2. Framework-specific debugging strategies for effective troubleshooting 3. Root cause analysis techniques to determine parallelization viability 4. Common pitfalls to avoid when debugging in parallel 5. Validation checklists to ensure quality fixes 6. Advanced patterns for complex scenarios 7. Debugging tool recommendations for every supported framework

Use this guide in conjunction with the main SKILL.md workflow to orchestrate effective parallel debugging sessions.