sdlc-framework 1.0.0

package/src/references/clarification-strategy.md

@@ -0,0 +1,352 @@
+# Clarification Strategy Reference
+
+This document explains how the spec phase gathers requirements through targeted questions instead of assumptions. It covers why guessing is dangerous, what categories of questions to ask, how to give recommendations, when to stop asking, and common anti-patterns.
+
+---
+
+## Why No Guessing
+
+AI code generators default to assumptions when requirements are unclear. This is the single biggest source of wasted work in AI-assisted development. The SDLC framework enforces a clarification-first approach: when something is ambiguous, ask — do not guess.
+
+### Concrete Examples of Assumption Failures
+
+**Example 1: "Add authentication"**
+
+Without clarification, the AI assumes:
+- JWT-based auth (could have been session-based)
+- Email + password login (could have been OAuth only)
+- Bcrypt for password hashing (could have been argon2)
+- Access and refresh tokens (could have been single token)
+- 1-hour token expiry (could have been 15 minutes)
+
+The developer spends 3 hours implementing JWT with refresh tokens. The stakeholder wanted OAuth with Google only. 3 hours wasted.
+
+**Example 2: "Fix the search"**
+
+Without clarification, the AI assumes:
+- The bug is in the search results (could be in the search input)
+- It affects all searches (could be only empty searches)
+- The fix is in the backend (could be a frontend display issue)
+- Performance is the issue (could be incorrect results)
+
+The developer optimizes database queries for 2 hours. The actual bug was a CSS issue hiding the search results on mobile. 2 hours wasted.
+
+**Example 3: "Add a dashboard"**
+
+Without clarification, the AI assumes:
+- A web dashboard (could be a CLI dashboard)
+- Real-time data (could be static daily reports)
+- Charts and graphs (could be just numbers in a table)
+- All users see the same dashboard (could be role-based)
+
+The developer builds a real-time React dashboard with Chart.js. The stakeholder wanted a simple table of daily stats in the admin panel. A week wasted.
+
+### The Cost Formula
+
+```
+Cost of asking = 5 minutes per question
+Cost of wrong assumption = 1-8 hours of rework
+Break-even = asking is cheaper if there is even a 10% chance the assumption is wrong
+```
+
+When in doubt, ask. The math always favors it.
+
+---
+
+## Question Categories
+
+Questions fall into five categories. The spec phase should cover all categories that are relevant to the work.
+
+### 1. Scope Questions
+
+**What they clarify:** The boundaries of the work. What is included and what is not.
+
+**When to ask:** Always. Every task has scope ambiguity.
+
+**Examples:**
+- "The request mentions user search. Should this include search by name only, or also by email and role?"
+- "Should the API support pagination, or is the dataset small enough to return all results?"
+- "Does 'fix the login' mean the login form, the authentication logic, or both?"
+- "Should this work on mobile devices, or is desktop-only acceptable for now?"
+
+### 2. Approach Questions
+
+**What they clarify:** How the work should be done. Technical choices.
+
+**When to ask:** When there are multiple valid approaches and the choice affects architecture, performance, or maintainability.
+
+**Examples:**
+- "For storing user sessions, should we use JWT tokens (stateless, scalable) or database sessions (revocable, more control)?"
+- "Should the search be implemented with a simple SQL LIKE query or a full-text search engine like Elasticsearch?"
+- "Should we create a new service for this, or add methods to the existing UserService?"
+- "Should the form validation happen client-side, server-side, or both?"
+
+### 3. Edge Case Questions
+
+**What they clarify:** What happens when things go wrong or inputs are unexpected.
+
+**When to ask:** When the happy path is clear but failure modes are not specified.
+
+**Examples:**
+- "What should happen if a user tries to register with an email that already exists?"
+- "If the external API is down, should we show cached data, an error message, or a fallback?"
+- "What is the maximum number of items a user can add to their cart?"
+- "Should deleted users be hard-deleted or soft-deleted?"
+
+### 4. Integration Questions
+
+**What they clarify:** How this work connects to existing systems.
+
+**When to ask:** When the work interacts with other services, APIs, or systems.
+
+**Examples:**
+- "This feature sends emails. Should it use the existing NotificationService, or is there a different email system?"
+- "The dashboard needs user data. Should it call the UserService directly, or go through the API?"
+- "Should the new endpoint follow the existing API versioning pattern (/v1/users) or use a different scheme?"
+- "Does this need to integrate with the existing authentication middleware?"
+
+### 5. Testing Questions
+
+**What they clarify:** How to verify the work is correct.
+
+**When to ask:** When acceptance criteria are not obvious from the requirement.
+
+**Examples:**
+- "How should we verify the email was sent? Mock the email service and check it was called, or use a test email server?"
+- "Should the e2e tests run against a real database or an in-memory database?"
+- "What is the expected response time for the search API? Do we need performance tests?"
+- "Are there specific browsers or devices we need to test against?"
+
+---
+
+## How to Give Recommendations
+
+Asking questions without offering recommendations puts the burden entirely on the stakeholder. The SDLC framework requires that every question includes a recommendation.
+
+### The Recommendation Pattern
+
+```
+Question: [What are the options?]
+
+Options:
+A) [First option] — [trade-off summary]
+B) [Second option] — [trade-off summary]
+C) [Third option if applicable] — [trade-off summary]
+
+Recommendation: [Option X] because [concrete reason].
+```
+
+### Good Recommendation Example
+
+```
+Question: How should we handle user session storage?
+
+Options:
+A) JWT tokens — Stateless, scales horizontally without shared storage.
+   Token revocation requires a blocklist (adds complexity).
+
+B) Database sessions — Simple revocation (delete the row).
+   Requires shared database for multi-server setups.
+   Adds a database query on every request.
+
+C) Redis sessions — Fast lookups, built-in TTL for expiry.
+   Requires Redis infrastructure.
+   Good middle ground between stateless and database.
+
+Recommendation: Option A (JWT) because the project uses a stateless
+architecture and does not require immediate token revocation. If
+revocation becomes a requirement later, we can add a Redis blocklist.
+```
+
+### Bad Recommendation Example
+
+```
+Question: How should we handle sessions?
+
+Options:
+A) JWT
+B) Database sessions
+
+It depends on your needs.
+```
+
+This is useless. "It depends" is not a recommendation. Explain the trade-offs and pick one.
+
+### When You Genuinely Cannot Recommend
+
+Sometimes the decision depends on information only the stakeholder has (budget, timeline, team preference). In this case:
+
+```
+Question: Should we build this in-house or use a third-party service?
+
+Options:
+A) Build in-house — Full control, no vendor dependency.
+   Estimated 2 weeks of development.
+
+B) Use [Service X] — Ready immediately. $50/month.
+   Limited customization.
+
+I cannot recommend one because it depends on your budget and timeline
+constraints. If budget is flexible, Option B saves 2 weeks. If vendor
+dependency is a concern, Option A gives full control.
+```
+
+---
+
+## When to Stop Asking
+
+Clarification has diminishing returns. At some point, additional questions delay progress without reducing risk.
+
+### Signals to Stop Asking
+
+**You have enough to write acceptance criteria.** If you can write specific, testable Given/When/Then criteria, you have enough clarity to proceed.
+
+**Questions are getting granular.** "Should the button be blue or green?" is a question that does not affect architecture or correctness. Make a reasonable choice and note it.
+
+**The stakeholder is repeating themselves.** If the answers to new questions are "like I said before," you have already covered the scope.
+
+**Questions are about implementation, not requirements.** "Should I use a for loop or map?" is not a clarification question — it is a code decision. Make it during implementation.
+
+### The Rule of Three
+
+Ask a maximum of three rounds of questions. Each round should have 2-5 questions. After three rounds (6-15 questions total), you should have enough to write the spec. If you still do not, the requirement itself may need to be split into smaller pieces.
+
+**Round 1:** Scope and approach (the big questions).
+**Round 2:** Edge cases and integration (the detailed questions).
+**Round 3:** Testing and remaining ambiguities (cleanup).
+
+### Diminishing Returns Heuristic
+
+```
+Round 1: Resolves ~60% of ambiguity
+Round 2: Resolves ~25% of remaining ambiguity
+Round 3: Resolves ~10% of remaining ambiguity
+Round 4+: Resolves <5% — diminishing returns territory
+```
+
+After three rounds, the remaining ambiguity is small enough to handle with reasonable defaults and a note in the spec.
+
+---
+
+## Anti-Patterns
+
+### Anti-Pattern 1: Asking Too Many Questions
+
+**Symptom:** 15+ questions in a single round. The stakeholder feels interrogated.
+
+**Why it happens:** The AI tries to eliminate all ambiguity at once.
+
+**Fix:** Prioritize. Ask the 3-5 most impactful questions first. The answers will often resolve other questions.
+
+**Example:**
+```
+BAD: 12 questions about the login page including font size,
+     button color, error animation duration, and input padding.
+
+GOOD: 3 questions: What authentication method? What error handling
+      for invalid credentials? Any existing UI components to reuse?
+```
+
+### Anti-Pattern 2: Asking Obvious Questions
+
+**Symptom:** Questions whose answers are already in the codebase or project context.
+
+**Why it happens:** The AI did not read the existing code before asking.
+
+**Fix:** Search the codebase first. If there is an existing auth system using JWT, do not ask "should we use JWT or sessions?" Use JWT.
+
+**Example:**
+```
+BAD: "What testing framework should we use?"
+     (package.json clearly shows vitest)
+
+GOOD: "The project uses vitest. Should the new tests follow the
+       existing mocking pattern in tests/user.test.ts, or is there
+       a reason to use a different approach?"
+```
+
+### Anti-Pattern 3: Not Offering Recommendations
+
+**Symptom:** Every question ends with "what do you think?" without the AI expressing any opinion.
+
+**Why it happens:** The AI tries to be neutral and not impose preferences.
+
+**Fix:** Always recommend. "I recommend Option A because..." Stakeholders can disagree, but they should not have to do all the thinking.
+
+**Example:**
+```
+BAD: "We could use PostgreSQL or MongoDB. Which do you prefer?"
+
+GOOD: "I recommend PostgreSQL because the existing project uses it,
+       the data is relational, and adding MongoDB would introduce a
+       second database technology without clear benefit."
+```
+
+### Anti-Pattern 4: Asking Questions That Do Not Affect the Code
+
+**Symptom:** Questions about business strategy, user demographics, or market positioning.
+
+**Why it happens:** The AI is trained on business analysis data and conflates business questions with technical requirements.
+
+**Fix:** Only ask questions whose answers change the code. "Who is the target user?" does not change the code. "Should the UI support screen readers?" does.
+
+**Example:**
+```
+BAD: "What is the long-term vision for this feature?"
+
+GOOD: "Should this API support versioning now, or is it internal-only
+       with no backward compatibility requirement?"
+```
+
+### Anti-Pattern 5: Re-Asking Answered Questions
+
+**Symptom:** A question that was answered in a previous round is asked again with different wording.
+
+**Why it happens:** Context loss between clarification rounds.
+
+**Fix:** Maintain a clarification log (the `<clarifications>` section of the spec). Check it before each new round of questions.
+
+**Example:**
+```
+BAD: Round 1: "Should users be able to reset their password?"
+     Answer: "Yes, via email link."
+     Round 2: "How should password recovery work?"
+
+GOOD: Round 2 skips this question because it was answered in Round 1.
+```
+
+---
+
+## Putting It All Together: A Spec Phase Example
+
+**Request:** "Add user notifications"
+
+**Round 1: Scope and Approach**
+
+1. "What types of notifications? Email only, in-app only, or both?"
+   - Recommendation: Start with in-app only. Email adds infrastructure complexity. We can add email in a later iteration.
+
+2. "What events trigger notifications? User actions (someone liked your post) or system events (your subscription expires) or both?"
+   - Recommendation: Start with user actions. They are higher value and simpler to implement.
+
+3. "Should notifications be real-time (WebSocket push) or poll-based (check on page load)?"
+   - Recommendation: Poll on page load. The project does not have WebSocket infrastructure. Real-time can be added later without changing the data model.
+
+**Stakeholder answers:** In-app only. User actions only. Poll on page load is fine.
+
+**Round 2: Edge Cases and Integration**
+
+4. "What happens when a user has 1000+ notifications? Should we paginate, auto-archive, or limit?"
+   - Recommendation: Show the 50 most recent. Auto-archive after 30 days. This keeps the UI fast and the database clean.
+
+5. "Should the notification bell show an unread count?"
+   - Recommendation: Yes. It is standard UX and adds minimal implementation effort.
+
+**Stakeholder answers:** 50 most recent with auto-archive. Yes to unread count.
+
+**Round 3: Not needed.** Enough clarity to write acceptance criteria:
+- AC-1: Given a user action, When the action completes, Then a notification is created.
+- AC-2: Given a user with unread notifications, When they load the page, Then the bell shows the unread count.
+- AC-3: Given more than 50 notifications, When the user opens notifications, Then only the 50 most recent are shown.
+
+Two rounds, five questions, clear spec. No assumptions.