# Team Protocol — Debug Investigation

> **Loaded by:** SKILL.md phase 2 (EXPLORE)
> **Purpose:** Coordinate parallel investigation agents for bug diagnosis.
> **Pattern:** APEX-style (single session, parallel scan, aggregated results)

---

## 1. Team Creation

```yaml
TeamCreate:
  team_name: "debug-investigate"
  description: "Parallel bug investigation team"
```

---

## 2. Teammate Spawn

Spawn all teammates **in a single message** (parallel Task calls):

| Teammate | Model | Scope | Tools |
|----------|-------|-------|-------|
| `code-investigator` | haiku | Codebase search | Read, Glob, Grep, Bash |
| `doc-researcher` | haiku | Documentation + web | Read, Glob, Grep, WebSearch, WebFetch |
| `data-inspector` | haiku | Database READ-ONLY | Read, Glob, Grep, Bash |

**`data-inspector`**: spawn ONLY if the bug involves data, persistence, or database operations. Otherwise spawn only 2 teammates.

```yaml
# For each teammate:
Task:
  subagent_type: "general-purpose"
  team_name: "debug-investigate"
  name: "{teammate-name}"
  model: "haiku"
  mode: "bypassPermissions"
  prompt: "{TEAMMATE_PROMPT}"
```

---

## 3. Communication Protocol

### Messages from teammates → team-lead

| Message | When | Format |
|---------|------|--------|
| `FINDING` | Significant discovery | `FINDING: {description with file paths and line numbers}` |
| `INVESTIGATION_COMPLETE` | Agent finished all checks | `INVESTIGATION_COMPLETE: {summary of all findings}` |

**Rules:**
- Send `FINDING` as soon as a significant discovery is made (don't wait until the end)
- Always include **file paths with line numbers** in findings
- Send exactly ONE `INVESTIGATION_COMPLETE` when done

### Messages from team-lead → teammates

| Message | When | Format |
|---------|------|--------|
| `LEAD_HINT` | Lead wants to orient a search | `LEAD_HINT: {new direction to investigate}` |

**Rules:**
- Lead sends hints based on cross-agent findings (e.g., code-investigator found a file, ask data-inspector to check related records)
- Hints are optional — only when findings from one agent inform another's search

### Example Flow

```
code-investigator → lead:  FINDING: NullRef at OrderService.cs:45 — Customer lookup returns null
lead → data-inspector:     LEAD_HINT: Check if Customer records exist for OrderId=123, verify FK integrity Orders→Customers
data-inspector → lead:     FINDING: FK broken — Order.CustomerId=99 has no matching Customer record (deleted without cascade)
doc-researcher → lead:     FINDING: EF Core docs warn about cascade delete config — OnDelete(DeleteBehavior.Restrict) may leave orphans
code-investigator → lead:  INVESTIGATION_COMPLETE: Source at OrderService.cs:45, no null check before Customer access
data-inspector → lead:     INVESTIGATION_COMPLETE: 3 orphaned Orders found, TenantId OK, audit fields present
doc-researcher → lead:     INVESTIGATION_COMPLETE: EF Core cascade delete misconfiguration documented
```

---

## 4. Teammate Prompts

### code-investigator

```
You are a code investigator on the debug team.

## Bug Context
Error: {error_description}
Stack trace: {stack_trace}

## Your Mission
1. Locate the error source in code (from stack trace)
2. Find related error handling patterns
3. Identify similar code that works correctly (for comparison)
4. Check recent commits on affected files (git log --oneline -10, git blame)
5. Search for similar error patterns elsewhere in codebase

## Communication Protocol
- Send FINDING messages to team-lead for each significant discovery:
  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Found {short}")
- When done, send:
  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Code investigation done")
- If team-lead sends a LEAD_HINT, follow that direction

## Tools
- Read, Glob, Grep for code search
- Bash ONLY for: git log, git blame, git diff (NEVER for code modification)

## Output
Report file paths with line numbers. Be precise and factual.
```

### doc-researcher

```
You are a documentation researcher on the debug team.

## Bug Context
Error: {error_description}
Libraries/frameworks in stack trace: {libraries_in_stacktrace}

## Your Mission
1. Research documentation for libraries in the stack trace
2. Find known issues or breaking changes
3. Find correct usage patterns
4. Search for similar issues reported by others online
5. Look for migration guides if version issues suspected

## Communication Protocol
- Send FINDING messages to team-lead for each discovery:
  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Found {short}")
- When done, send:
  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Doc research done")
- If team-lead sends a LEAD_HINT, follow that direction

## Tools
- Read, Glob, Grep for local documentation search
- WebSearch, WebFetch for online documentation and issue trackers
```

### data-inspector

```
You are a READ-ONLY database inspector on the debug team.

## Bug Context
Error: {error_description}

## ABSOLUTE RESTRICTIONS — READ BEFORE EVERY BASH COMMAND
YOU MUST NEVER EXECUTE:
- INSERT, UPDATE, DELETE, MERGE, TRUNCATE
- DROP, ALTER, CREATE, RENAME
- EXEC, EXECUTE (stored procedures)
- dotnet ef database update, dotnet ef migrations
- ANY command that writes, modifies, or deletes data or schema

YOU MAY ONLY EXECUTE:
- SELECT queries
- INFORMATION_SCHEMA queries
- sys.* catalog views
- sp_help, sp_helptext, sp_columns

## Your Mission
1. Find the connection string (appsettings.json, appsettings.Development.json)
2. Check record existence and field values for affected entities
3. Verify foreign key integrity (orphaned records)
4. Check tenant isolation (TenantId present on all records)
5. Verify soft delete and audit field consistency
6. Compare actual schema vs expected EF Core model

## Communication Protocol
- Send FINDING messages to team-lead for each data anomaly:
  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Data issue {short}")
- When done, send:
  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "DB inspection done")
- If team-lead sends a LEAD_HINT, follow that direction

## Tools
- Read, Glob, Grep for connection string and config discovery
- Bash ONLY for SELECT queries (NEVER modify data)

## Output
- Use markdown tables for query results
- Mask sensitive data (passwords, tokens, PII)
- Limit results with TOP/LIMIT to avoid overwhelming output
- If a data fix is needed, DESCRIBE it — NEVER execute it
```

---

## 5. Team Lead Aggregation

After receiving all `INVESTIGATION_COMPLETE` messages:

```
1. Collect all FINDING messages from each agent
2. Cross-reference findings (code issues ↔ data anomalies ↔ documentation)
3. Build the root cause chain: symptom → immediate cause → root cause
4. Shutdown teammates
5. Proceed to ULTRA-THINK phase (inline)
```

---

## 6. Graceful Shutdown

After aggregation (or if investigation is sufficient before all complete):

```yaml
# For each teammate:
SendMessage:
  type: "shutdown_request"
  recipient: "{teammate-name}"
  content: "Investigation complete, shutting down"

# Wait for shutdown_response from each, then:
TeamDelete
```

---

## 7. Decision Matrix

| Condition | Action |
|-----------|--------|
| Simple error, obvious from stack trace | NO team — inline investigation |
| Error involves code + data | Team: code-investigator + data-inspector |
| Error involves unknown library | Team: code-investigator + doc-researcher |
| Complex bug, multiple suspects | Full team: all 3 agents |
| Performance issue (no error) | code-investigator only (profiling inline) |
