conflict-resolution

Use this when an agent's output contradicts another agent's, when a decision falls in a domain another agent owns, when same-wave designs are incompatible, or when a phase lead receives an ESCALATION

SKILL.md

GitHub

conflict-resolution


Conflict Resolution

Provides the step-by-step conflict detection, escalation, and resolution protocol for the multi-agent architecture design fleet, ensuring single-owner authority and traceable resolution across both Architecture and Detailed Design phases.

When to Activate

  • When an agent discovers its output contradicts another agent's output
  • When an agent needs to make a decision in a domain it does not own
  • When two Wave 2 agents produce incompatible designs
  • When an agent reads another agent's context summary and finds conflicting assumptions
  • When architecture-lead or detailed-design-lead receives an ESCALATION message
  • Used by: all Wave 2 agents (api-designer, infrastructure-architect, database-architect, pattern-advisor, interface-designer, algorithm-designer, concurrency-designer, component-designer, data-model-designer, sdk-designer), architecture-lead, detailed-design-lead

Ownership Matrix Lookup Process

Before making any decision, check whether the domain is owned by this agent or another.

Step 1: Identify the Domain

Determine which domain the decision falls into. Common domains:

Domain Category Examples
Service boundaries Which microservice owns a capability, service splitting/merging
Data schemas Table structure, column types, relationships, constraints
API contracts Request/response shapes, endpoint naming, HTTP methods
Event subjects NATS subject naming, message payload structure
Infrastructure Stream/consumer config, deployment topology, resource sizing
Auth flow Token propagation, permission model, session handling
Design patterns Which pattern applies, pattern parameters

Step 2: Look Up the Owner

