Smithery is now a part of Arcade.dev! Read more in our announcement here
Transform vague requirements into concrete decisions by exploring the decision space...
You help transform high-level desires into concrete, justified decisions by systematically exploring the decision space, identifying dependencies, and challenging default assumptions that would otherwise create mediocre implementations.
Every high-level requirement explodes into a decision tree. Every default hides assumptions that may be wrong for your specific context. The path to exceptional software is systematically questioning assumptions rather than accepting statistical averages.
Research from requirements engineering shows that 60-80% of project failures trace back to requirements problems, not technical execution.
High-level: "Users should authenticate"
Immediate questions:
Second-order decisions:
Hidden assumptions defaulted without thought:
Initial request: "We need user profiles"
Why 1: "Why do we need user profiles?"
Why 2: "Why personalize the experience?"
Why 3: "Why separate data by user?"
Why 4: "Why not just department-level separation?"
Why 5: "Why is individual accountability needed?"
Actual requirement discovered:
Questions to ask:
Anti-patterns to catch:
Questions to ask:
Revelations these produce:
Questions to ask:
Discoveries these enable:
Hard constraints: If A then must B
Mutual exclusions: If A then cannot B
Soft preferences: If A then prefer B
Find decisions that unlock or constrain many others:
Example lynchpin: "Is this application internal only?"
If internal_only = true:
If internal_only = false:
User assumptions:
| Default | Alternatives |
|---|---|
| "Users have email addresses" | Phone, Employee ID, Username only |
| "Users have persistent identity" | Anonymous, Session-only, Ephemeral |
| "Users want to customize" | Defaults fine, Admin-configured |
| "Users access from multiple devices" | Single workstation, Shared terminals |
Scale assumptions:
| Default | Reality Check |
|---|---|
| "Need to handle millions of users" | What's realistic year 1, 3, 5? |
| "Must scale horizontally" | Would vertical work for projected load? |
| "Needs real-time updates" | What latency is actually acceptable? |
| "Requires microservices" | What's the team size and skill? |
Technical assumptions:
| Default | Alternatives |
|---|---|
| "Need a database" | Files, In-memory, External API, Event log |
| "Need user accounts" | Shared access, Token-based, IP-based |
| "Need REST API" | GraphQL, RPC, Message queue, Direct DB |
| "Need responsive design" | Desktop only, Mobile only, Fixed viewport |
Symptoms of gravity:
Resistance techniques:
Devil's Advocate:
Scenario Testing:
Decision Brief:
header:
decision_id: "DEC-YYYY-NNN"
title: "[Decision Name]"
impact: "[Foundational/Major/Minor]"
reversibility: "[Easy/Moderate/Difficult]"
context:
requirement_trace: "[Original requirement]"
discovered_context:
- "[Context item 1]"
- "[Context item 2]"
existing_constraints:
- "[Constraint 1]"
- "[Constraint 2]"
options:
option_1:
name: "[Option name]"
description: "[What this means]"
pros: ["[Pro 1]", "[Pro 2]"]
cons: ["[Con 1]", "[Con 2]"]
cost: "[Low/Moderate/High]"
risk: "[Low/Medium/High]"
effort: "[Estimate]"
eliminated_options:
"[Option name]":
reason: "[Why eliminated]"
dependencies:
decisions_this_enables: ["[Decision 1]"]
decisions_this_requires: ["[Decision 2]"]
recommendation:
choice: "[Recommended option]"
rationale: ["[Reason 1]", "[Reason 2]"]
conditions: ["[Condition 1]", "[Condition 2]"]
Functional requirements:
Non-functional requirements:
Technical specifications:
Anti-requirements (crucial for preventing scope creep):
Technical spike (1-3 days):
User spike (2-5 days):
Integration spike (3-5 days):
Immediate reversal needed when:
Considered reversal when:
Pattern: Spending months gathering requirements through endless stakeholder meetings without building anything. Why it fails: Requirements evolve when users see working software. Perfect understanding is impossible upfront; stakeholders often don't know what they want until they see what they don't want. Fix: Time-box exploration phases. Build prototypes early. Validate assumptions through spikes rather than meetings. Aim for "good enough to start" rather than "complete."
Pattern: Accepting defaults without documentation—"obvious" choices everywhere, copy-paste architecture from previous projects. Why it fails: Undocumented decisions become invisible constraints. When problems emerge later, no one remembers why choices were made or whether alternatives were considered. Fix: Document every significant decision with rationale. Challenge defaults explicitly. Create decision briefs even for "obvious" choices so the reasoning is captured.
Pattern: "While we're at it" additions during requirements gathering. Nice-to-have becomes must-have through scope bleed. Why it fails: Discovery expands indefinitely. The "complete" feature set grows faster than implementation capacity. Core value gets buried under accumulated wants. Fix: Maintain strict must/should/could separation. Create anti-requirements (what you will NOT build). Revisit scope when additions emerge—something must leave if something enters.
Pattern: Requirements specify technology choices: "Use React" instead of "Users need fast page loads." How before what. Why it fails: Technology choices belong to implementation. Premature technology constraints eliminate potentially better solutions and encode assumptions that may be wrong. Fix: Write requirements as user outcomes and constraints. Keep technology decisions separate. Let implementation choose how to achieve the what.
Pattern: Treating one vocal stakeholder as the voice of all users. Requirements reflect their preferences without broader validation. Why it fails: Individual stakeholders have individual biases. The loudest voice rarely represents typical users. Edge cases become core requirements. Fix: Identify all user categories. Get input from multiple representatives. Validate requirements with actual usage data where available. Weight inputs by user volume.
| Skill | What it provides |
|---|---|
| requirements-analysis | Initial problem framing and stakeholder identification |
| research | Domain knowledge and prior art discovery |
| Skill | What this provides |
|---|---|
| system-design | Concrete requirements and constraints for architecture |
| github-agile | User stories and acceptance criteria for implementation |
| Skill | Relationship |
|---|---|
| requirements-analysis | Use requirements-analysis for initial scoping, elaboration for deep decision discovery |
| system-design | Use elaboration to define what, system-design to define how |
