| 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:
- Is the plan technically feasible? (✅/⚠️/❌)
- What is the effort vs alternative comparison?
- What is the recommended implementation sequence?
- What risks does the plan owner need to know about?