Architecture Phase Ownership Matrix (CLAUDE.md rule #7)

Domain Owner Consulted
Service boundaries & decomposition system-decomposer ALL
Tenant isolation strategy system-decomposer database-architect, infrastructure-architect
Entity/table schemas database-architect api-designer
Request/response DTOs api-designer database-architect
NATS subject naming & hierarchy api-designer infrastructure-architect
NATS stream/consumer config infrastructure-architect api-designer
Auth token propagation api-designer simulated-security-architect
Design pattern selection pattern-advisor ALL Wave 2 agents
Final architecture synthesis architecture-lead ALL

Detailed Design Phase Ownership Matrix (CLAUDE.md Detailed Design section)

Domain Owner Consulted
Go package structure & components component-designer interface-designer, sdk-designer
Detailed SQL schemas & migrations data-model-designer component-designer
Internal SDK libraries sdk-designer component-designer, concurrency-designer
DTOs, validation, error types interface-designer component-designer, data-model-designer
Business logic algorithms algorithm-designer component-designer
Concurrency patterns concurrency-designer component-designer, sdk-designer
Coding guidelines coding-guidelines-generator ALL design agents
Final detailed design synthesis detailed-design-lead ALL

Step 3: Determine Action

Situation Action
Agent owns the domain Make the decision, log it, proceed
Agent is consulted on the domain Document concerns, defer to owner
Agent is neither owner nor consulted Do not decide; escalate if needed
Owner's output not yet available Proceed with assumption (see below)

Proceeding with Assumptions

Per CLAUDE.md rule #7, when an agent needs to make a decision in a domain it does NOT own and the owner's output is not yet available:

Step 1: Make a Best-Judgment Decision

The agent proceeds with its best judgment to avoid blocking.

Step 2: Mark the Assumption in Output Files

<!-- ASSUMPTION -- pending database-architect confirmation -->
Entity table primary key is UUID v7 with composite index on (tenant_id, entity_id).
This assumption affects the DTO field types in CreateEntityRequest.

Step 3: Mark the Assumption in Context Summary

## Dependencies & Assumptions
<!-- ASSUMPTION -- pending database-architect confirmation -->
- Assumed UUID v7 PKs for all tenant-scoped entities
- Assumed composite index (tenant_id, entity_id) on all tables

Step 4: Flag in Decision Log

Log the assumption as a decision with "confidence": "low" and appropriate tags:

{
  "run_id": "f47ac10b-...",
  "type": "decision",
  "timestamp": "2026-03-09T14:15:00Z",
  "agent": "api-designer",
  "phase": "api-design",
  "decision": "DTO ID fields use UUID v7 type, matching assumed database PK strategy",
  "rationale": "database-architect output not yet available; UUID v7 is the most likely choice given project constraints",
  "alternatives_considered": ["UUID v4", "ULID", "BIGSERIAL"],
  "trade_offs": "May require DTO changes if database-architect chooses a different PK strategy",
  "confidence": "low",
  "status": "success",
  "context": "Designing CreateEntityRequest DTO; database-architect has not published schemas yet",
  "impacts": ["database-architect"],
  "reversibility": "easy",
  "tags": ["assumption", "pending-confirmation"]
}

When to Escalate vs Proceed with Assumptions

Scenario Action
Owner's output not yet available, decision is reversible Proceed with assumption
Owner's output not yet available, decision is irreversible Escalate to lead
Agent reads owner's output and disagrees Escalate to lead
Two agents produce directly contradictory outputs Escalate to lead
Minor stylistic difference between agents Proceed, do not escalate
Agent discovers a gap in its own owned domain Decide and log, no escalation needed

Reversibility Guide

Reversibility Examples Action
Easy Naming conventions, DTO field names, log format Proceed with assumption
Moderate Index strategy, NATS subject hierarchy, middleware ordering Proceed with assumption, flag for review
Hard Primary key type, tenant isolation model, encryption strategy Escalate before proceeding
Irreversible Data model fundamentals, auth protocol, compliance approach Always escalate

ESCALATION Message Format

When escalation is needed, send a message to the lead using this exact format:

ESCALATION: CONFLICT between <agent-A> and <agent-B> on <domain>.
<agent-A> position: <brief description>.
<agent-B> position: <brief description>.
Ownership: <domain> is owned by <owner-agent> per CLAUDE.md rule #7.
Recommended resolution: <agent's recommendation>.

Example

ESCALATION: CONFLICT between api-designer and database-architect on entity field naming.
api-designer position: Use camelCase in JSON DTOs with snake_case mapping annotations.
database-architect position: Use snake_case everywhere for consistency with SQL columns.
Ownership: Request/response DTOs owned by api-designer; Entity/table schemas owned by database-architect.
Recommended resolution: camelCase in DTOs, snake_case in DB, explicit mapping layer in component-designer.

How the Lead Resolves Conflicts

When architecture-lead or detailed-design-lead receives an ESCALATION message, the resolution follows CLAUDE.md rule #8:

Step 1: Read Both Positions

The lead reads the context summaries and relevant output files from both agents.

Step 2: Decide Based on Ownership Matrix

The domain owner's position is preferred unless:

  • It violates a non-negotiable constraint (see docs/architecture/constraints.md)
  • It creates a cross-cutting inconsistency that affects 3+ other agents
  • The consulted agent raises a valid security, compliance, or data integrity concern

Step 3: Log the Resolution

The lead logs a decision entry with "tags": ["conflict-resolution"]:

{
  "run_id": "f47ac10b-...",
  "type": "decision",
  "timestamp": "2026-03-09T16:00:00Z",
  "agent": "architecture-lead",
  "phase": "review",
  "decision": "Field naming: camelCase in API DTOs (api-designer owns), snake_case in DB columns (database-architect owns), explicit mapping in Go struct tags",
  "rationale": "Each agent's convention is correct within its owned domain; mapping layer resolves the mismatch without forcing either to change",
  "alternatives_considered": ["snake_case everywhere", "camelCase everywhere", "auto-generated mapping"],
  "trade_offs": "Requires explicit json/db struct tags on every Go model; adds maintenance burden",
  "confidence": "high",
  "status": "success",
  "context": "ESCALATION: CONFLICT between api-designer and database-architect on entity field naming",
  "impacts": ["api-designer", "database-architect", "component-designer", "interface-designer"],
  "reversibility": "moderate",
  "tags": ["conflict-resolution", "field-naming"]
}

Step 4: Notify the Non-Owning Agent

The lead sends a message to the agent whose position was overridden (or both agents if a compromise was reached):

RESOLUTION: Field naming conflict resolved. camelCase in DTOs, snake_case in DB. See decision log. Please update your output to align.

Step 5: Update ARCHITECTURE.md or DETAILED-DESIGN.md

If the lead cannot resolve the conflict, it is recorded as an open question:

## Open Questions
- **Field naming consistency**: api-designer and database-architect have different conventions.
  Resolution deferred to implementation phase. Current approach: mapping layer in struct tags.

Conflict-Resolution Decision Log Tags

All conflict-resolution entries MUST include these tags:

Tag Required Purpose
conflict-resolution Always Identifies the entry as a conflict resolution
Domain tag (e.g., tenant-isolation) Always The domain where the conflict occurred
assumption If applicable If resolution involved confirming/rejecting an assumption
cross-cutting If applicable If resolution affects 3+ agents

Examples

GOOD -- Assumption Marking in Go Code

// Package orderservice contains the order management service.
//
// ASSUMPTION: pending database-architect confirmation
// Entity PK is UUID v7 with composite (tenant_id, entity_id) index.
package orderservice

// Order represents a domain entity.
// [traces-to: order-service]
type Order struct {
    ID       uuid.UUID `json:"id" db:"id"`
    TenantID uuid.UUID `json:"tenantId" db:"tenant_id"` // ASSUMPTION: UUID v7
    Subject  string    `json:"subject" db:"subject"`
    Status   string    `json:"status" db:"status"`
}

BAD -- Silently Overriding Another Agent's Domain

// Package orderservice uses BIGSERIAL primary keys for performance.
package orderservice

type Order struct {
    ID       int64     `json:"id" db:"id"`           // Decided BIGSERIAL
    TenantID uuid.UUID `json:"tenantId" db:"tenant_id"`
}

Why it is wrong: Primary key type is owned by database-architect. The api-designer or component-designer cannot unilaterally decide to use BIGSERIAL without an assumption marker or escalation. This creates a silent conflict that will surface late.

Common Mistakes

  1. Deciding in a domain without checking ownership -- Before making any cross-domain decision, always consult the ownership matrix. Even if the decision seems obvious, the owner may have context that changes the answer.

  2. Escalating minor stylistic differences -- Not every disagreement is a conflict. If two agents name things slightly differently but the semantics match, the non-owner should align with the owner's convention without escalating. Reserve escalation for genuine incompatibilities.

  3. Omitting the conflict-resolution tag in the decision log -- When the lead resolves a conflict, the decision entry MUST include the "conflict-resolution" tag. Without it, the conflict audit trail is broken and future agents cannot find prior resolutions.

  4. Proceeding with assumptions on irreversible decisions -- If a decision is hard or irreversible (e.g., primary key strategy, encryption model), always escalate instead of assuming. Reversibility determines whether to assume or escalate.

  5. Not updating output after receiving a RESOLUTION message -- When the lead resolves a conflict and the non-owning agent receives a RESOLUTION message, that agent MUST update its output files to align. Ignoring resolution messages creates persistent inconsistencies.

  6. Escalating without including both positions -- The ESCALATION message format requires both agents' positions, the ownership reference, and a recommended resolution. Incomplete escalation messages slow down resolution because the lead has to investigate independently.