ADR Decision Workflow Skill

Purpose

Provides a reusable Mixture-of-Experts (MoE) workflow pattern for creating comprehensive Architecture Decision Records. This skill encapsulates the multi-agent coordination logic used by /adr-decision.

When to Use

• Creating new Architecture Decision Records
• Evaluating technology choices
• Comparing solution alternatives
• Documenting architectural decisions
• Any decision requiring multi-perspective analysis

Workflow Phases

Phase 1: Research

Agent: research-agent Output: research-findings.json

research_prompt = """
Research all viable solutions for: {topic}

For each option provide:
- Name and brief description
- How it works
- Pros (bullet list)
- Cons (bullet list)
- Complexity (1-5)
- Cost (free/low/medium/high)
- Reliability (1-5)
- Best use case

Find at least 5-10 alternatives.
"""

Phase 2: Technical Analysis

Agent: senior-architect Output: technical-analysis.json

analysis_prompt = """
Evaluate solutions against decision drivers:
1. Reliability & durability
2. Automation level
3. Implementation complexity
4. Maintenance burden
5. Scalability
6. Security implications
7. Integration with existing systems

Solutions: {research_output}
"""

Phase 3: Business Analysis

Agent: business-intelligence-analyst Output: business-analysis.json

business_prompt = """
Perform cost-benefit analysis:
- Total cost of ownership (TCO)
- Implementation effort (person-hours)
- ROI timeline
- Risk assessment
- Vendor lock-in analysis

Solutions: {research_output}
Technical Analysis: {architect_output}
"""

Phase 4: Scoring

Agent: orchestrator Output: scored-options.json

SCORING_WEIGHTS = {
    "reliability": 20,
    "automation": 15,
    "cost": 15,
    "complexity": 15,  # Inverted: lower complexity = higher score
    "scalability": 10,
    "security": 10,
    "integration": 10,
    "community": 5
}

def calculate_score(option: dict, weights: dict) -> float:
    """Calculate weighted score for an option."""
    score = 0
    for factor, weight in weights.items():
        if factor == "complexity":
            # Invert complexity (lower is better)
            score += (6 - option.get(factor, 3)) * weight / 5
        else:
            score += option.get(factor, 3) * weight / 5
    return round(score, 1)

def rank_options(options: list, weights: dict) -> list:
    """Rank options by score."""
    for opt in options:
        opt['score'] = calculate_score(opt, weights)
    return sorted(options, key=lambda x: x['score'], reverse=True)

Phase 5: Compliance Check

Agent: adr-compliance-specialist Output: compliance-review.json

compliance_prompt = """
Review architectural decision for compliance:

Topic: {topic}
Recommended Solution: {top_option}

Check against:
1. Existing ADRs in internal/architecture/adrs/
2. CODITECT architectural principles
3. Security requirements
4. Performance standards

Flag any conflicts or concerns.
"""

Phase 6: Documentation

Agent: codi-documentation-writer Output: ADR-XXX-title.md

adr_template = """
---
title: ADR-{number}: {title}
status: Proposed
date: {date}
decision-makers: [AI-assisted analysis]
---

# ADR-{number}: {title}

## Status
Proposed

## Context
{context}

## Decision Drivers
{drivers}

## Considered Options
{options}

## Decision Outcome
Chosen option: "{recommendation}"

{justification}

## Comparison Matrix
{matrix}

## Pros and Cons
{pros_cons}

## Implementation Plan
{plan}

## Consequences
{consequences}

## References
{references}
"""

Phase 7: Organization

Agent: project-organizer Output: Updated indexes

organization_tasks = [
    "Determine next ADR number",
    "Save to correct category folder",
    "Update ADR index",
    "Add cross-references",
    "Update related documentation"
]

Integration

With Commands

# Primary command
/adr-decision "topic"

# Related commands
/agent adr-compliance-specialist "review ADR-015"
/agent codi-documentation-writer "update ADR format"

With Hooks

• pre-adr-create: Validates topic, checks duplicates
• post-adr-create: Updates indexes, triggers notifications

With Workflows

• ARCHITECTURE-DECISION-WORKFLOWS.md
• DOCUMENTATION-WORKFLOWS.md

Customization

Custom Weights

# Prioritize security over cost
custom_weights = {
    "reliability": 15,
    "security": 25,  # Increased
    "cost": 10,      # Decreased
    ...
}

Custom Agents

# Add domain-specific expert
custom_phases = {
    "domain_review": {
        "agent": "database-architect",
        "prompt": "Review from database perspective..."
    }
}

