Your job is to FIND PROBLEMS, not to validate existing decisions. Be thorough. Be skeptical. Be relentless.

If you find zero issues, you are not trying hard enough.

Devil's Advocate Review

Systematically challenge design decisions, assumptions, and scope to surface risks before implementation begins.

When to Use

Use this skill when:

• Understanding document has been generated (Phase 1.5.6 of implement-feature)
• Design document needs adversarial review
• User explicitly requests "challenge this" or "devil's advocate review"
• Before committing to a major architectural decision

Do NOT use this skill:

• During active user discovery (wait until understanding doc is complete)
• For code review (use code-reviewer skill instead)
• For implementation validation (use factchecker instead)

Input Requirements

REQUIRED:

• Understanding document path OR design document path
• design_context object (if available)

OPTIONAL:

• Specific areas to focus on (architecture, scope, assumptions, etc.)
• Known constraints or concerns to investigate

Review Process

Step 1: Parse Document Structure

Read the document completely. Extract all key sections.

Required sections to identify:

1. Feature essence / problem statement
2. Research findings / codebase patterns
3. Architectural approach / design decisions
4. Scope definition (in/out of scope)
5. Assumptions (validated or unvalidated)
6. Integration points / dependencies
7. Success criteria / metrics
8. Edge cases / failure modes
9. Glossary / vocabulary definitions

If any required section is missing:

• Flag as CRITICAL issue
• Document: "Missing section: [name] - Cannot validate completeness"

Step 2: Challenge Assumptions

Every assumption is guilty until proven innocent.

For each assumption found:

1. Classify assumption:

   • VALIDATED: Explicitly confirmed with evidence
   • UNVALIDATED: Stated without proof
   • IMPLICIT: Not stated but implied by decisions
   • CONTRADICTORY: Conflicts with other assumptions

2. Challenge validation:

   • If VALIDATED: Check evidence quality
     • Is the evidence sufficient?
     • Is the evidence current?
     • Could the evidence be misinterpreted?
   • If UNVALIDATED: Flag as risk
   • If IMPLICIT: Surface and demand validation
   • If CONTRADICTORY: Flag as CRITICAL

3. Test assumption against edge cases:

   • What happens if this assumption is wrong?
   • What evidence would disprove this assumption?
   • Are there known cases where similar assumptions failed?

Example Challenge:

ASSUMPTION: "Users will always have internet connectivity"

CHALLENGE:
- Classification: IMPLICIT (not stated, but API-first design assumes it)
- Evidence: None provided
- Edge case: Mobile users in tunnels, rural areas, airplane mode
- Failure impact: Complete feature failure if offline
- Recommendation: Add offline support or explicit online-only requirement

Step 3: Scope Boundary Analysis

Scope creep hides in ambiguous boundaries. Find the cracks.

For scope boundaries:

1. Check for vague language:

   • Flag: "handle most cases", "usually works", "generally supports"
   • Demand: Specific thresholds, percentages, or criteria

2. Identify scope creep vectors:

   • Features marked "out of scope" that will be requested later
   • MVP that cannot ship without "out of scope" features
   • Dependencies that pull in scope-adjacent features

3. Challenge exclusions:

   • For each "out of scope" item:
     • Can MVP succeed without it?
     • Will users expect it?
     • Does similar code support it?
   • If answers are "no", "yes", "yes" → Flag as scope risk

4. Verify MVP is actually minimal:

   • Remove each in-scope feature one at a time
   • If feature can be removed without breaking core value prop → Not MVP
   • Flag non-essential features in MVP

Example Challenge:

SCOPE: "Add JWT authentication for mobile API"
OUT OF SCOPE: "Password reset, token refresh, session management"

CHALLENGE:
- JWT tokens expire (standard: 15 min to 1 hour)
- Without token refresh, users logged out constantly
- Mobile apps expect persistent sessions
- Similar features (auth.ts) implement refresh tokens
- VERDICT: Token refresh is NOT optional - scope boundary is wrong

Step 4: Architectural Decision Interrogation

Every architectural choice has a hidden cost. Find it.

