architecture-designer-tot-protocol

Architecture Designer: Tree of Thoughts Enhancement

**Enhancement Version:** 1.0.0 **Base Agent:** @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/architecture-designer.md **Research Basis:** REF-020 Tree of Thoughts (Yao et al., 2023, NeurIPS) **Issue:** #97 **Status:** Active **Last Updated:** 2026-01-25

---

Overview

This document extends the Architecture Designer agent with Tree of Thoughts (ToT) decision-making protocol for systematic evaluation of architectural alternatives. ToT improves architecture decision quality through deliberate exploration of multiple paths before committing to a choice.

**Core Enhancement:** When creating Architectural Decision Records (ADRs), generate and evaluate k=3-5 alternatives using weighted scoring against NFR-derived criteria, enabling data-driven selection with documented trade-offs.

---

Enhanced Agent Capabilities

New Capabilities

1. **Multi-alternative generation** - Create k=3-5 distinct architectural options per decision 2. **NFR-based evaluation** - Score alternatives against weighted criteria derived from non-functional requirements 3. **Quantitative comparison** - Build scoring matrices showing weighted contributions 4. **Backtracking planning** - Define measurable triggers for decision re-evaluation 5. **Trade-off documentation** - Explicit acknowledgment of what is sacrificed in selection

Existing Capabilities (Retained)

All base Architecture Designer capabilities remain unchanged (system architecture design, technology stack selection, microservice boundary definition, data model design, API contract specification, deployment architecture planning, security architecture design, disaster recovery planning) — see `@$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/architecture-designer.md`.

---

ToT Decision-Making Protocol

Protocol Activation

The Architecture Designer agent enters ToT mode when:

1. **Explicit request:** User asks for "alternatives evaluation" or "ToT-based decision" 2. **ADR creation:** Any ADR creation task triggers ToT workflow 3. **High-stakes decision:** Technology stack, database selection, architectural pattern choice 4. **Ambiguous requirements:** Multiple valid approaches possible

**Default:** All ADR creation uses ToT protocol unless user explicitly requests single-option justification.

5-Phase ToT Workflow

Phase 1: Criteria Definition (Pre-Generation)

**Objective:** Establish evaluation framework before exploring alternatives.

**Activities:** 1. Read relevant NFR modules from `@.aiwg/requirements/nfr-modules/` 2. Identify applicable quality attributes (performance, scalability, security, maintainability, cost) 3. Assign weights based on NFR priorities and project context 4. Define minimum acceptable threshold (default: 65/100) 5. Specify critical (pass/fail) criteria if any

**Output:** Evaluation criteria table in ADR (weighted criteria + minimum score + critical pass/fail criteria).

> Worked examples for every phase: see `docs/agent-examples/architecture-designer-tot-protocol-examples.md` (`aiwg discover "architecture designer tot protocol worked examples"`).

Phase 2: Alternative Generation (k=3-5)

**Objective:** Create diverse architectural options representing different trade-off optimizations.

**Generation Strategy:**

Use one or more of these strategies to ensure diversity (illustrative examples in the worked-examples link above):

1. **Pattern-based diversity:** ensures fundamentally different architectural styles (e.g., monolith vs microservices vs serverless). 2. **Technology-based diversity:** ensures different technology ecosystem trade-offs (e.g., PostgreSQL vs MongoDB vs DynamoDB). 3. **Trade-off optimization diversity:** ensures different criteria prioritizations (e.g., performance- vs cost- vs simplicity-optimized). 4. **Vendor/ecosystem diversity:** ensures different lock-in and integration trade-offs (e.g., AWS-native vs GCP-native vs multi-cloud). 5. **Hybrid combinations:** ensures creative combinations (e.g., REST+polling vs WebSocket vs GraphQL subscriptions vs gRPC streaming).

**Minimum k=3, Recommended k=5:**

• k=3: Fast decisions, limited exploration
• k=5: Thorough exploration, better coverage (recommended default)
• k>5: Rarely justified, diminishing returns

**Include status quo:** If modifying existing architecture, include "keep current approach" as baseline for comparison.

**Output:** 3-5 option descriptions with implementation details (see worked-examples link above).

Phase 3: Systematic Evaluation

**Objective:** Score each option against criteria with documented rationale.

**Scoring Guidelines:**

Use 0-10 scale:

• **0-2:** Fails criterion, significant issues
• **3-4:** Poor fit, major concerns
• **5-6:** Acceptable, notable compromises
• **7-8:** Good fit, minor concerns
• **9-10:** Excellent fit, ideal

**Evaluation Template (per option) — required fields:**

• Per-criterion score table (Criterion | Score 0-10 | Rationale) with specific rationale for every score
• Weighted Score: sum of (score × weight) × 10, reported out of 100
• Critical Criteria Check: pass/fail against each critical threshold
• Pros, Cons, and Risks (each risk paired with a Mitigation)

(See worked-examples link above for a fully populated per-option template.)

**Evaluate all k options** using this template before proceeding to comparison.

Phase 4: Comparison and Selection

**Objective:** Build comparison matrix, identify highest-scoring option, apply context to make final selection.

**Comparison Matrix:** Build one row per option with per-criterion scores, the weighted contribution (score × weight) in parentheses, a bolded weighted **Total**, and a Critical Pass? column.

**Selection Process:**

1. **Eliminate failures:** Remove options failing any critical criterion; remove options below the minimum threshold. 2. **Identify quantitative winner:** Rank surviving options by total score. 3. **Apply context factors:**