Decision Maps

What is a Decision Map?

A decision map is a structured representation of the debate between Boundary's agents. It synthesizes all perspectives into an auditable record of:

• Trade-offs: Competing engineering values and their implications
• Risk surfaces: Concrete failure vectors that emerge from agent conflict
• Irreversible commitments: Decisions that will be difficult or impossible to undo later
• Assumption dependencies: Hidden assumptions that the decision relies on
• Failure modes: Specific ways the decision could fail under different conditions

Unlike a traditional recommendation, a decision map preserves the tension between competing values. It shows you the decision space in all its complexity, not just a single path forward.

Reading a Decision Map

Structure

Decision maps are organized into several key sections:

• Executive Summary: High-level overview of the decision and key concerns
• Agent Perspectives: The positions taken by each agent and their reasoning
• Disagreements: Points of conflict between agents, which often indicate significant trade-offs
• Risk Surfaces: Concrete failure vectors identified through the debate
• Irreversible Commitments: Decisions that create long-term constraints
• Assumption Dependencies: Hidden assumptions that must hold for the decision to succeed

Key Indicators

When reading a decision map, look for:

• High disagreement: When agents strongly disagree, it indicates a significant trade-off or risk surface that needs careful consideration.
• Escalating concerns: If agents become more concerned as context is gathered, it may indicate a fundamental problem with the approach.
• Consensus on risks: When agents agree on specific risks, those are likely real and important.
• Irreversible commitments: Pay special attention to decisions that will be hard to undo, these are the most critical to get right.

Understanding Risk Surfaces

Risk surfaces are not probabilities, they are concrete failure vectors that emerge from the agent conflict. Each risk surface represents a specific way your decision could fail:

• Technical risks: System failures, performance degradation, scalability limits
• Security risks: Attack vectors, data exposure, authentication vulnerabilities
• Operational risks: Complexity overhead, testing burden, maintenance costs
• Domain risks: Violations of business logic, downstream bugs, invariant violations

The value of risk surfaces is that they are specific and actionable. They tell you not just that something might go wrong, but how it might go wrong and under what conditions.

Trade-offs and Failure Modes

Decision maps explicitly surface trade-offs between competing engineering values:

• Simplicity vs. Scalability: Simple solutions may not scale, but scalable solutions add complexity
• Security vs. Usability: More secure systems may be harder to use, while user-friendly systems may have security gaps
• Speed vs. Correctness: Fast implementations may have edge cases, while correct implementations may be slower
• Flexibility vs. Constraints: Flexible designs may be harder to reason about, while constrained designs may be too rigid

Each trade-off represents a decision point. The decision map helps you understand what you're giving up and what you're gaining with each choice.

Using Decision Maps in Practice

Decision maps are most valuable when used as:

• Decision memory: Store decision maps for future reference when similar boundaries emerge. They become a queryable knowledge base of past decisions and their trade-offs.
• Team communication: Share decision maps with your team to ensure everyone understands the risks and trade-offs involved in a decision.
• Risk mitigation planning: Use identified risk surfaces to plan mitigation strategies before implementation.
• Post-mortem analysis: Compare decision maps with actual outcomes to improve future decision-making.

Recording Decisions

After reviewing a decision map, you can record the final decision using the record_decision tool. This creates a permanent record that includes:

• The original decision question
• The complete decision map from the debate
• The final decision taken
• The rationale for choosing that option
• Who participated in the decision

Recorded decisions are stored locally and can be queried later, creating a decision memory that helps inform future choices.