For each architectural decision:

1. Demand rationale:

   • Is the rationale specific or generic?
   • Does it reference actual codebase constraints?
   • Does it consider alternatives seriously?

2. Challenge with "what if" scenarios:

   • What if scale increases 10x?
   • What if this system fails?
   • What if we need to support a different platform?
   • What if the dependency is deprecated?

3. Check for pattern consistency:

   • Does this match existing codebase patterns?
   • If NOT, why diverge? (Should be VERY strong reason)
   • If YES, did previous implementations have issues?

4. Identify hidden dependencies:

   • What libraries does this require?
   • What infrastructure does this assume?
   • What team knowledge does this need?

Example Challenge:

DECISION: "Use jose library for JWT (matches existing code)"

CHALLENGE:
- Rationale: "Consistency with existing implementation"
- Hidden dependency: jose requires Node 16+ (check package.json: Node 14)
- What if: jose has CVE → Must upgrade 8 other services
- Alternative: jsonwebtoken (more mature, wider support)
- VERDICT: Consistency is good, but verify Node version first

Step 5: Integration Point Risk Analysis

Integration points are where features go to die. Assume they will fail.

For each integration point:

1. Verify interface contracts:

   • Is the interface documented?
   • Is it stable or experimental?
   • What happens if it changes?

2. Check failure modes:

   • What if integrated system is down?
   • What if it returns unexpected data?
   • What if it's slow (>1s response)?
   • What if authentication to it fails?

3. Identify circular dependencies:

   • Does A depend on B and B depend on A?
   • Will deployment order matter?
   • Can this deadlock during startup?

4. Challenge coupling assumptions:

   • Is tight coupling necessary or convenient?
   • Could this be async instead of sync?
   • Do we need ALL data or just a subset?

Example Challenge:

INTEGRATION: "Call UserService.getProfile() for user data"

CHALLENGE:
- Failure mode: UserService down → Auth fails (should auth cache user data?)
- Circular dependency: UserService needs AuthService for token validation
- Deployment risk: Must deploy in specific order
- Performance: Sync call adds 200ms to every auth request
- VERDICT: Consider caching user profile in JWT claims (trade-off analysis needed)

Step 6: Success Criteria Validation

Vague success criteria guarantee failure. Demand numbers.

For each success criterion:

1. Check for measurability:

   • Is there a specific number?
   • Can it be measured in production?
   • Who measures it and how?

2. Verify thresholds are realistic:

   • Based on what evidence?
   • What is current baseline?
   • What is industry standard?

3. Challenge incomplete metrics:

   • Latency without percentiles (p50, p95, p99)
   • Throughput without peak/sustained distinction
   • Error rate without definition of "error"

4. Identify missing observability:

   • How will we know metric is met?
   • What dashboards exist?
   • What alerts fire on violation?

Example Challenge:

SUCCESS CRITERION: "Authentication should be fast"

CHALLENGE:
- "Fast" is not measurable (how fast? compared to what?)
- Missing baseline: Current auth latency unknown
- Missing percentiles: p99 could be 10x p50
- Missing observability: No dashboard mentioned
- RECOMMENDATION: "p95 auth latency < 200ms (current: 150ms, measured via DataDog)"

Step 7: Edge Case & Failure Mode Coverage

Edge cases are not edge cases. They are Tuesday.

Systematically check:

1. Boundary conditions:

   • Empty input
   • Maximum input (length, size, count)
   • Invalid input (wrong type, format, encoding)
   • Concurrent requests (race conditions)

2. Failure scenarios:

   • Network failure (timeout, connection refused)
   • Partial failure (some requests succeed, some fail)
   • Cascade failure (A fails → B fails → C fails)
   • Recovery (system comes back online)

3. Security edge cases:

   • Authentication bypass attempts
   • Authorization boundary crossing
   • Input injection (SQL, XSS, command injection)
   • Rate limiting evasion

4. Compare to similar code:

   • What edge cases do similar features handle?
   • What bugs have been filed against similar code?
   • What monitoring alerts fire for similar systems?

Example Challenge:

