---
name: ai-solution-evaluation
description: Evaluate AI solutions across 4 dimensions — Confidence, Risk, Effort, Soundness — before accepting any recommendation. Prevents blind plan acceptance and production disasters. Source: Sam/Francis, AI workflow expert.
version: 1.0.0
metadata:
  filePattern: "**/*"
priority: 90
---

# AI Solution Evaluation

## The 4-Dimension Matrix

When asking for solutions, ALWAYS request evaluation across these four dimensions:

| Dimension | Question | Why It Matters |
|-----------|----------|---------------|
| **Confidence** | How certain is the AI this will actually work? | Low = needs a spike/prototype first |
| **Risk** | What's the likelihood of breaking something in production? | High = needs feature flag or staged rollout |
| **Effort** | How many files/services/changes are involved? | High = needs more planning phases |
| **Soundness** | Is this architecturally correct for this system? | Low = technical debt you'll pay later |

## Standard Request Template

```
Give me 3 solutions for [problem].
For each, rate:
- Confidence (High/Med/Low): how certain are you this works?
- Risk (High/Med/Low): what's the chance we break something in production?
- Effort (S/M/L): how many changes are involved?
- Soundness (✅/⚠️/❌): is this architecturally correct?
Recommend the option with highest confidence and lowest risk.
```

## AI's Natural Behavior — Use It

- AI is **naturally risk-averse** — it always generates fallback paths
- It will NOT recommend deleting production data unless you explicitly say it's safe
- Left to its own devices, it picks the safest option — **let it**
- If it recommends something risky, ask: "Why risky? Is there a safer path?"

## Plan Review Protocol

**NEVER accept a plan as a wall of text.**

1. Ask for the plan
2. Say: "Give me the negatives/concerns first" (black-first review)
3. Say: "Now visualize this as a Mermaid diagram or ASCII flowchart"
4. Understand the visual before approving
5. Only say yes when you understand every step

## Workflow Building Blocks (Mix and Match)

Commands are not a linear pipeline — treat as choose-your-own-adventure:

| Command | Use When |
|---------|----------|
| `/research` | Don't understand the problem space yet |
| `/solutions` | Need options with 4-dimension evaluation |
| `/plan` | Have a chosen solution, need implementation steps |
| `/visualize` | Plan is a wall of text — always run this |
| `/review` | Black-first review before accepting |
| `/execute` | Only after all above are done |

## Multi-Agent Decision

| Situation | Use |
|-----------|-----|
| Standard feature implementation | Single primary agent |
| Parallel domain reviews (FE + BE simultaneously) | Sub-agents (carefully) |
| Workflow orchestration | Single agent with orchestration system prompt |

**Before using sub-agents**: run the same task with a single agent and compare.
Sub-agents are slower, use more tokens, and can produce code that can't talk to each other.

## Anti-Patterns
- ❌ "Looks good to me" on a wall-of-text plan
- ❌ Accepting the first solution without the 4-dimension evaluation
- ❌ Using multi-agent when a single agent would suffice
- ❌ Ignoring the risk dimension for production systems
- ❌ Skipping the visualization step (you will miss something)
- ❌ FOMO-chasing new AI features — slash commands + skills are all you need