docs/implementation/analyst_team_disagreement_layer.md

Analyst Team + Disagreement Resolution Layer

What Was Added

A lightweight, additive collaboration layer was implemented in the AAT path to make specialist reasoning explicit and auditable without rewriting the existing graph.

The layer introduces three structured artifacts:

• aat_analyst_opinions: one structured AnalystOpinion per active analyst
• aat_disagreements: detected disagreements across opinions
• aat_coordinator_synthesis: coordinator-level synthesis and selected action

Components

1. Structured opinion models:

• AnalystOpinion
• DisagreementItem
• CoordinatorSynthesis

2. Opinion producers:

• SchemaAgent, DomainAgent, DocumentAgent, and Verifier now provide opinion artifacts
• StrategicCoordinator now provides coordinator opinion + synthesis

3. New HypothesisAnalyst:

• Deterministic, low-overhead analyst
• Reviews question, semantic context, specialist analysis, plan, execution output, verifier output
• Emits strategy, failure-mode, alternative-interpretation opinion

4. Disagreement detection:

• detect_disagreements(opinions, context) detects confidence/action/schema/verifier/document/filter/aggregation/row-count conflicts

Safety and Compatibility

• Existing graph stages and control flow are unchanged
• Existing outputs remain intact (task_metrics.csv, trajectory.csv, tool_calls.csv, comprehensive_evaluation.csv, validation_report.md)
• Missing data defaults to empty artifacts ([] / {}) instead of crashing
• High-severity disagreement policy prevents blind APPROVE_FINAL unless strong evidence exists

Evaluation Additions

eval-v2 now reports Analyst Team metrics:

• mean agreement score
• tasks with high disagreement
• disagreement type distribution
• coordinator override count
• verifier disagreement count

Verbose/research per-task views can include:

• Agreement
• Disagreements
• Final Action