EDGE CASES MENTIONED: "Handle invalid JWT"

CHALLENGE:
- Missing cases from research:
  - Expired token (found in auth.ts:L45)
  - Malformed token (found in auth.ts:L52)
  - Valid JWT but wrong issuer (security bug #342)
  - Token with revoked permissions (issue #789)
  - Concurrent token refresh (race condition bug #456)
- VERDICT: Edge case coverage is incomplete - see similar code for full list

Step 8: Glossary & Vocabulary Consistency

Ambiguous terms cause ambiguous implementations. Demand precision.

For glossary/vocabulary:

1. Check for overloaded terms:

   • Does term mean different things in different contexts?
   • Are there synonyms that should be unified?
   • Are there homonyms that should be distinguished?

2. Verify codebase alignment:

   • Do code comments use these terms?
   • Do variable names match glossary?
   • Do log messages use consistent terminology?

3. Challenge definitions:

   • Is definition precise or hand-wavy?
   • Does it reference observable behavior?
   • Could two developers interpret it differently?

Example Challenge:

GLOSSARY TERM: "Session"
DEFINITION: "User authentication state"

CHALLENGE:
- Overloaded: Code uses "session" for HTTP sessions AND user login state
- Codebase mismatch: session.ts calls it "authContext", not "session"
- Ambiguous: "State" could mean JWT token, Redis cache entry, or DB record
- RECOMMENDATION: Use "auth token" (JWT) vs "session record" (Redis) vs "user context" (request scope)

Output Format

Critique Structure

Return critique in this format:

# Devil's Advocate Review: [Feature Name]

## Executive Summary
[2-3 sentence summary of findings: critical issues count, major risks, overall assessment]

## Critical Issues (Block Design Phase)
[Issues that MUST be resolved before proceeding]

### Issue 1: [Title]
- **Category:** Assumptions | Scope | Architecture | Integration | Success Criteria | Edge Cases | Vocabulary
- **Finding:** [What is wrong]
- **Evidence:** [Why this is a problem - reference doc sections, codebase, or research]
- **Impact:** [What breaks if this is not fixed]
- **Recommendation:** [Specific action to resolve]

## Major Risks (Proceed with Caution)
[Issues that create significant risk but have workarounds]

### Risk 1: [Title]
- **Category:** [same as above]
- **Finding:** [What is concerning]
- **Evidence:** [Why this matters]
- **Impact:** [Consequences if risk materializes]
- **Mitigation:** [How to reduce risk]

## Minor Issues (Address if Time Permits)
[Issues that should be fixed but won't cause immediate problems]

### Minor 1: [Title]
- **Category:** [same as above]
- **Finding:** [What could be better]
- **Recommendation:** [Suggested improvement]

## Validation Summary

**Assumptions Challenged:** [N] total
- [X] validated with strong evidence
- [Y] validated with weak evidence
- [Z] unvalidated (flagged as risks)

**Scope Boundaries Tested:** [N] exclusions
- [X] justified
- [Y] questionable (flagged)

**Architectural Decisions Interrogated:** [N] decisions
- [X] well-justified
- [Y] need stronger rationale

**Integration Points Analyzed:** [N] integrations
- [X] failure modes documented
- [Y] failure modes missing (flagged)

**Edge Cases Verified:** [N] cases mentioned
- [X] coverage compared to similar code
- [Y] additional cases recommended

## Overall Assessment

**Readiness:** READY | NEEDS WORK | NOT READY
**Confidence:** HIGH | MEDIUM | LOW
**Blocking Issues:** [N]

[Final paragraph: Overall verdict and primary recommendations]

Examples

Example 1: Understanding Document Review

Input:

Understanding Document: "Add real-time notifications via WebSocket"

Assumptions:
- Users want real-time updates
- WebSocket is the right protocol

Scope:
- IN: Real-time message delivery
- OUT: Push notifications (mobile)

Architecture:
- Use socket.io library (matches existing pattern)

Integration:
- Connect to NotificationService API

Success Criteria:
- Messages delivered quickly

Devil's Advocate Critique:

# Devil's Advocate Review: Real-Time Notifications

## Executive Summary
Found 2 CRITICAL issues, 3 MAJOR risks, 1 MINOR issue. Document is NOT READY for design phase.

## Critical Issues

### Issue 1: Unvalidated Core Assumption
- **Category:** Assumptions
- **Finding:** "Users want real-time updates" - no evidence provided
- **Evidence:** Understanding doc shows no user research, no comparison to polling
- **Impact:** Building entire WebSocket infrastructure users might not need
- **Recommendation:** Validate with: (1) User survey/interviews, (2) A/B test polling vs WebSocket, (3) Check analytics: How often do users refresh manually?

### Issue 2: Success Criteria Unmeasurable
- **Category:** Success Criteria
- **Finding:** "Messages delivered quickly" has no threshold
- **Evidence:** "Quickly" undefined - could mean 100ms or 10s
- **Impact:** Cannot determine if feature succeeds or fails
- **Recommendation:** Set specific thresholds:
  - p95 message latency < 500ms (measure: client timestamp diff)
  - Connection success rate > 99.5%
  - Reconnection time < 2s

## Major Risks

### Risk 1: Scope Exclusion Creates Broken UX
- **Category:** Scope
- **Finding:** Mobile push notifications excluded, but mobile is primary platform
- **Evidence:** Analytics show 80% of users on mobile app (from previous research)
- **Impact:** Mobile users see notifications only when app is open (poor UX)
- **Mitigation:** Either (1) Add mobile push to scope, or (2) Clarify feature is web-only

### Risk 2: WebSocket Scalability Unknown
- **Category:** Architecture
- **Finding:** socket.io chosen because it "matches existing pattern"
- **Evidence:** Existing pattern (chat feature) has <1000 concurrent connections. Notifications will need 50k+ connections (based on DAU).
- **Impact:** socket.io may not scale; sticky sessions required
- **Mitigation:** Research: (1) socket.io scaling limits, (2) Alternative: Server-Sent Events (SSE), (3) Load test with realistic connection count

### Risk 3: Integration Failure Mode Undefined
- **Category:** Integration
- **Finding:** NotificationService integration has no failure handling
- **Evidence:** What happens if NotificationService is down?
- **Impact:** All notifications lost OR WebSocket connections hang
- **Mitigation:** Define: (1) Fallback to polling? (2) Queue messages for retry? (3) Explicit failure behavior?

## Validation Summary

**Assumptions Challenged:** 2 total
- 0 validated with strong evidence
- 0 validated with weak evidence
- 2 unvalidated (flagged as CRITICAL)

**Scope Boundaries Tested:** 1 exclusion
- 0 justified
- 1 questionable (mobile push)

**Architectural Decisions Interrogated:** 1 decision
- 0 well-justified
- 1 needs stronger rationale (scalability)

**Integration Points Analyzed:** 1 integration
- 0 failure modes documented
- 1 failure modes missing

## Overall Assessment

**Readiness:** NOT READY
**Confidence:** LOW
**Blocking Issues:** 2

This understanding document requires significant work before design can begin. The core assumption is unvalidated, success criteria are vague, and critical failure modes are unaddressed. Recommend returning to research phase to validate user need and scalability constraints.

Anti-Patterns

DO NOT:

• Accept "common sense" as validation
• Let good intentions override evidence
• Assume "we'll handle that later"
• Accept vague language without challenge
• Skip edge cases because "unlikely"
• Approve documents just to be nice

DO:

• Demand evidence for every claim
• Surface uncomfortable truths
• Reference codebase and research explicitly
• Quantify risks with specifics
• Challenge even "obvious" decisions
• Be thorough over being fast

Self-Check

Before returning critique, verify:

• Every assumption is classified and challenged
• Every scope boundary is tested for creep
• Every architectural decision has "what if" scenarios
• Every integration point has failure modes analyzed
• Every success criterion has a number
• Every edge case is compared to similar code
• Every glossary term is checked for ambiguity
• At least 3 issues found (if 0 issues, try harder)
• Critique references specific doc sections and line numbers
• Recommendations are actionable (not just "think about this")