Contextual Ambiguity Detector

Contextual Ambiguity Detector

Detects hidden assumptions, undocumented choices, and alternative-path gaps in code. Surfaces where code chose one way without explaining why, making implicit decisions explicit.

Decision Framework

When to Apply

Use when:

• Reviewing code with hardcoded magic numbers or string literals
• Finding conditional logic that assumes user behavior (e.g., "users will always have email")
• Spotting API integrations with assumed response formats
• Detecting UI code with assumed screen sizes or input methods
• Code review where "why this way?" has no documented answer

When NOT to Apply

Don't use when:

• Code is well-documented with ADRs (Architecture Decision Records)
• Configuration is externalized and environment-driven
• Domain rules are formally specified (e.g., regulatory requirements)

Anti-Patterns Detected

Trigger Phrases

• "Review code for assumptions"
• "Check for hardcoded values"
• "Detect hidden choices"
• "Find undocumented decisions"
• "Audit code assumptions"

1. User Behavior Assumptions

Code that assumes how users will interact without fallbacks.

// ASSUMPTION: User always has a name
const displayName = user.firstName + ' ' + user.lastName;

// BETTER: Handle missing data
const displayName = [user.firstName, user.lastName]
  .filter(Boolean)
  .join(' ') || 'Anonymous User';

Triggers:

• Direct property access without null checks
• String concatenation assuming non-empty values
• Date/time calculations assuming timezone
• Form submissions assuming all fields filled

2. Tech Stack Assumptions

Hardcoded dependencies on specific technologies without abstraction.

// ASSUMPTION: Always MySQL
const query = `SELECT * FROM users WHERE id = ${id}`;

// BETTER: Abstracted
const query = db.select('users').where({ id });

Triggers:

• Raw SQL strings
• Browser-specific APIs without feature detection
• OS-specific file paths
• Network assumptions (always online, specific latency)

3. UI Pattern Assumptions

Interface code that assumes specific interaction patterns.

// ASSUMPTION: Desktop mouse interaction
element.addEventListener('click', handler);

// BETTER: Universal interaction
element.addEventListener('click', handler);
element.addEventListener('touchend', handler);
element.setAttribute('role', 'button');
element.setAttribute('tabindex', '0');

Triggers:

• Mouse-only event handlers
• Fixed pixel layouts
• Assumed viewport sizes
• Hover-dependent interactions

4. Data Shape Assumptions

Code that assumes specific data structures without validation.

// ASSUMPTION: Response always has data.users array
const users = response.data.users.map(u => u.name);

// BETTER: Validated access
const users = (response?.data?.users || []).map(u => u?.name || 'Unknown');

Triggers:

• Deep property access without optional chaining
• Array operations without empty checks
• API response usage without schema validation

5. Edge Case Blindspots

Missing handling for boundary conditions.

// BLINDSPOT: Zero, negative, very large quantities
const total = price * quantity;

// BETTER: Validated
const total = price * Math.max(0, Math.min(quantity, MAX_ORDER_QTY));

Triggers:

• Division without zero-check
• Array access without bounds check
• Date math without DST consideration
• File operations without size limits

Detection Rules

Output Format

## Ambiguity Report

### 🔴 Critical (Must Document)
- [file:line] Assumes all users have email addresses
  - Alternative: Support phone-only or anonymous users
  - Decision: Document in ADR-XXX

### 🟡 Warnings (Should Document)  
- [file:line] Hardcoded to PostgreSQL array syntax
  - Alternative: Use parameterized queries
  - Decision: Document in ADR-XXX

### 📝 Suggestions (Consider)
- [file:line] Assumes desktop viewport
  - Alternative: Responsive breakpoints
  - Decision: Document if intentional

Integration with Other Skills

• database-schema-designer: Validate data access assumptions
• authentication-flow-designer: Check identity/permission assumptions
• accessibility-pattern-library: Verify interaction assumptions
• mobile-gesture-handler: Validate touch/mobile assumptions