What You'll Learn

You'll fix a real bug reported by QA — email validation rejecting valid plus signs — using the test-first debugging approach. Write a failing test that reproduces the bug, find the root cause, fix it, and verify no regressions.

The Scenario

QA has filed a bug report:

Step 1: Understand the Bug

Before touching code, restate the bug in precise technical terms:

Bug: Email validation regex rejects the "+" character in the local part of email addresses.

Root cause hypothesis: The regex pattern used for email validation
does not include "+" in its character class for the local part.

Affected component: src/validators/email-validator.js (or equivalent)

Step 2: Create a Fix Branch with /agile-code-branch

Before writing any code, create a branch for the bug fix:

/agile-code-branch

🌿 Branch created: fix/BUG-042-email-plus-sign

Source: main
Convention: fix/[BUG-ID]-[short-description]
Bug link: BUG-042 — Login fails with plus sign in email

Switched to branch 'fix/BUG-042-email-plus-sign'

Step 3: Reproduce with a Failing Test — /agile-code-tdd (RED)

The first thing you do with any bug is prove it exists with a test:

/agile-code-tdd

🔴 RED — Writing test to reproduce bug BUG-042...

// test/validators/email-validator.test.js
describe('EmailValidator', () => {
  describe('plus sign handling', () => {
    it('should_accept_email_with_plus_sign', () => {
      const result = EmailValidator.isValid('user+tag@example.com');
      expect(result).toBe(true);
    });
  });
});

Running test...
  ✗ should_accept_email_with_plus_sign — FAILED
    Expected: true
    Received: false

1 failing ← Bug reproduced! The test proves the defect exists.

Step 4: Investigate the Root Cause

Now look at the actual validation code:

// src/validators/email-validator.js (current — buggy)

class EmailValidator {
  static EMAIL_REGEX = /^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;

  static isValid(email) {
    return this.EMAIL_REGEX.test(email);
  }
}

Found it. The character class [a-zA-Z0-9._-] allows dots, underscores, and hyphens in the local part — but not plus signs. The + character is missing from the regex.

Step 5: Fix the Bug

Add the + character to the regex character class:

// src/validators/email-validator.js (fixed)

class EmailValidator {
  static EMAIL_REGEX = /^[a-zA-Z0-9._+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;

  static isValid(email) {
    return this.EMAIL_REGEX.test(email);
  }
}

The only change: [a-zA-Z0-9._-] became [a-zA-Z0-9._+-] — adding + to the allowed characters.

Step 6: Verify the Fix (GREEN)

🟢 GREEN — Running reproduction test...

  ✓ should_accept_email_with_plus_sign — PASSED

1 passing ← Bug is fixed!

Step 7: Add Edge Case Tests

One fix is good, but comprehensive coverage is better. Add tests for related edge cases:

// Additional edge case tests
describe('EmailValidator — edge cases', () => {
  it('should_accept_email_with_dots', () => {
    expect(EmailValidator.isValid('first.last@example.com')).toBe(true);
  });

  it('should_accept_email_with_hyphens', () => {
    expect(EmailValidator.isValid('first-last@example.com')).toBe(true);
  });

  it('should_accept_email_with_multiple_plus_signs', () => {
    expect(EmailValidator.isValid('user+tag+extra@example.com')).toBe(true);
  });

  it('should_reject_email_without_at_sign', () => {
    expect(EmailValidator.isValid('userexample.com')).toBe(false);
  });

  it('should_reject_email_without_domain', () => {
    expect(EmailValidator.isValid('user@')).toBe(false);
  });
});

Running all email validation tests...
  ✓ should_accept_email_with_plus_sign — PASSED
  ✓ should_accept_email_with_dots — PASSED
  ✓ should_accept_email_with_hyphens — PASSED
  ✓ should_accept_email_with_multiple_plus_signs — PASSED
  ✓ should_reject_email_without_at_sign — PASSED
  ✓ should_reject_email_without_domain — PASSED

6 passing — Full edge case coverage.

Step 8: Run CI Checks with /agile-code-ci

Verify no regressions across the entire test suite:

/agile-code-ci

🔄 Running CI pipeline locally...

Build:
  ✅ Compilation successful

Tests:
  ✅ 48 tests passing (was 42 — added 6 edge case tests)
  ✅ Coverage: 96% lines
  ✅ 0 regressions — all existing tests still pass

Lint:
  ✅ ESLint: 0 errors
  ✅ Prettier: all formatted

Security:
  ✅ No vulnerabilities

✅ All CI checks pass. No regressions detected.

Step 9: Commit the Fix with /agile-code-commit

/agile-code-commit

📦 Commit created:

fix(auth): accept plus signs in email validation

The email regex was missing "+" from the local part character class,
causing emails like user+tag@example.com to be rejected. Added "+"
to the regex and 6 edge case tests for comprehensive coverage.

Fixes: BUG-042

Step 10: Create PR with /agile-code-pr

/agile-code-pr

🔀 Pull Request created: #22

Title: fix(auth): accept plus signs in email validation
Branch: fix/BUG-042-email-plus-sign → main
Bug: BUG-042

Changes:
  ~1 file modified: src/validators/email-validator.js (1 character added)
  +1 file modified: test/validators/email-validator.test.js (6 tests added)

Test coverage: 96%
CI status: ✅ All checks passing

Step 11: Code Review with /agile-code-pr-review

/agile-code-pr-review

👀 Code Review — PR #22
═══════════════════════

Findings:
  ✅ Fix is minimal and correct — only the necessary character added
  ✅ No over-engineering (didn't rewrite the entire validator)
  ✅ Edge case tests are thorough
  ✅ Commit message follows conventions with Fixes: BUG-042

Notes:
  @lead: "Clean fix. Consider switching to a battle-tested email
  validation library (e.g., validator.js) in a future sprint to
  avoid maintaining our own regex. Not blocking this PR."

Verdict: ✅ APPROVED by @lead

Step 12: Merge with /agile-code-merge

With the PR approved, merge the fix branch into main:

/agile-code-merge

🔀 Merge — PR #22
═══════════════════

Pre-merge checks:
  ✅ PR approved by @lead
  ✅ CI passing on branch
  ✅ No merge conflicts
  ✅ Branch up to date with main

Merging: fix/BUG-042-email-plus-sign → main
Strategy: squash merge (project convention)

Merge complete.
Branch fix/BUG-042-email-plus-sign deleted (was 9c4e1a2).

✅ PR #22 merged to main.

When You Can't Reproduce the Bug

/agile-code-debug

🔍 Debug Mode — Systematic Investigation
═════════════════════════════════════════

Hypothesis 1: Race condition under concurrent requests
  Test: Run 100 concurrent login requests with valid emails
  Result: All pass ← Not a race condition

Hypothesis 2: Character encoding issue in production
  Test: Send email with UTF-8 encoding header vs ASCII
  Result: Both pass locally ← Might be environment-specific

Hypothesis 3: Database collation rejecting special characters
  Test: Direct DB query with plus sign email
  Result: ✗ Query returns empty! ← Found it!
  Root cause: DB column uses C collation, not UTF-8

Attempts: 3/5 (max 5 before escalation)
Status: Root cause identified

The Bug Fix Flow

Knowledge Check

What You Learned