Skip to main content
AI/MLjmagly

tot-decide

Evaluate architectural decisions using Tree of Thoughts exploration

Stars
141
Source
jmagly/aiwg
Updated
2026-05-31
Slug
jmagly--aiwg--tot-decide
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/jmagly/aiwg/HEAD/agentic/code/frameworks/sdlc-complete/skills/tot-decide/SKILL.md -o .claude/skills/tot-decide.md

Drops the SKILL.md into .claude/skills/tot-decide.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

Tree of Thoughts Decision Command

Evaluate architectural decisions by generating and scoring k alternatives using the ToT methodology.

Instructions

When invoked, perform structured Tree of Thoughts exploration for architecture decisions:

  1. Parse Decision Context

    • Extract the decision question from arguments or prompt
    • Identify relevant non-functional requirements from .aiwg/requirements/nfr-modules/
    • Load existing architectural constraints from .aiwg/architecture/

  2. Load ToT Protocol

    • Reference @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/schemas/flows/tree-of-thought.yaml for workflow schema
    • Reference @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/enhancements/architecture-designer-tot-protocol.md for agent protocol

  3. Define Evaluation Criteria

    • Extract criteria from NFRs (scalability, security, performance, maintainability)
    • Assign weights based on project priorities
    • Define scoring rubric (1-5 scale)

  4. Generate Alternatives (k=3 default)

    • Generate k distinct architectural approaches
    • Each alternative must be meaningfully different (not variations of the same approach)
    • Document the core idea, key components, and trade-offs for each

  5. Score and Compare

    • Build weighted scoring matrix
    • Calculate composite scores
    • Identify clear winner or close calls requiring stakeholder input

  6. Generate ADR

    • Use @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/templates/architecture/adr-with-tot.md template
    • Document all alternatives with scores
    • Record decision rationale and trade-offs accepted
    • Include backtracking triggers (conditions for re-evaluation)

  7. Output

    • Display scoring matrix summary
    • State recommendation with confidence level
    • Save ADR to .aiwg/architecture/
    • If close call (score gap < 0.5), flag for human decision gate

Arguments

  • [decision-context] - Description of the architectural decision (required)
  • --alternatives [k] - Number of alternatives to generate (default: 3, max: 7)
  • --depth [levels] - Depth of exploration per alternative (default: 2)
  • --output [path] - Custom output path for ADR (default: .aiwg/architecture/)
  • --criteria [list] - Override criteria (comma-separated)
  • --quick - Skip detailed analysis, produce summary matrix only

Examples

Full Architecture Decision

/tot-decide "Select authentication approach for multi-tenant SaaS platform"

Output:

Tree of Thoughts Decision Analysis
===================================

Decision: Authentication approach for multi-tenant SaaS

Criteria (from NFRs):
  Security    [30%] - Multi-tenant isolation required
  Scalability [25%] - 10K+ tenants expected
  Cost        [20%] - Startup budget constraints
  Dev Speed   [15%] - MVP in 3 months
  Maintenance [10%] - Small ops team

Alternatives Generated:
  A: OAuth2 + OIDC with tenant-scoped JWTs
  B: Session-based with Redis cluster per tenant
  C: API key + HMAC with per-request validation

Scoring Matrix:
  | Criterion     | Wt  | A    | B    | C    |
  |---------------|-----|------|------|------|
  | Security      | 30% | 5    | 4    | 3    |
  | Scalability   | 25% | 5    | 3    | 4    |
  | Cost          | 20% | 3    | 2    | 5    |
  | Dev Speed     | 15% | 3    | 4    | 5    |
  | Maintenance   | 10% | 4    | 2    | 4    |
  | Weighted      |     | 4.15 | 3.10 | 4.00 |

Recommendation: Option A (OAuth2 + OIDC)
  Confidence: HIGH (gap > 0.5 from runner-up)
  Trade-off accepted: Higher initial dev cost for superior security/scale

ADR saved: .aiwg/architecture/adr-auth-approach.md

Quick Comparison

/tot-decide "Database for event sourcing" --alternatives 4 --quick

Deep Analysis

/tot-decide "Microservices vs modular monolith" --depth 3 --criteria "scalability,team-autonomy,ops-complexity,latency"

References

  • @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/schemas/flows/tree-of-thought.yaml - ToT workflow schema
  • @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/agents/enhancements/architecture-designer-tot-protocol.md - Agent enhancement
  • @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/templates/architecture/adr-with-tot.md - ADR template
  • @.aiwg/research/findings/REF-020-tree-of-thoughts.md - Research foundation
  • @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/reasoning-sections.md - Reasoning requirements