proposal-evaluation

name	proposal-evaluation
description	Systematically evaluate technical proposals, migration plans, and design documents — verifying premises, assessing per-solution feasibility, comparing alternatives, and producing a risk register.
category	software-development
triggers	["evaluate feasibility of a plan/migration/proposal","review technical design document","analyze migration strategy","compare architecture alternatives"]

Proposal Evaluation Framework

Evaluate any technical proposal, design document, or migration plan with a structured, repeatable framework. Start with the core premise, then evaluate each proposed solution individually, then synthesize with alternative comparison and risk register.

Workflow

1. Core Premise Verification

Before evaluating individual solutions, identify and validate the foundational assumptions the proposal is built on.

For each premise:
  - State the claim explicitly
  - Check against authoritative documentation / known constraints
  - Label: ✅ true, ⚠️ partially true, ❌ false
  - Add evidence and citations

If a core premise is wrong, the downstream analysis is moot — surface this first.

2. Per-Solution Evaluation

For each proposed "how to fix X" or solution step:

✓/⚠️/❌ Summary label   ← quick verdict
Arguments:
  - Why it works (with technical evidence)
  - Failure modes (be specific about trigger conditions)
Constraints:
  - Dependencies (tools, permissions, environment, services)
  - Hidden costs (time, complexity, maintenance burden)

Don't just say "it works" — quantify.

• "✅ Works because Cloudflare documents X as I/O, not CPU"
• "⚠️ Loads a 120MB model into browser — verify on mobile Safari first"
• "❌ Exceeds 128MB memory limit on Free tier: 152MB > 128MB"

3. Implementation Ordering Assessment

Given multiple proposed steps, determine the optimal sequence:

Step	Risk	Dependencies	Alone Value	Recommended Position
A	low	none	fixes the most dangerous bug	1st
B	low	none	unblocks local dev	2nd
C	medium	A+B done	provides testing baseline	3rd
D	medium	none	core feature	4th

Rule of thumb: do low-risk, high-value, no-dependency steps first. Each step should be independently verifiable and independently revertible.

4. Alternative Comparison

If the user proposed one approach, present the leading alternative(s) for comparison:

Dimension	Proposed Approach	Alternative (e.g. "$5/mo upgrade")
Cost	$0 ongoing	$5/mo
Effort	12h implementation	0.5h
Complexity	High (JS model + IndexedDB)	Low (existing code unchanged)
Latency (first)	5-15s (model download)	1-2s
Latency (subsequent)	100-300ms	1-2s

Let the comparison guide, not dictate. The user's context (budget, time, risk tolerance) determines the right call.

5. Risk Register

Systematically list risks the plan didn't account for:

#	Risk	Trigger	Impact	Mitigation
R1	Model download fails	Old browser, no WebGL	Feature degraded	Timeout → auto downgrade
R2	Multi-tab memory	3+ tabs open	Browser OOM	Service Worker sharing

Good risk entries have three properties:

• Specific ("iOS Safari IndexedDB 50MB limit") not vague ("mobile might not work")
• Actionable mitigation — not just "be careful"
• Bounded — the worst case is limited, not catastrophic

6. Updated Verification Checklist

Produce a new checklist that covers:

□ Step-specific: each implementation step has its own verification
□ Environment coverage: Docker, Cloudflare, GitHub Pages, localhost
□ Edge case: failure mode / degraded path tested
□ Existing baseline: previous behavior still works

Pitfalls

• Don't skip premise verification: if a core assumption is wrong, the entire analysis is sand.
• Don't assert without evidence: every ⚠️ / ❌ needs a specific technical reason and source.
• Don't miss the alternative: always compare with the simplest alternative (even "do nothing" or "pay $5/mo").
• Don't write vague risks: "network might fail" → prescribe the specific failure mode and the automated fallback.
• Don't recommend without tradeoffs: present the choice clearly, state what's lost and gained.
• Know when to stop: a plan that passes core premise verification and whose risks all have solid mitigations is feasible. Don't keep inventing hypothetical edge cases.

Verification

After analysis, the deliverable should answer:

1. Is the plan technically feasible? (✅/⚠️/❌)
2. What is the effort vs alternative comparison?
3. What is the recommended implementation sequence?
4. What risks does the plan owner need to know about?