agent-conflict-resolution

When to Activate

Use this skill when:

• Two or more agents give contradictory recommendations in the same session
• The orchestrator agent's synthesis phase encounters conflicting outputs
• A lower-priority agent's suggestion contradicts a higher-priority agent's finding
• You need to decide which agent's recommendation to apply when they disagree
• Sequential agent invocations appear to undo each other's changes

Do not use this skill for single-agent sessions with no conflict — standard agent instructions apply.

Quick Resolution Checklist

When two agents disagree, work through this in order — stop at the first rule that applies:

1. Is one recommendation about SECURITY (secrets, injection, auth, validation)?
   → Security (P1) wins unconditionally. No exceptions. Document it.

2. Is one recommendation about ARCHITECTURE (extract, separate concerns, design)?
   → Is this greenfield or a production incident?
     - Greenfield: Architect wins.
     - Production incident: Pragmatic wins — extract later, add ADR.

3. Is this about writing tests vs. fixing urgently?
   → Is production down or data loss occurring?
     - Yes: Fix first, tests follow.
     - No: TDD wins (tests first).

4. Is one recommendation about PERFORMANCE vs. CORRECTNESS?
   → Is there profiling evidence (flamegraph, benchmark)?
     - Yes: Performance wins — document TTL/eviction strategy.
     - No: Correctness wins. Theoretical concern is insufficient.

5. Is this STYLE vs. CONSISTENCY (rename, reformat, reorganize)?
   → Existing code: Consistency wins.
   → Net-new code: Clarity wins.

6. None of the above?
   → Escalate to user: show both recommendations, explain the trade-off.

Escalation Protocol

Escalate to the user when:

• Conflict doesn't fit any of the 5 classes above
• Both agents are the same priority level (P3 vs P3) with no tiebreaker
• A lower-priority agent raises a concern that could invalidate the higher-priority recommendation
• The conflict involves a business or product decision (not a technical one)

When escalating:

1. Show both recommendations clearly
2. State the conflict class (or "unclassified")
3. State what information would resolve the conflict (e.g., "does your team prioritize deployment speed or consistency here?")
4. Do NOT silently pick one — ask explicitly

Priority Hierarchy (Quick Reference)

P1 SECURITY (never override)
  └─ security-reviewer, devsecops-reviewer, supply-chain-auditor

P2 ARCHITECTURE (requires justification to override)
  └─ architect, data-architect, contract-reviewer

P3 CODE QUALITY (balanced, prefer more specific agent)
  └─ code-reviewer, typescript-reviewer, go-reviewer, python-reviewer, …

P4 ADVISORY (easily overridden by P1–P3)
  └─ code-simplifier, refactor-cleaner, performance-analyst

P5 CONTEXTUAL (task-phase dependent — see conflict class rules)
  └─ tdd-guide, build-error-resolver, e2e-runner

Full hierarchy with override rules: docs/agent-priority-hierarchy.md

Five Conflict Classes — Decision Trees

Class 1: security-vs-simplicity

                    [Conflict detected]
                           │
            ┌──────────────┴──────────────┐
            │                             │
   security-reviewer     code-simplifier / refactor-cleaner
   recommends keeping    recommends removing
            │
            └──────────► KEEP (P1 wins unconditionally)
                         No exception.

Real-world example:

security-reviewer: "Add input sanitization before passing to SQL query"
code-reviewer:     "This is handled by the ORM — the check is redundant"

Resolution: Keep the explicit sanitization. Defense in depth is correct even
when the ORM provides partial protection. Document why it's intentional.

---

Class 2: architecture-vs-pragmatism

                    [Conflict detected]
                           │
              ┌────────────┴────────────┐
              │                         │
      architect says EXTRACT        code agent says KEEP INLINE
              │
         Is this greenfield?
              │
       ┌──────┴──────┐
       YES            NO
       │               │
   Architect wins   Is it a production incident?
                        │
                  ┌─────┴─────┐
                  YES          NO
                  │             │
              Pragmatic      Architect wins
              (extract later)  (document override)

Real-world example:

architect:          "Extract UserNotificationService into its own bounded context"
typescript-reviewer: "This is 40 lines — extracting adds unnecessary indirection"

Context: 2-year-old legacy codebase, urgent bugfix needed
Resolution: Pragmatic wins. Add ADR noting the extraction as tech debt.

---

Class 3: methodology-vs-urgency

                    [Conflict detected]
                           │
            ┌──────────────┴──────────────┐
            │                             │
       tdd-guide says WRITE TEST FIRST    build-error-resolver says FIX NOW
            │
     Is production down or data loss?
            │
       ┌────┴────┐
       YES        NO
       │           │
   Fix first    tdd-guide wins
   Add tests    (tests first)
   after

Real-world example:

tdd-guide:           "Write failing test for the edge case first"
build-error-resolver: "The deploy pipeline is blocked — fix the null check now"

Situation: CI is broken, blocking the team
Resolution: Fix the null check immediately. Schedule test as follow-up commit.

---

Class 4: performance-vs-correctness

                    [Conflict detected]
                           │
         ┌─────────────────┴─────────────────┐
         │                                     │
  performance-analyst says CACHE         code-reviewer says ALWAYS RECOMPUTE
         │
  Is there profiling evidence?
         │
    ┌────┴────┐
    YES        NO
    │           │
  Apply cache  Correctness wins
  (document    (theoretical perf concern
   TTL/eviction)  not sufficient)

Real-world example:

performance-analyst: "Cache user permissions in Redis with 60s TTL"
security-reviewer:   "Stale permission cache is a security risk for deprovisioned users"

Here security-vs-performance overlaps with security-vs-simplicity:
Resolution: Security (P1) wins. Shorter TTL (5s) is acceptable compromise.
Document in ADR.

---

Class 5: style-vs-consistency

                    [Conflict detected]
                           │
            ┌──────────────┴──────────────┐
            │                             │
  Agent A says RENAME (clarity)      Agent B says KEEP (consistency)
            │
    Is this existing code?
            │
       ┌────┴────┐
       YES        NO (net-new code)
       │           │
   Consistency   Style / clarity wins
   wins           (use the better name)

---

Structured Conflict Signal

When emitting a recommendation that may conflict with another agent, append:

## Conflicts With

If `[agent-name]` recommended [opposite action]:
- Conflict class: `[class-name]`
- Resolution rule: [which agent wins and why]
- Action: DEFER | PROCEED | ESCALATE TO USER

Copy-Paste Template

Copy this block verbatim into your agent output whenever a conflict exists:

---
## ⚠ Conflict Signal

**This recommendation may conflict with another agent.**

| Field | Value |
|-------|-------|
| Conflicting agent | `<agent-name>` (e.g. `security-reviewer`) |
| Their recommendation | <one-line summary of opposing recommendation> |
| Conflict class | `<class>` (security-vs-simplicity / architecture-vs-pragmatism / methodology-vs-urgency / performance-vs-correctness / style-vs-consistency) |
| Winner per hierarchy | <agent that wins> — <one-sentence rationale> |
| Suggested action | DEFER / PROCEED / ESCALATE TO USER |

> If you are the orchestrator: apply the winner's recommendation and record this conflict
> in the `### Conflicts Resolved` table of your synthesis output.
---

Example:

## Recommendation

Remove the null guard at `src/api/users.ts:88`.
TypeScript strict mode guarantees `user` is non-null at this point.

## Conflicts With

If `security-reviewer` recommended keeping this guard:
- Conflict class: `security-vs-simplicity`
- Resolution rule: P1 security wins unconditionally
- Action: DEFER — do not apply this removal if security-reviewer is active

Orchestrator Synthesis Protocol

When synthesizing results from multiple agents in the ### Conflicts section:

1. Identify conflicts — compare recommendations across all agent outputs for same code locations
2. Classify — assign each conflict to one of the 5 classes
3. Apply resolution rule — state which agent wins and why
4. Document overrides — if lower-priority agent wins, note the justification
5. Never silently resolve — every conflict must appear in the ### Conflicts Resolved section

Output format:

### Conflicts Resolved

| Conflict | Agents | Class | Winner | Rationale |
|----------|--------|-------|--------|-----------|
| Remove null check at users.ts:88 | code-simplifier vs security-reviewer | security-vs-simplicity | security-reviewer | P1 wins unconditionally |
| Extract NotificationService | architect vs typescript-reviewer | architecture-vs-pragmatism | typescript-reviewer | Legacy codebase, pragmatic override |

Anti-Patterns

Do NOT:

❌ Silently apply a lower-priority recommendation without noting the conflict
❌ Auto-revert another agent's changes without human confirmation
❌ Block the user — conflicts are guidance, not hard stops
❌ Accept "this might be slow" as evidence for performance-vs-correctness class
❌ Override security-reviewer even when the check appears redundant

Do:

✓ Surface every conflict explicitly in synthesis output
✓ Apply priority hierarchy deterministically
✓ Document context when using context-dependent rules (class 2, 3)
✓ Require profiling evidence before accepting performance override
✓ Treat P1 security recommendations as unconditional

Code Examples

Conflict-aware orchestration output

## Results

### Agreements
- All agents: add retry logic with exponential backoff on network calls
- All agents: extract constants from magic numbers in processOrder()

### Conflicts Resolved

| Conflict | Agents | Class | Winner |
|----------|--------|-------|--------|
| Remove userId validation | code-simplifier vs security-reviewer | security-vs-simplicity | security-reviewer (P1) |
| Extract OrderProcessor service | architect vs code-reviewer | architecture-vs-pragmatism | code-reviewer — legacy codebase, pragmatic |

### Recommendations
1. Keep userId validation at orders.ts:42 (security requirement)
2. Keep OrderProcessor inline for now — create tech debt ticket for extraction
3. Add retry logic: agreed by all agents