What AI Can't See: Design Flaws and Missing Requirements

The hardest bugs to find during code review aren't bugs at all. They're things that should be there but aren't. If code is wrong, it's visible when you read it. But if something is missing from the code entirely — something that should be there according to requirements or business logic? That's invisible. It doesn't exist in the diff. AI review tools won't flag it.

Missing Requirements: The Invisible Problem

Here's a PR titled "Implement account deactivation". The code looks correct at first glance:

@PostMapping("/users/{userId}/deactivate")
public ResponseEntity<Void> deactivateUser(
        @PathVariable String userId,
        @AuthenticationPrincipal UserDetails currentUser) {

    if (!currentUser.getUsername().equals(userId)) {
        throw new ForbiddenException("Only the account owner can delete the account.");
    }

    User user = userRepository.findById(userId)
        .orElseThrow(() -> new UserNotFoundException(userId));
    user.setStatus(UserStatus.DEACTIVATED);
    user.setDeactivatedAt(LocalDateTime.now());
    userRepository.save(user);

    return ResponseEntity.noContent().build();
}

Authentication check exists. Exception handling is present. Status changes are properly saved. An AI review tool would pass this code. But a good human reviewer asks: What else is connected to this user that needs to be handled during deactivation?

The questions flow:

• Active Subscription: If this user has a paid subscription, will it auto-cancel when the account is deactivated? What's the refund policy for the remaining subscription period? How do we handle pro-rated refunds?
• Orders in Progress: Are there orders in progress or pending fulfillment? Do they get canceled? Do customers get notified? Does inventory need to be restored?
• Credit/Points Balance: The user has accumulated points or credit. Is that balance forfeited? Refunded? Transferred to another account?
• Relationships with Other Users: Are there shared documents? Team memberships? Ongoing transactions with other users? What happens to collaborative access?
• Data Retention & Privacy: Are we legally required to retain data for specific periods? What about GDPR's "right to be forgotten"?
• Notifications: Are customers notified of account deactivation? Do related users get notifications?

None of this is in the code. It's not a bug — it's missing functionality that the planning document and business requirements specify.

How Reviewers See "What's Not There"

Some questions are particularly effective at revealing missing requirements:

• "If this data changes, what else is connected?" State changes in one entity often affect related entities. Account deactivation cascades through subscriptions, orders, team memberships.
• "Is there rollback if it fails?" Multi-step operations need failure handling. If email notification fails after account is deactivated, can we rollback the deactivation?
• "Are users notified?" Status changes that users should know about need notification mechanisms.
• "Is this reversible?" Should account deactivation be recoverable? Is there a grace period before permanent deletion?
• "What are the legal implications?" GDPR, SOX, HIPAA, industry regulations — these create requirements that aren't obvious from code.

Architectural Problems: Patterns in Individual PRs

Architectural issues usually don't appear in one PR — they appear as patterns. But the first signal shows up in individual PRs. Catching these early prevents major refactoring later.

Signal 1: Layer Boundary Violations

@RestController
public class OrderController {
    private final OrderRepository orderRepository;

    @GetMapping("/orders/{id}")
    public Order getOrder(@PathVariable String id) {
        // Controller directly calls Repository, skipping Service
        return orderRepository.findById(id);
    }
}

Architecture says: Controller → Service → Repository. When Controllers skip layers, every future addition (caching, transactions, security) requires modifying Controllers too.

Signal 2: Circular Dependencies

// userService.ts
class UserService {
  async deleteUser(userId) {
    await this.orderService.cancelAllOrders(userId);
    await this.userRepository.delete(userId);
  }
}

// orderService.ts
class OrderService {
  async getOrderWithUser(orderId) {
    const user = await this.userService.findById(orderId.userId);
    return { order, user };
  }
}

UserService knows OrderService. OrderService knows UserService. They're circularly dependent. Unit testing becomes impossible. Deployment is tightly coupled.

Solution: Event-based architecture where UserService publishes UserDeletedEvent and OrderService subscribes.

Signal 3: Business Logic in Wrong Layer

Discount calculations inside React components. Date formatting repeated across the codebase. Authorization checks in Controllers.

When business logic spreads, it becomes duplication, harder to test, and risky to change.

Business Logic: The Hardest to Verify

A business logic bug is code that executes perfectly but does the wrong thing.

function calculateDiscount(subtotal, coupon, member) {
  return subtotal - coupon - memberDiscount;  // Applies both discounts
}

The code looks right. But if your discount policy is "apply the larger discount only, never both," this is wrong.

Verification approach: Plug in numbers and calculate by hand:

Order: $100
Coupon: $10
Member discount: $15

Current code: $100 - $10 - $15 = $75
Policy says: $100 - $15 = $85 (larger discount only)

