Decision Helper

Step 2: Define Criteria

Goal: Establish what matters for this decision and how much.

Present the default criteria table unless the user provides custom criteria. Ask if they want to adjust weights or add/remove criteria.

WHY these defaults: Correctness dominates because a wrong solution has zero value regardless of other factors. Complexity/Maintainability/Risk form a middle tier because they determine long-term cost. Effort/Familiarity are lower because they're temporary (teams learn, effort is one-time). Ecosystem is lowest because it rarely decides between otherwise-equal options.

Use defaults unless the user has a strong reason to change them. Agonizing over whether Complexity should be weight 3 or 4 rarely changes the outcome -- the framework exists to make decisions faster, not slower. Set weights before scoring; adjusting weights after seeing results to make a preferred option win is confirmation bias with extra steps.

If the user wants sensitivity analysis, re-score with adjusted weights after the initial pass to test recommendation stability.

Gate: Criteria and weights confirmed (default or custom).

Step 3: Score Each Option

Goal: Rate each option against each criterion with justification.

Score every criterion 1-10 (1-3 poor, 4-6 adequate, 7-9 strong, 10 exceptional). Provide a one-sentence justification per score -- this prevents arbitrary numbers and makes disagreements productive.

Calculate weighted score: sum(score * weight) / sum(weights)

Treat scores as subjective estimates, not measurements. A difference of 0.03 between two options is noise, not signal -- the close-call detection in Step 4 handles this.

Gate: All options scored, all scores justified, weighted scores calculated.

Step 4: Analyze Results

Goal: Interpret the scores and provide a clear recommendation.

Apply these rules in order:

1. No Good Option (all weighted scores <6.0): Flag that none of the options are strong. Suggest the user explore alternatives or revisit constraints
2. Close Call (top two within 0.5): Always flag as "close call -- additional factors should decide." Identify which criteria drive the difference and ask the user what matters most. Never hand-wave a close call with "close enough, just pick one" -- these deserve explicit acknowledgment
3. Clear Winner (top option leads by >0.5): Recommend the winner. Note which high-weight criteria drove the result
4. Dominant Option (top option leads on ALL weight-5 criteria): Note the dominance -- this is a high-confidence recommendation

If the matrix contradicts the user's intuition, do not override the math. Instead, ask which criterion is missing or mis-weighted. Add it, re-score, and see if the matrix now agrees. If it does, you found the hidden factor. If it still disagrees, trust the matrix -- it surfaces the reasoning that gut feelings obscure.

Present the output table:

## Decision: [statement]

| Criterion (weight) | Option A | Option B | Option C |
|---------------------|----------|----------|----------|
| Correctness (5)     | 8        | 7        | 9        |
| Complexity (3)      | 6        | 8        | 4        |
| Maintainability (3) | 7        | 7        | 5        |
| Risk (3)            | 6        | 8        | 4        |
| Effort (2)          | 7        | 5        | 3        |
| Familiarity (2)     | 8        | 4        | 2        |
| Ecosystem (1)       | 7        | 6        | 8        |
| **Weighted Score**  | **7.0**  | **6.7**  | **5.2**  |

**Recommendation**: Option A (7.0) — [key reasoning]
**Confidence**: High / Medium (scores within 0.5) / Low (no option >6.0)

Gate: Recommendation stated with confidence level. Close calls flagged.

Step 5: Persist Decision

Goal: Record the decision for future reference.

Check for an active ADR session:

cat .adr-session.json 2>/dev/null

If ADR exists: Append a decision record (statement, options, winner, key reasoning, confidence, date) to the ADR's decisions section.

If no ADR: Note the decision in the active task plan (plan/active/*.md). If neither exists, present the record to the user for manual recording.

The user can skip persistence for informal exploration by requesting it.

Gate: Decision recorded or presented. Workflow complete.

Error Handling

Error: "Too many options"

Cause: User presents 5+ options Solution: Help decompose. Group similar options or eliminate clearly inferior ones first. Then score the remaining 2-4.

Error: "Criteria don't fit this decision"

Cause: Default criteria aren't relevant (e.g., scoring a content strategy, not a technical choice) Solution: Ask the user to define custom criteria. Suggest domain-appropriate alternatives.

Error: "Scores feel wrong"

Cause: User disagrees with a score after seeing the matrix Solution: Adjust the score and recalculate. The matrix is a tool for the user, not an authority over them. If many scores feel wrong, the criteria may need revisiting.

References

• Repository CLAUDE.md files (read before execution for project-specific constraints)

Reference Loading Table

Load these files when the corresponding signals appear in the decision request: