Stop Reviewing Code You Don't Understand Yet — Turn AI Into a Rigorous First-Pass Reviewer That Cites Evidence, Not Style

A complete review should answer:

1. What is the change intended to accomplish?
2. Does the implementation match the requirement?
3. What behavior changed?
4. What behavior may have changed unintentionally?
5. Are error conditions handled correctly?
6. Are inputs validated?
7. Are permissions and authorization enforced?
8. Are sensitive values protected?
9. Are outputs and public interfaces stable?
10. Are concurrency and state changes safe?
11. Are dependencies used appropriately?
12. Are tests sufficient?
13. Is the code maintainable?
14. Is the change observable in production?
15. Can the change be rolled back safely?
16. Are there edge cases not covered?
17. Is the change appropriately scoped?
18. Is the code ready for human approval?

Requirement

Add an endpoint that allows an authenticated user to update their display name.

Requirements:

• User must be authenticated.
• User may update only their own profile.
• Display name must be between 1 and 100 characters.
• Leading and trailing whitespace should be removed.
• The endpoint should return the updated profile.
• Changes should be audited.

Example Code

app.put('/api/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) {
    return res.status(404).json({
      error: 'User not found'
    });
  }
  user.displayName = req.body.displayName;
  await db.users.save(user);
  return res.json(user);
});

The implementation updates a user record identified by a route parameter and returns the saved object.

It does not fully satisfy the requirement because:

• Authentication is not enforced in the shown handler.
• Authorization does not restrict updates to the current user.
• Input validation is missing.
• Whitespace normalization is missing.
• Audit logging is missing.
• The full user object may expose fields not intended for API output.

AI-CR-001 — Missing Ownership Authorization

Severity: Critical
Confidence: Confirmed
Category: Security

Affected Code:

const user = await db.users.findById(req.params.id);

Evidence: The handler selects the target account using a caller-controlled route parameter and does not compare it with the authenticated user's identifier.

Why It Matters: Any caller who can reach this endpoint may be able to update another user's profile by changing the route parameter.

Failure Scenario: A user sends:

PUT /api/users/another-user-id

and changes another account's display name.

Recommended Remediation: Use the authenticated identity as the target identifier or explicitly compare the requested identifier with the authenticated user.

Example:

if (req.params.id !== req.auth.userId) {
  return res.status(403).json({
    error: 'Forbidden'
  });
}

A stronger design may remove the route identifier entirely:

PUT /api/users/me

Recommended Test: Verify that an authenticated user receives 403 when attempting to update another user's record.

AI-CR-002 — Missing Input Validation

Severity: High
Confidence: Confirmed
Category: Functional Correctness

Affected Code:

user.displayName = req.body.displayName;

Evidence: The value is assigned without verifying its type, length, or normalized content.

Why It Matters: The endpoint may store:

• Null values
• Empty strings
• Strings longer than 100 characters
• Non-string values
• Whitespace-only values

Recommended Remediation: Validate the type, trim the value, and enforce the length requirement after trimming.

if (typeof req.body.displayName !== 'string') {
  return res.status(400).json({
    error: 'displayName must be a string'
  });
}
const displayName = req.body.displayName.trim();
if (displayName.length < 1 || displayName.length > 100) {
  return res.status(400).json({
    error: 'displayName must contain 1 to 100 characters'
  });
}

Recommended Tests:

• Empty string
• Whitespace-only string
• 1-character string
• 100-character string
• 101-character string
• Null
• Number
• Missing property

AI-CR-003 — Missing Audit Event

Severity: High
Confidence: Confirmed
Category: Operations

Evidence: The requirement states that changes must be audited, but the handler does not create an audit event.

Why It Matters: The organization cannot reliably determine:

• Who made the change
• Which account changed
• When the change occurred
• What the previous value was
• What the new value is

Recommended Remediation: Record an audit event containing:

• Acting user identifier
• Target user identifier
• Operation
• Previous value
• New value
• Timestamp
• Request or correlation identifier

Sensitive values should be minimized according to audit policy.

Recommended Test: Verify that one audit event is created after a successful update and no success audit event is written when persistence fails.

AI-CR-004 — Raw Persistence Object Returned

Severity: Medium
Confidence: High
Category: Security

Affected Code:

return res.json(user);

Evidence: The handler returns the full database object.

Why It Matters: The object may contain fields not intended for external disclosure, such as:

• Internal identifiers
• Permission data
• Account status
• Authentication metadata
• Audit fields
• Password hashes
• Recovery settings

Recommended Remediation: Return an explicit API response model.

return res.json({
  id: user.id,
  displayName: user.displayName
});

Recommended Test: Verify that the response contains only the documented profile fields.

app.put(
  '/api/users/me',
  requireAuthentication,
  async (req, res, next) => {
    try {
      if (typeof req.body.displayName !== 'string') {
        return res.status(400).json({
          error: 'displayName must be a string'
        });
      }
      const displayName = req.body.displayName.trim();
      if (displayName.length < 1 || displayName.length > 100) {
        return res.status(400).json({
          error: 'displayName must contain 1 to 100 characters'
        });
      }
      const user = await db.users.findById(req.auth.userId);
      if (!user) {
        return res.status(404).json({
          error: 'User not found'
        });
      }
      const previousDisplayName = user.displayName;
      user.displayName = displayName;
      await db.transaction(async transaction => {
        await db.users.save(user, {
          transaction
        });
        await db.auditEvents.create(
          {
            actorUserId: req.auth.userId,
            targetUserId: user.id,
            action: 'UserDisplayNameUpdated',
            previousValue: previousDisplayName,
            newValue: displayName,
            requestId: req.id,
            occurredAt: new Date()
          },
          {
            transaction
          }
        );
      });
      return res.json({
        id: user.id,
        displayName: user.displayName
      });
    } catch (error) {
      next(error);
    }
  });

The exact transaction, authentication, audit, and error-handling patterns should follow the application's established architecture.

Teams may track:

• Defects found before merge
• Defects escaped to production
• Review turnaround time
• Average pull-request size
• Findings by severity
• False-positive rate
• Repeated defect categories
• Test gaps identified
• Security findings identified
• AI comments accepted
• AI comments rejected
• Review coverage by repository

Metrics should improve the process, not rank individual developers.

Define:

• Approved AI platforms
• Code-classification rules
• Prohibited data
• Required human reviewers
• Repositories eligible for AI review
• Logging and retention requirements
• Whether AI comments may be posted automatically
• Severity thresholds
• False-positive handling
• Escalation process
• Audit requirements
• Model-change review
• Prompt ownership
• Periodic quality evaluation