Now the bug is visible. But you have to know the policy to see it.

The Reviewer's Preparation

To find omissions and business logic errors, reviewers must understand the context before reading code:

1. Read the PR description carefully — what does the author claim was changed?
2. Read the planning document or requirements (if linked) — what does the business actually need?
3. Ask: "Are all requirements visible in the code?"
4. Check for related systems and dependencies — what cascading changes are needed?
5. Only then, read the code itself

Many reviewers skip straight to code. That's when missing requirements slip through.

Involving Domain Experts

For complex business logic, developer review might not be sufficient. Include domain experts:

• Finance logic: Include a financial analyst who knows the business rules
• Medical code: Include a domain expert in healthcare who knows compliance requirements
• Legal compliance: Include compliance officer or lawyer
• Product features: Include product manager or business analyst
• Security: Include security engineer for new endpoints or data handling

These experts see requirements and edge cases that pure technical code review misses. They catch missing validations, missing notifications, missing compliance checks, and missing business logic.

Cascading Effects: Thinking Beyond One PR

Good reviewers think about cascading effects. When you deactivate a user account, what else breaks or needs updating?

User deactivated
  ↓
Subscription needs to cancel (refund policy?)
  ↓
Active orders need to be canceled (customer notification?)
  ↓
Team memberships need to be removed (other team members notified?)
  ↓
API tokens need to be revoked (cached tokens invalidated?)
  ↓
Shared documents need access revocation (collaborators notified?)
  ↓
Financial records need to be archived (audit trail preserved?)
  ↓
Support tickets tied to this user (reassign to another agent?)

A single user deactivation can trigger 7+ systems. Code review only for the immediate user deactivation endpoint misses all of these.

The Questions That Reveal Omissions

"What happens tomorrow?" A feature works today. What happens when:

• The business needs to change the policy?
• Someone joins the team who doesn't know the decision?
• The external system changes behavior?
• Data grows 100x larger?

"What fails silently?" Problems that don't throw exceptions or show errors:

• Email not sent but no error logged
• Notification queue backed up but endpoint still works
• Cache expired but fallback is broken
• Database connection pooled but connections never close

"Who else cares?" Dependencies on this code:

• Other teams depending on this API
• Analytics systems waiting for events
• External partners integrating with your API
• Background jobs scheduled based on state changes

The Reviewer Preparation Checklist

Before reviewing complex business logic, prepare:

• Read the issue/ticket linked in the PR
• Read any PRDs (Product Requirements Documents)
• Understand who the stakeholders are
• Check related PRs or issues for context
• Know the regulatory/compliance context if applicable
• Understand what systems depend on this code
• Review any planning documents or design docs

This preparation takes 10-15 minutes but prevents missing requirements that code review alone would catch.

Examples of Invisible Problems

Invisible Problem 1: Incorrect Financial Logic

function calculateDiscount(cartTotal, couponPercent, tierDiscount) {
  return cartTotal * (1 - couponPercent) * (1 - tierDiscount);
}

// Code works. But if policy is "apply largest discount only":
// $100 * 0.9 (10% coupon) * 0.95 (5% tier) = $85.50
// Should be $90 (10% is larger)

The code is syntactically perfect but semantically wrong. You find it by understanding business rules, not by code inspection.

Invisible Problem 2: Missing Compliance

Code complies with technical standards but breaks regulatory requirements. A PR doesn't mention GDPR requirements, SOX compliance, HIPAA data residency, or PCI DSS encryption. These requirements aren't in code — they're in external documents.

Invisible Problem 3: Broken Workflows

A workflow might be technically correct but missing a step users need. Example: Account deactivation code works, but doesn't notify the user or handle subscriptions. The workflow is incomplete.

AI's Blind Spots, Your Strength

AI can't read planning documents. AI doesn't know business policies or regulatory requirements. AI doesn't track what's connected to what in your domain. AI doesn't understand historical decisions or why legacy patterns exist.

These are exactly what experienced human reviewers see and understand.

In your next review, don't stop at "the code works." Ask: "What should happen that isn't in this code?" That question catches missing requirements, missing error handling, missing notifications, missing cascading updates, and missing compliance checks that could become expensive problems later.

Developing Domain Expertise

The most valuable reviewers aren't the most senior developers — they're the ones who understand the business domain deeply. They know:

• How users actually use the system
• What edge cases happen in production
• What business rules are non-negotiable
• What regulatory requirements apply
• What systems depend on this code
• What mistakes have happened before

This domain expertise is built over time through reviewing many PRs in the same domain. It's irreplaceable and it's what makes experienced reviewers valuable.

• Next article: Building a Strong Code Review Culture in the Age of AI