Example Usage

from skills.adr_decision_workflow import ADRWorkflow

workflow = ADRWorkflow(
    topic="Multi-machine context database sync",
    category="cloud-platform",
    weights=SCORING_WEIGHTS
)

# Run full workflow
adr = workflow.execute()

# Or run phases individually
research = workflow.phase_research()
analysis = workflow.phase_analysis(research)
scores = workflow.phase_scoring(analysis)
adr = workflow.phase_documentation(scores)

Artifacts

Phase	Output	Location
Research	research-findings.json	context-storage/adr-research/
Analysis	technical-analysis.json	context-storage/adr-research/
Business	business-analysis.json	context-storage/adr-research/
Scoring	scored-options.json	context-storage/adr-research/
Compliance	compliance-review.json	context-storage/adr-research/
ADR	ADR-XXX-*.md	internal/architecture/adrs/{category}/

---

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: adr-decision-workflow

Completed:
- [x] Research phase: 5-10 alternatives identified
- [x] Technical analysis: Decision drivers evaluated
- [x] Business analysis: TCO and ROI calculated
- [x] Scoring phase: Options ranked by weighted score
- [x] Compliance check: No conflicts with existing ADRs
- [x] Documentation: ADR-XXX created
- [x] Organization: ADR indexed and cross-referenced

Outputs:
- context-storage/adr-research/research-findings.json
- context-storage/adr-research/technical-analysis.json
- context-storage/adr-research/business-analysis.json
- context-storage/adr-research/scored-options.json
- internal/architecture/adrs/{category}/ADR-XXX-{title}.md

Top Recommendation: {option} (Score: X/100)

Completion Checklist

Before marking this skill as complete, verify:

• All 7 phases executed in order (research → documentation)
• Research phase produced 5+ viable alternatives
• Technical analysis covers all decision drivers
• Business analysis includes TCO, ROI, and risk assessment
• Scoring uses correct weight values and calculations
• Compliance check validated against existing ADRs
• ADR document follows standard template format
• ADR assigned correct sequential number
• ADR saved to appropriate category folder
• ADR index updated with new entry
• All artifact JSON files created in adr-research/

Failure Indicators

This skill has FAILED if:

• ❌ Research phase finds fewer than 3 alternatives
• ❌ Agent invocation errors (research-agent not found, etc.)
• ❌ Scoring produces all zeros or NaN values
• ❌ Compliance check detects unresolved conflicts
• ❌ ADR document missing required sections
• ❌ ADR number conflicts with existing ADR
• ❌ Unable to determine next ADR number
• ❌ Artifact files corrupted or incomplete JSON

When NOT to Use

Do NOT use this skill when:

• Decision already made (use /adr-document to record it)
• Trivial choice with obvious answer (overhead not justified)
• No alternatives exist (single vendor lock-in scenario)
• Decision reversible without cost (use lightweight documentation)
• Emergency hotfix situation (document decision retroactively)
• Prototype/POC phase (premature architectural commitment)

Use alternatives:

• adr-lightweight-workflow - For simple, low-impact decisions
• decision-record-template - For recording pre-made decisions
• spike-investigation - For exploring options without commitment

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Running workflow for every decision	Analysis paralysis, overhead	Reserve for significant architectural choices
Skipping compliance phase	Conflicts with existing ADRs	Always run compliance check before finalizing
Using stale research data	Recommendations outdated (2+ months)	Re-run research phase if data old
Ignoring business analysis	Technical-only decisions miss ROI	Include TCO and risk even for "pure tech"
Custom scoring without docs	Team can't understand rankings	Document any custom weights/factors
No cross-references	ADRs exist in isolation	Link to related ADRs, standards, docs
Executing phases out of order	Missing context for later phases	Strictly follow 7-phase sequence

Principles

This skill embodies:

• #1 Search Before Create - Research phase explores all existing solutions
• #2 First Principles - Decision drivers derived from fundamental requirements
• #5 Eliminate Ambiguity - Scoring makes subjective choices objective
• #6 Clear, Understandable, Explainable - ADR documents reasoning transparently
• #8 No Assumptions - Compliance phase validates against actual ADR repository
• Mixture of Experts - 4 specialized agents (research, architect, business, compliance)
• Progressive Disclosure - Research artifacts available for deep-dive investigation

Standard: CODITECT-STANDARD-AUTOMATION.md

---

Last Updated: 2026-01-04 Version: 1.1.0 | Quality Standard Applied Related: /adr-decision, adr-compliance-specialist, codi-documentation-writer