Resume Bullet Extraction

"Your resume isn't a job description. It's a highlight reel of impact."

Purpose

Transform completed work into powerful resume bullet points that demonstrate value and technical competence.

The Bullet Formula

[Strong Action Verb] + [What You Did] + [Technical Context] + [Impact/Result]

Components

Strong Action Verbs

Building/Creating

• Engineered
• Architected
• Developed
• Implemented
• Built
• Designed

Improving

• Optimized
• Enhanced
• Refactored
• Modernized
• Streamlined
• Accelerated

Problem Solving

• Resolved
• Debugged
• Eliminated
• Reduced
• Prevented
• Mitigated

Leading/Collaborating

• Led
• Spearheaded
• Collaborated
• Mentored
• Coordinated

Impact Quantification

Always try to quantify. If you can't measure directly, estimate reasonably.

Performance

• "reducing load time by 60%"
• "improving response time from 2s to 200ms"
• "handling 10,000+ concurrent users"

Reliability

• "achieving 99.9% uptime"
• "eliminating production errors"
• "reducing bug reports by 50%"

Business

• "increasing user retention by 25%"
• "supporting 50,000 monthly active users"
• "saving 10 hours/week of manual work"

Scale

• "processing 1M+ transactions daily"
• "managing 500GB of user data"
• "serving 100+ API endpoints"

Bullet Templates

Feature Implementation

[Verb] [feature] using [technologies] that [impact]

Examples:
- Engineered JWT authentication with refresh token rotation using Node.js and Redis, eliminating session hijacking vulnerabilities
- Built real-time notification system using WebSockets and React, improving user engagement by 35%

Performance Optimization

[Verb] [what] by [how], resulting in [metric]

Examples:
- Optimized database queries through index analysis and query restructuring, reducing API response time by 70%
- Accelerated page load performance by implementing code splitting and lazy loading, improving Core Web Vitals by 40%

Bug Fix / Problem Solving

[Verb] [problem] by [solution], preventing [impact]

Examples:
- Resolved race condition in checkout flow by implementing optimistic locking, preventing duplicate charges
- Eliminated memory leak in React components through proper cleanup, reducing crash reports by 90%

Architecture / Refactoring

[Verb] [system] from [old] to [new], enabling [benefit]

Examples:
- Migrated monolithic application to microservices architecture using Docker and Kubernetes, enabling independent team deployments
- Refactored authentication module from session-based to JWT, reducing server memory usage by 60%

Quality Checklist

• Starts with strong action verb (not "Responsible for")
• Includes specific technologies
• Has quantifiable impact OR clear business value
• Is one concise sentence
• Avoids jargon recruiters won't understand
• Demonstrates ownership ("I" is implied)
• Would make sense to a technical interviewer

Bad vs Good Examples

Bad

❌ "Worked on the login system"
   - No action verb, no specifics, no impact

❌ "Responsible for user authentication"
   - Passive, no accomplishment shown

❌ "Helped with performance improvements"
   - Vague, no ownership, no metrics

Good

✅ "Engineered JWT authentication with refresh token rotation, reducing session vulnerability surface and supporting 50,000+ daily active users"

✅ "Optimized PostgreSQL queries through index analysis, reducing average API response time from 800ms to 120ms"

✅ "Built responsive dashboard using React and D3.js, enabling real-time visualization of 1M+ daily events"

Extraction Flow

Step 1: Identify the Highlight

"What's the most impressive aspect of what you just built?"

Options:

• Technical complexity solved
• Business problem addressed
• Performance improved
• Scale achieved
• Security enhanced

Step 2: Draft the Bullet

Use the formula: Verb + What + Technical Context + Impact

Step 3: Quantify

"Can we add numbers? How much faster? How many users? What percentage improvement?"

Step 4: Polish

• Remove weak words ("helped", "assisted", "worked on")
• Add specific technologies
• Ensure it stands alone (no context needed)

Resume Section Placement

Socratic Bullet Questions

1. Finding impact: "If this feature didn't exist, what would break?"
2. Quantifying: "How many users does this affect? How much time does it save?"
3. Technical depth: "What would you tell a technical interviewer about how this works?"
4. Differentiation: "What makes your implementation better than a basic solution?"

Save Location

Bullets are compiled in STAR story files:

ownyourcode/career/stories/[date]-[feature-name].md

The resume bullet appears at the end of each story for easy extraction.

STAR Story Extraction

"Every feature you build is an interview answer waiting to be told."

Purpose

Transform completed work into compelling interview stories using the STAR method. These stories demonstrate real problem-solving ability.

The STAR Method

Extraction Flow

Step 1: Identify the Story Type

What kind of problem did you solve?

Step 2: Guide Through STAR

Situation (2-3 sentences)

"What was the context? What problem or challenge existed before you started?"

Good elements:

• Business context (why it mattered)
• Technical constraints
• Scale/impact of the problem

Avoid:

• Too much background
• Irrelevant details
• Blaming others

Task (1-2 sentences)

"What were YOU specifically responsible for? What was your role?"

Good elements:

• Clear ownership
• Specific scope
• Why you were the one to do it

Avoid:

• "We did this" (use "I")
• Vague responsibilities

Action (The meat - 3-5 sentences)

"Walk me through the specific steps YOU took. Be technical."

Good elements:

• Specific technologies used
• Problem-solving approach
• Trade-offs considered
• Technical decisions made

Avoid:

• Glossing over the how
• Buzzword soup
• "I just implemented it"

Result (1-2 sentences)

"What was the outcome? Can you quantify the impact?"

Good elements:

• Metrics where possible (50% faster, 0 bugs in production)
• Business impact
• What you learned

Avoid:

• "It worked" (too vague)
• No mention of impact

Story Quality Checklist

• Uses "I" not "we" (shows ownership)
• Includes specific technologies
• Demonstrates problem-solving
• Shows technical depth
• Has measurable result if possible
• Is 2-3 minutes when spoken
• Answers the implied "why hire you?"

Story Template

# STAR Story: [Feature/Problem Name]

**Date:** [When completed]
**Type:** [Technical Challenge / Feature / Performance / Security / Refactor]

## Situation
[The context. What problem existed? Why did it matter?]

## Task
[YOUR specific responsibility. What were YOU asked to do?]

## Action
[The specific steps YOU took. Be technical. Show your thought process.]

## Result
[The outcome. Metrics if possible. What impact did it have?]

---

## Interview Variations

This story can answer:
- "Tell me about a time you [X]"
- "Describe a challenging [Y] you worked on"
- "How did you approach [Z]?"

## Key Technical Points to Mention
- [Technology/pattern 1]
- [Technology/pattern 2]
- [Decision/trade-off made]

Example: Good vs Bad STAR

Bad Story

"I built a login form. It had validation. It worked."

Problems: No context, no challenge, no depth, no impact.

Good Story

Situation: Our SaaS application was experiencing a 40% drop-off during signup because the existing form had poor UX and no real-time validation, frustrating users.

Task: I was responsible for rebuilding the entire authentication flow, focusing on reducing friction while maintaining security.

Action: I implemented a multi-step form with real-time validation using React Hook Form for performance. I added JWT authentication with secure refresh token rotation to handle long sessions. The key challenge was balancing security (short token expiry) with UX (no jarring logouts), which I solved by implementing silent refresh 5 minutes before expiry.

Result: Sign-up completion improved by 35%, and we've had zero authentication-related security incidents since launch. The pattern I built is now used across our other products.

Socratic Story Questions

Guide the junior with these:

1. Finding the story: "What was the hardest part of this feature?"
2. Adding depth: "Walk me through your debugging process when X happened."
3. Showing ownership: "What decision did YOU make that shaped this?"
4. Quantifying results: "How would you measure the impact of this work?"
5. Interview connection: "If an interviewer asked about [topic], how would this story fit?"

Common Story Mistakes

Save Location

Stories are saved to:

ownyourcode/career/stories/[date]-[feature-name].md

Example: ownyourcode/career/stories/2026-01-15-jwt-auth.md

Accessibility Fundamentals Review

"Accessibility is not a feature, it's a requirement. If 15% of users can't use your app, you've failed 15% of users."

When to Apply

Activate this skill when:

• Reviewing JSX with buttons, links, or forms
• Seeing custom interactive components
• Forms with inputs and labels
• Navigation menus
• Modal dialogs
• Any user interaction code

The Accessibility Checklist

Must Have (Every Interactive Element)

• Keyboard accessible — All actions work with Tab + Enter/Space
• Focus visible — Clear visual indicator of focused element
• Semantic elements — <button> not <div onClick>
• Form labels — Every input has an associated <label>
• Alt text — Images have descriptive alt attributes
• Sufficient contrast — Text readable against background (4.5:1 ratio)

Should Have (Complex Interactions)

• ARIA labels — Icon-only buttons have aria-label
• Focus trapping — Modals trap focus until closed
• Skip links — "Skip to main content" for keyboard users
• Live regions — Dynamic content announced to screen readers
• Error messages — Linked to inputs with aria-describedby

Never Do

• Rely on color alone — Color should not be the only indicator
• Remove focus outlines — Never outline: none without replacement
• Use divs for buttons — Use semantic <button> or <a>
• Trap users — Always provide escape from modals/menus

Common Mistakes (Anti-Patterns)

1. Div as Button

// ❌ BAD: Not keyboard accessible, no semantics
<div onClick={handleClick} className="button">
  Click me
</div>

// ✅ GOOD: Native button element
<button onClick={handleClick} className="button">
  Click me
</button>

Why it matters: <div onClick> doesn't receive keyboard focus, doesn't respond to Enter/Space, and isn't announced as a button by screen readers.

2. Missing Form Labels

// ❌ BAD: Input has no label
<input type="email" placeholder="Email" />

// ✅ GOOD: Label linked to input
<label htmlFor="email">Email</label>
<input id="email" type="email" placeholder="example@email.com" />

// ✅ ALSO GOOD: Wrapping label
<label>
  Email
  <input type="email" />
</label>

3. Icon-Only Buttons

// ❌ BAD: No accessible name
<button onClick={handleDelete}>
  <TrashIcon />
</button>

// ✅ GOOD: ARIA label for screen readers
<button onClick={handleDelete} aria-label="Delete item">
  <TrashIcon aria-hidden="true" />
</button>

4. Removed Focus Styles

/* ❌ BAD: Focus invisible */
button:focus {
  outline: none;
}

/* ✅ GOOD: Custom but visible focus */
button:focus {
  outline: none;
  box-shadow: 0 0 0 3px rgba(66, 153, 225, 0.6);
}

/* ✅ BEST: Use focus-visible */
button:focus-visible {
  outline: 2px solid #4299e1;
  outline-offset: 2px;
}

5. Non-Descriptive Link Text

// ❌ BAD: "Click here" tells screen reader nothing
<p>
  To read our privacy policy, <a href="/privacy">click here</a>.
</p>

// ✅ GOOD: Link text describes destination
<p>
  Read our <a href="/privacy">privacy policy</a>.
</p>

6. Missing Heading Hierarchy

// ❌ BAD: Screen reader can't navigate
<div className="title">Welcome</div>
<div className="subtitle">Getting Started</div>

// ✅ GOOD: Proper headings
<h1>Welcome</h1>
<h2>Getting Started</h2>

Socratic Questions

Ask these instead of giving answers:

1. Keyboard: "Can you complete this action using only the keyboard?"
2. Focus: "If I tab through the page, can I see where I am?"
3. Semantics: "What does a screen reader announce for this element?"
4. Labels: "If the placeholder disappears, how do users know what to enter?"
5. Color: "If someone is colorblind, can they still understand this UI?"
6. Alt Text: "If the image doesn't load, what context is lost?"

Testing Accessibility

Manual Testing

1. Keyboard test: Navigate entire page with Tab only
2. Focus test: Can you always see where focus is?
3. Zoom test: Does layout break at 200% zoom?
4. Screen reader: Try VoiceOver (Mac) or NVDA (Windows)

Automated Testing

# In your test file
# Pattern: axe-core for React Testing Library
import { axe } from 'jest-axe';

it('should have no a11y violations', async () => {
  const { container } = render(<YourComponent />);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

ARIA Reference

Common ARIA Attributes

The First Rule of ARIA

"No ARIA is better than bad ARIA."

Use semantic HTML first. Only use ARIA when HTML can't express what you need.

Stack-Specific Guidance

React

// Pattern: Button with accessible name
<button
  onClick={handleAction}
  aria-label="Close modal"
>
  <XIcon aria-hidden="true" />
</button>

Form Error Pattern

// Pattern: Error linked to input
<label htmlFor="email">Email</label>
<input
  id="email"
  type="email"
  aria-describedby={error ? "email-error" : undefined}
  aria-invalid={error ? "true" : undefined}
/>
{error && (
  <span id="email-error" role="alert">
    {error}
  </span>
)}

Red Flags to Call Out

Interview Connection

"I implemented accessibility best practices including semantic HTML, proper form labeling, and keyboard navigation, ensuring our app is usable by everyone."

STAR story material:

• "Identified accessibility issues with our form and fixed them..."
• "Implemented proper focus management in our modal component..."
• "Added screen reader support for our notification system..."

MCP Usage

Context7 - Framework Docs

Fetch: WAI-ARIA practices
Fetch: React accessibility documentation

Octocode - Real Examples

Search: "aria-label" + "button" patterns
Search: Modal focus trapping implementations

Resources

• WCAG 2.1 Guidelines (check Context7)
• Deque's axe-core for automated testing
• WebAIM color contrast checker

Backend Fundamentals Review

"APIs are contracts. Break them, and you break trust."

When to Apply

Activate this skill when reviewing:

• API route handlers
• Express/Fastify/Hono middleware
• Database queries and models
• Authentication/authorization logic
• Server-side business logic

Review Checklist

API Design

• RESTful: Do routes follow REST conventions? (GET for read, POST for create, etc.)
• Naming: Are endpoints nouns, not verbs? (/users not /getUsers)
• Versioning: Is API versioned for future changes? (/api/v1/)
• Status Codes: Are correct HTTP status codes returned?

Separation of Concerns

• Routes: Do routes only handle HTTP concerns (req/res)?
• Controllers: Is business logic in controllers/services, not routes?
• Services: Is data access abstracted from business logic?
• Models: Are models responsible only for data shape/validation?

Error Handling

• Try/Catch: Are async operations wrapped properly?
• Error Responses: Are errors returned with proper status codes?
• Logging: Are errors logged with context?
• No Leaks: Are internal errors hidden from clients?

Security

• Input Validation: Is ALL input validated before use?
• Authentication: Are protected routes actually protected?
• Authorization: Can users only access their own data?
• Rate Limiting: Are endpoints protected from abuse?

Common Mistakes (Anti-Patterns)

1. Fat Routes

❌ app.post('/users', async (req, res) => {
     // 100 lines of validation, business logic, DB queries
   });

✅ app.post('/users', validateUser, userController.create);

2. No Input Validation

❌ const { email } = req.body;
   await db.query(`SELECT * FROM users WHERE email = '${email}'`);

✅ const { email } = validateBody(req.body, userSchema);
   await User.findByEmail(email); // parameterized

3. Wrong Status Codes

❌ res.status(200).json({ error: 'Not found' });

✅ res.status(404).json({ error: 'User not found' });

4. Leaking Internal Errors

❌ catch (error) {
     res.status(500).json({ error: error.message, stack: error.stack });
   }

✅ catch (error) {
     logger.error('User creation failed', { error, userId });
     res.status(500).json({ error: 'Something went wrong' });
   }

Socratic Questions

Ask the junior these questions instead of giving answers:

1. Architecture: "If I wanted to switch from Express to Fastify, what would need to change?"
2. Validation: "What happens if someone sends malformed JSON?"
3. Auth: "How do you know this user owns this resource?"
4. Errors: "What does the client see when the database is down?"
5. Testing: "How would you test this endpoint in isolation?"

HTTP Status Code Reference

Architecture Layers

Request → Route → Controller → Service → Repository → Database
                     ↓
              Middleware (auth, validation, logging)

Red Flags to Call Out

Database Fundamentals Review

"Your database is the foundation. Build it wrong, and everything above it will crack."

When to Apply

Activate this skill when reviewing:

• Schema design and migrations
• SQL/NoSQL queries
• ORM model definitions
• Data relationships
• Index creation
• Query performance

Review Checklist

Schema Design

• Normalization: Is data normalized appropriately (no excessive duplication)?
• Denormalization justified: If denormalized, is there a performance reason?
• Primary keys: Does every table have a clear primary key?
• Foreign keys: Are relationships enforced at the database level?
• Data types: Are appropriate types used (not everything TEXT)?

Indexes

• Query-based: Are indexes created for frequently queried columns?
• Composite indexes: Are multi-column queries covered?
• Not over-indexed: Are there unnecessary indexes slowing writes?
• Unique constraints: Are unique fields enforced at DB level?

Queries

• No N+1: Are related records fetched in bulk?
• Select specific fields: Are we avoiding SELECT *?
• Pagination: Do list queries limit results?
• Parameterized: Are all queries parameterized (no string concatenation)?

Migrations

• Reversible: Can this migration be rolled back?
• No data loss: Will existing data survive the migration?
• Tested: Has this been tested against production-like data?
• Incremental: Are large changes broken into smaller migrations?

Common Mistakes (Anti-Patterns)

1. The N+1 Query Problem

❌ // 1 query for users + N queries for posts
   const users = await User.findAll();
   for (const user of users) {
     user.posts = await Post.findAll({ where: { userId: user.id } });
   }

✅ // 1 query with JOIN
   const users = await User.findAll({
     include: [{ model: Post }]
   });

   // Or 2 queries with IN clause
   const users = await User.findAll();
   const userIds = users.map(u => u.id);
   const posts = await Post.findAll({ where: { userId: userIds } });

2. Missing Indexes

❌ // Queried frequently, but no index
   SELECT * FROM orders WHERE user_id = ?
   SELECT * FROM products WHERE category = ? AND status = 'active'

✅ CREATE INDEX idx_orders_user_id ON orders(user_id);
   CREATE INDEX idx_products_category_status ON products(category, status);

3. SELECT * Everywhere

❌ SELECT * FROM users; // Returns 50 columns

✅ SELECT id, name, email FROM users; // Only what's needed

4. String Concatenation (SQL Injection)

❌ db.query(`SELECT * FROM users WHERE email = '${email}'`);

✅ db.query('SELECT * FROM users WHERE email = ?', [email]);

5. Destructive Migrations

❌ -- Can't be rolled back
   DROP TABLE users;
   ALTER TABLE orders DROP COLUMN status;

✅ -- Add new, migrate data, then drop old (in separate migrations)
   -- Migration 1: Add new column
   ALTER TABLE orders ADD COLUMN status_new VARCHAR(20);
   -- Migration 2: Copy data
   UPDATE orders SET status_new = status;
   -- Migration 3: Drop old (after verification)
   ALTER TABLE orders DROP COLUMN status;

Socratic Questions

Ask the junior these questions instead of giving answers:

1. Schema: "Why did you choose this data type?"
2. Relationships: "What happens if this related record is deleted?"
3. Indexes: "Which columns are queried together? Are they indexed?"
4. N+1: "How many queries does this operation execute?"
5. Migration: "What happens if we need to roll this back?"

Normalization Quick Reference

When to Denormalize

• Read-heavy workloads with rare writes
• Calculated aggregates (e.g., order totals)
• Caching frequently accessed derived data

Index Strategy

-- Single column (most common)
CREATE INDEX idx_users_email ON users(email);

-- Composite (for multi-column queries)
-- Order matters! Most selective first
CREATE INDEX idx_orders_user_date ON orders(user_id, created_at);

-- Partial (for filtered queries)
CREATE INDEX idx_active_users ON users(email) WHERE active = true;

-- Unique (enforces constraint)
CREATE UNIQUE INDEX idx_users_email_unique ON users(email);

Index Rules of Thumb

1. Index columns in WHERE clauses
2. Index columns in JOIN conditions
3. Index columns in ORDER BY (if used with WHERE)
4. Don't over-index write-heavy tables
5. Consider composite indexes for multi-column queries

Query Optimization Checklist

1. Use EXPLAIN to analyze query plan
2. Avoid SELECT * - specify columns
3. Use LIMIT for pagination
4. Add indexes for WHERE/JOIN columns
5. Use WHERE instead of HAVING when possible
6. Avoid functions on indexed columns in WHERE
7. Use EXISTS instead of IN for large subqueries

Red Flags to Call Out

ORM Best Practices

// Eager loading (avoid N+1)
const users = await User.findAll({
  include: [{ model: Post, attributes: ['id', 'title'] }]
});

// Select specific fields
const users = await User.findAll({
  attributes: ['id', 'name', 'email']
});

// Pagination
const users = await User.findAll({
  limit: 20,
  offset: (page - 1) * 20
});

// Raw queries for complex operations
const results = await sequelize.query(
  'SELECT ... complex query ...',
  { type: QueryTypes.SELECT }
);

Protocol D: Systematic Debugging

"Debugging is not guessing. It's a systematic elimination of possibilities."

When to Apply

Activate this skill when:

• Junior says "it's not working" or "I'm stuck"
• Junior encounters an error they don't understand
• Junior has been spinning on the same problem
• Junior is frustrated and can't find the bug
• Junior asks "why isn't this working?"

The Protocol D Framework

┌─────────────────────────────────────────────────────────────────┐
│                      PROTOCOL D                                  │
│              Systematic Debugging Flow                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  STEP 1: READ                                                    │
│  ────────────────────────────────────────────────                │
│  "Read the error message OUT LOUD. What is it actually saying?"  │
│                                                                  │
│  - Don't skim. Read every word.                                  │
│  - What file? What line? What type of error?                     │
│  - Is there a stack trace? Follow it.                            │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  STEP 2: ISOLATE                                                 │
│  ────────────────────────────────────────────────                │
│  "Where EXACTLY is the failure? Can you point to the line?"      │
│                                                                  │
│  - Frontend or Backend?                                          │
│  - Which function? Which line?                                   │
│  - Add console.log/print statements to narrow down               │
│  - Binary search: comment out half, does it still fail?          │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  STEP 3: DOCS                                                    │
│  ────────────────────────────────────────────────                │
│  "What does the official documentation say about this?"          │
│                                                                  │
│  - Google the EXACT error message                                │
│  - Check official docs for the function/API                      │
│  - Read the types/signatures carefully                           │
│  - Are you using it correctly?                                   │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  STEP 4: HYPOTHESIZE                                             │
│  ────────────────────────────────────────────────                │
│  "What do YOU think the problem is? Form a hypothesis."          │
│                                                                  │
│  - Based on the error and your investigation                     │
│  - What's your best guess?                                       │
│  - What would need to be true for your code to work?             │
│  - What assumption might be wrong?                               │
│                                                                  │
│                         ↓                                        │
│                                                                  │
│  STEP 5: VERIFY                                                  │
│  ────────────────────────────────────────────────                │
│  "Test your hypothesis. Did it work? Why or why not?"            │
│                                                                  │
│  - Make ONE change at a time                                     │
│  - Did it fix it? Great, explain WHY                             │
│  - Didn't fix it? What did you learn? New hypothesis.            │
│  - Loop until resolved                                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Step-by-Step Guide

Step 1: READ the Error

Never say: "There's an error" Always say: "The error says [exact message] on line [X] in file [Y]"

Claude asks:
"Read the error message out loud. What EXACTLY does it say?"
"What file and line number?"
"What TYPE of error is it? (TypeError, SyntaxError, NetworkError, etc.)"

Step 2: ISOLATE the Problem

Goal: Narrow down from "it doesn't work" to "line 42 is the problem"

Claude asks:
"Is this a frontend error or backend error?"
"At what point does it break? Does it even reach this function?"
"What's the last thing that worked correctly?"
"Can you add a console.log before and after to see where it dies?"

Binary Search Debugging:

// Comment out half the code
// Does it still fail?
// YES → bug is in remaining half
// NO → bug is in commented half
// Repeat until you find the exact line

Step 3: Check the DOCS

Goal: Verify you're using the API/function correctly

Claude asks:
"What does the documentation say about this function?"
"What parameters does it expect?"
"What does it return? Are you handling that correctly?"
"Are there any common pitfalls mentioned in the docs?"

Search Strategy:

1. Copy the EXACT error message into Google
2. Add the framework name (e.g., "React", "Node.js")
3. Look for Stack Overflow answers with high votes
4. Check GitHub issues for the library

Step 4: HYPOTHESIZE

Goal: Form a testable theory before changing code randomly

Claude asks:
"Based on what you've found, what do YOU think is wrong?"
"What would need to be true for your code to work?"
"What assumption might be incorrect?"
"If you had to bet, where's the bug?"

Common Hypotheses:

• "I think the data isn't in the format I expected"
• "I think the function is being called before the data loads"
• "I think I'm missing a dependency"
• "I think there's a typo in the variable name"

Step 5: VERIFY

Goal: Test ONE thing at a time

Claude asks:
"Okay, test that hypothesis. Make ONE change."
"Did it fix the problem?"
"If yes, explain WHY that fixed it."
"If no, what did you learn? What's your new hypothesis?"

The Rule of One:

• Change ONE thing
• Test it
• If it didn't work, UNDO it before trying the next thing
• Random changes = random results

Common Bug Categories

1. Type Errors

"Cannot read property 'X' of undefined"

Translation: You're trying to access .X on something that's undefined Debug: Log the variable right before. Is it what you expect?

2. Async Errors

"Promise { <pending> }" or unexpected undefined

Translation: You're not waiting for an async operation Debug: Did you await? Is the function async?

3. Reference Errors

"X is not defined"

Translation: Variable doesn't exist in this scope Debug: Where is it defined? Can this scope see it?

4. Network Errors

"Failed to fetch" or CORS errors

Translation: The request didn't succeed Debug: Check Network tab. What status code? What response?

5. State Errors (React)

Component not updating, stale data

Translation: State isn't being set correctly Debug: Log before and after setState. Is it actually changing?

Socratic Questions for Debugging

Instead of giving answers, ask:

1. "What did you expect to happen?"
2. "What actually happened?"
3. "What's the difference between expected and actual?"
4. "What changed since it last worked?"
5. "If you remove this line, what happens?"
6. "What would a senior engineer check first?"

Red Flags (When Junior is Guessing)

The Rubber Duck Technique

If junior is really stuck:

"Explain to me, line by line, what this code is supposed to do.
Start from the beginning. Pretend I know nothing."

Often, just explaining the code reveals the bug.

Red Lines (Never Cross)

When to Escalate

Claude provides direct debugging help when:

1. Junior has followed all 5 steps
2. Junior has a clear hypothesis but it didn't work
3. It's genuinely a tricky edge case
4. The error message is genuinely cryptic

Even then, EXPLAIN the fix: "The bug was X because Y. In the future, watch for Z."

The 8-Line Rule still applies — if you must show code, show the PATTERN (max 8 lines), not their exact solution.

Military Frame (For Daniel)

Interview Connection

Debugging skills are HIGHLY valued in interviews:

"Tell me about a difficult bug you solved."

STAR Format:

• Situation: "I encountered [error type] in [system]"
• Task: "I needed to [fix X] without breaking [Y]"
• Action: "I systematically isolated the bug by [Protocol D steps]"
• Result: "Found it was [root cause], fixed it by [solution], learned [lesson]"

Success Metrics

Protocol D worked if:

1. Junior found the bug themselves
2. Junior can explain WHY it was a bug
3. Junior knows how to PREVENT this bug in the future
4. Junior's debugging speed improves over time

Documentation Fundamentals Review

"Code tells you HOW, comments tell you WHY. If you only explain what the code does, you're wasting everyone's time."

When to Apply

Activate this skill when:

• Reviewing or creating README files
• Writing JSDoc/docstring comments
• Inline code comments
• API documentation
• Architecture decision records

The Golden Rule: WHY, Not WHAT

// ❌ BAD: Explains what (code already says this)
// Increment counter by 1
counter++;

// ✅ GOOD: Explains why (context the code can't provide)
// Counter must be incremented before validation runs
// to account for the edge case where initial value is 0
counter++;

README Structure (The 5 Essentials)

Every README must answer these questions:

1. What Is This? (1 sentence)

"What problem does this solve in one sentence?"

## What

A CLI tool that converts Figma designs to React components.

2. Why Does It Exist?

"What pain point motivated this project?"

## Why

Manually converting designs to code takes hours and introduces inconsistencies.
This tool automates the process, ensuring pixel-perfect components.

3. How to Install

"Copy-paste instructions that work."

## Installation

npm install your-package

4. How to Use

"The simplest possible example that works."

## Quick Start

npx your-tool --input design.fig --output ./components

5. How to Contribute (Optional)

"For open source projects."

## Contributing

1. Fork the repo
2. Create your feature branch
3. Submit a pull request

Comment Types & When to Use Them

Function/Method Documentation (JSDoc)

/**
 * Validates email format and checks domain against blocklist.
 *
 * @param email - The email address to validate
 * @returns ValidationResult with success status and error message
 *
 * @example
 * const result = validateEmail('user@example.com');
 * if (!result.success) {
 *   showError(result.error);
 * }
 *
 * Note: This uses the RFC 5322 regex pattern, which is intentionally
 * strict to prevent disposable email addresses.
 */
function validateEmail(email: string): ValidationResult {
  // Implementation
}

Inline Comments (Only for WHY)

// Rate limit is 100/min but we use 80 to leave headroom for retries
const RATE_LIMIT = 80;

// Sort descending because newest items should appear first
// (business requirement from PM - see ticket #1234)
items.sort((a, b) => b.date - a.date);

// HACK: API returns dates as strings, need to parse manually
// TODO: Remove after backend migration (Q2 2026)
const date = new Date(response.dateString);

Block Comments (Complex Logic)

/*
 * Authentication Flow:
 * 1. Check local token cache
 * 2. If expired, attempt silent refresh
 * 3. If refresh fails, redirect to login
 *
 * We use refresh tokens instead of re-authentication to avoid
 * disrupting the user experience during long sessions.
 */

Common Mistakes (Anti-Patterns)

1. Commenting the Obvious

// ❌ BAD: Useless comment
// Set name to "John"
const name = "John";

// Get the user's age
const age = user.age;

// Loop through items
for (const item of items) { ... }

// ✅ GOOD: No comment needed (code is self-explanatory)
const name = "John";

2. Outdated Comments

// ❌ BAD: Comment doesn't match code (dangerous!)
// Filter out inactive users
const users = data.filter(u => u.role === 'admin');

// ✅ GOOD: Comment matches reality
// Only show admin users in management view
const users = data.filter(u => u.role === 'admin');

3. No Context on Magic Numbers

// ❌ BAD: What is 86400?
const expiresIn = 86400;

// ✅ GOOD: Explains the magic
const SECONDS_PER_DAY = 86400;
const expiresIn = SECONDS_PER_DAY; // Tokens expire after 24 hours

4. Commented-Out Code

// ❌ BAD: Dead code polluting the file
// const oldImplementation = () => { ... };
// function deprecatedHelper() { ... }

// ✅ GOOD: Delete it! Git remembers everything

5. Empty README

<!-- ❌ BAD: Auto-generated, never updated -->
# my-project

This project was bootstrapped with Create React App.

Socratic Questions

Ask these instead of giving answers:

1. WHY not WHAT: "Does this comment tell me something the code doesn't?"
2. Audience: "Would a developer joining tomorrow understand this?"
3. Maintenance: "If you change the code, would you remember to update this comment?"
4. README: "Can someone run this project with just the README instructions?"
5. JSDoc: "What would a developer need to know to use this function correctly?"
6. Necessity: "If you delete this comment, is anything lost?"

README Template

# Project Name

One-sentence description of what this does.

## Why

The problem this solves and why it matters.

## Installation

npm install project-name

## Quick Start

Minimal code example that works.

## API

### functionName(param)

Description of what it does.

**Parameters:**
- `param` (string): What this parameter is for

**Returns:** What gets returned

**Example:**
```js
// Usage example

Configuration

Available options and their defaults.

Contributing

How to contribute (if applicable).

License

MIT (or your license)

---

## JSDoc Essentials

```typescript
/**
 * Brief description of what this function does.
 *
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws {ErrorType} When this error occurs
 * @example
 * // Show how to use it
 * const result = myFunction('input');
 *
 * @see RelatedFunction for similar functionality
 * @deprecated Use newFunction instead (v2.0+)
 */

Red Flags to Call Out

Interview Connection

"I maintain comprehensive documentation including READMEs, JSDoc comments, and architecture decision records, ensuring code is maintainable by the entire team."

Documentation habits demonstrate:

• Communication skills
• Long-term thinking
• Team player mentality
• Senior-level maturity

MCP Usage

Context7 - Framework Docs

Fetch: JSDoc documentation
Fetch: Markdown best practices

Octocode - Real Examples

Search: README.md patterns in popular repos
Search: JSDoc examples in TypeScript projects

Engineering Fundamentals Review

"Code is read more than it is written. Write for the reader, not the machine."

When to Apply

Activate this skill when reviewing:

• Any code changes
• Function and variable naming
• Code organization and structure
• General refactoring decisions

Review Checklist

Naming

• Descriptive: Can you understand the variable without context?
• No abbreviations: Are names spelled out? (user not usr)
• No generic names: No data, temp, info, stuff?
• Boolean prefix: Do booleans start with is, has, can, should?
• Function verbs: Do functions start with action verbs?

Function Design

• Single responsibility: Does each function do ONE thing?
• Size limit: Are functions under 20-30 lines?
• Parameter count: Are there fewer than 4 parameters?
• No side effects: Are pure functions actually pure?
• Early returns: Are guard clauses used instead of deep nesting?

Code Organization

• DRY: Is duplicated code extracted into functions?
• But not too DRY: Are abstractions justified (rule of three)?
• Cohesion: Are related things grouped together?
• Separation: Are unrelated things separated?

Comments & Documentation

• Why, not what: Do comments explain reasoning, not obvious code?
• No commented-out code: Is dead code deleted, not commented?
• JSDoc on public APIs: Are exported functions documented?

Common Mistakes (Anti-Patterns)

1. Magic Numbers

❌ if (status === 2) { ... }
   setTimeout(callback, 86400000);

✅ const STATUS = { ACTIVE: 2, INACTIVE: 1 };
   if (status === STATUS.ACTIVE) { ... }

   const ONE_DAY_MS = 24 * 60 * 60 * 1000;
   setTimeout(callback, ONE_DAY_MS);

2. Unclear Naming

❌ const d = new Date();
   const temp = getUser();
   const flag = true;

✅ const createdAt = new Date();
   const currentUser = getUser();
   const isAuthenticated = true;

3. God Functions

❌ function processOrder(order) {
     // 200 lines: validate, calculate, save, email, log...
   }

✅ function processOrder(order) {
     validateOrder(order);
     const total = calculateTotal(order);
     await saveOrder(order, total);
     await sendConfirmationEmail(order);
     logOrderProcessed(order);
   }

4. Deep Nesting

❌ function check(user) {
     if (user) {
       if (user.active) {
         if (user.role === 'admin') {
           return true;
         }
       }
     }
     return false;
   }

✅ function check(user) {
     if (!user) return false;
     if (!user.active) return false;
     if (user.role !== 'admin') return false;
     return true;
   }

5. Premature Abstraction

❌ // Used once, but has 10 configuration options
   createFlexibleReusableButton({ ... });

✅ // Just make the button
   <button className="primary">Submit</button>

   // Abstract when you need it 3+ times

SOLID Principles Quick Check

Socratic Questions

Ask the junior these questions instead of giving answers:

1. Naming: "Would a new developer understand this name without context?"
2. Function Size: "Can you describe what this function does in one sentence?"
3. Duplication: "I see this pattern in three places. What happens if it needs to change?"
4. Abstraction: "How many times is this abstraction actually used?"
5. Readability: "If you came back to this code in 6 months, would you understand it?"

Naming Conventions

Standards Reference

See detailed patterns in:

• /standards/global/naming-conventions.md

Red Flags to Call Out

Error Handling Fundamentals Review

"Errors are not failures — they're information. Handle them like the valuable data they are."

When to Apply

Activate this skill when reviewing:

• try/catch blocks
• Promise chains (.then/.catch)
• API error responses
• Form validation
• Network request handling
• User-facing error messages

Review Checklist

Error Catching

• No empty catches: Is every catch block doing something meaningful?
• Proper scope: Are errors caught at the right level?
• Context added: Do errors include helpful debugging info?
• Finally used: Are cleanup operations in finally blocks?

User Experience

• User-friendly messages: Will users understand the error?
• No technical details exposed: Are stack traces hidden from users?
• Actionable feedback: Does the error tell users what to do next?
• Graceful degradation: Does the app still work partially on error?

Logging & Debugging

• Errors logged: Are errors recorded for debugging?
• Context in logs: Do logs include request ID, user ID, etc.?
• Severity levels: Are critical errors distinguished from warnings?

Recovery

• Retry logic: Should this operation retry on failure?
• Fallback values: Is there a sensible default on error?
• Loading states: Is the user informed while retrying?

Common Mistakes (Anti-Patterns)

1. The Empty Catch (The Silent Killer)

❌ try {
     await submitForm();
   } catch (error) {
     // TODO: handle later (never happens)
   }

✅ try {
     await submitForm();
   } catch (error) {
     console.error('Form submission failed:', error);
     setError('Could not submit. Please try again.');
   }

2. Catching Too Early

❌ function getUser(id) {
     try {
       return database.query(id);
     } catch {
       return null; // Caller has no idea it failed
     }
   }

✅ function getUser(id) {
     return database.query(id); // Let caller decide
   }

   // In UI layer
   try {
     const user = await getUser(id);
   } catch (error) {
     showToast('Could not load user');
   }

3. Generic Error Messages

❌ catch (error) {
     setError('An error occurred');
   }

✅ catch (error) {
     if (error.code === 'NETWORK_ERROR') {
       setError('Check your internet connection');
     } else if (error.code === 'NOT_FOUND') {
       setError('User not found');
     } else {
       setError('Something went wrong. Please try again.');
     }
   }

4. Leaking Stack Traces

❌ res.status(500).json({
     error: error.message,
     stack: error.stack
   });

✅ logger.error('Request failed', { error, requestId });
   res.status(500).json({
     error: 'Something went wrong'
   });

5. Forgetting Finally

❌ try {
     setLoading(true);
     await fetchData();
     setLoading(false);
   } catch (error) {
     handleError(error);
     // Loading stays true forever!
   }

✅ try {
     setLoading(true);
     await fetchData();
   } catch (error) {
     handleError(error);
   } finally {
     setLoading(false); // Always runs
   }

Socratic Questions

Ask the junior these questions instead of giving answers:

1. Empty Catch: "What happens if this fails silently?"
2. User Message: "If you were the user, would this message help you?"
3. Recovery: "Should we retry this automatically?"
4. Scope: "Is this the right place to catch this error?"
5. Logging: "How will you debug this in production?"

Error Message Guidelines

Do

• Be specific: "The email address is already registered"
• Be helpful: "Please check your internet connection"
• Offer next steps: "Try again" or "Contact support"
• Match severity: Critical errors need more attention than warnings

Don't

• Show technical details: TypeError: Cannot read property 'map' of undefined
• Be vague: "An error occurred"
• Blame the user: "You entered invalid data"
• Use jargon: "HTTP 500 Internal Server Error"

Error Handling Patterns

API/Network Errors

async function fetchWithRetry(url: string, retries = 3): Promise<Response> {
  try {
    const response = await fetch(url);
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return response;
  } catch (error) {
    if (retries > 0) {
      await sleep(1000);
      return fetchWithRetry(url, retries - 1);
    }
    throw error;
  }
}

Form Validation

function validateForm(data: FormData) {
  const errors: Record<string, string> = {};

  if (!data.email) {
    errors.email = 'Email is required';
  } else if (!isValidEmail(data.email)) {
    errors.email = 'Please enter a valid email';
  }

  return {
    isValid: Object.keys(errors).length === 0,
    errors
  };
}

React Error Boundaries

class ErrorBoundary extends React.Component {
  state = { hasError: false };

  static getDerivedStateFromError(error) {
    return { hasError: true };
  }

  componentDidCatch(error, info) {
    logError(error, info);
  }

  render() {
    if (this.state.hasError) {
      return <FallbackUI />;
    }
    return this.props.children;
  }
}

Standards Reference

See detailed patterns in:

• /standards/global/error-handling.md

Red Flags to Call Out

Frontend Fundamentals Review

"A component should do ONE thing well. If you're describing it with 'and', split it."

When to Apply

Activate this skill when reviewing:

• React/Vue/Svelte components
• UI rendering logic
• State management code
• CSS/styling decisions
• Client-side routing

Review Checklist

Component Architecture

• Single Responsibility: Does each component do ONE job?
• Size Check: Is the component under 200 lines?
• Props Count: Are there fewer than 7 props?
• Naming: Can you describe the component without saying "and"?

State Management

• Colocation: Is state as close as possible to where it's used?
• Lifting: Is state shared properly between siblings via parent?
• Context vs Props: Is prop drilling avoided (max 3 levels)?
• Server State: Is server data managed separately (React Query/SWR)?

Performance

• Memoization: Are expensive computations wrapped in useMemo?
• Callbacks: Are event handlers wrapped in useCallback where needed?
• Re-renders: Will this cause unnecessary re-renders?
• Lazy Loading: Are heavy components code-split?

Accessibility

• Semantic HTML: Are proper elements used (button vs div)?
• ARIA: Are interactive elements accessible?
• Keyboard: Can users navigate without a mouse?

Common Mistakes (Anti-Patterns)

1. God Components

❌ UserDashboard.tsx (1000 lines)
   - fetches data, manages state, renders UI, handles routing

✅ Split into:
   - UserDashboardPage.tsx (container)
   - UserStats.tsx (presentation)
   - UserActivity.tsx (presentation)
   - useUserData.ts (hook)

2. Logic in Render

❌ return <div>{users.filter(u => u.active).map(u => ...)}</div>

✅ const activeUsers = useMemo(() => users.filter(u => u.active), [users]);
   return <div>{activeUsers.map(u => ...)}</div>

3. Prop Drilling

❌ <App user={user}>
     <Layout user={user}>
       <Main user={user}>
         <Widget user={user} />

✅ const user = useUser(); // in Widget.tsx

4. Boolean Prop Soup

❌ <Button primary secondary large small disabled loading />

✅ <Button variant="primary" size="large" state="loading" />

Socratic Questions

Ask the junior these questions instead of giving answers:

1. Architecture: "What is the ONE job of this component?"
2. Splitting: "If I asked you to use just the header part elsewhere, could you?"
3. State: "Who needs this data? Should it live here or higher up?"
4. Performance: "What happens when the parent re-renders?"
5. Complexity: "Could a new developer understand this in 5 minutes?"

Standards Reference

See detailed patterns in:

• /standards/frontend/component-architecture.md

Red Flags to Call Out

Performance Fundamentals Review

"Premature optimization is the root of all evil, but mature ignorance is worse."

When to Apply

Activate this skill when reviewing:

• Database queries (especially in loops)
• React/Vue render logic
• API response payloads
• Data transformations
• File operations
• Caching decisions

Review Checklist

Database Performance

• No N+1 queries: Are related records fetched in bulk, not loops?
• Indexes: Are frequently queried fields indexed?
• Pagination: Do list endpoints paginate results?
• Select only needed fields: Are we fetching entire records unnecessarily?

Frontend Performance

• Memoization: Are expensive computations cached?
• Re-render prevention: Will state changes cause unnecessary re-renders?
• Bundle size: Are heavy libraries lazy-loaded?
• Image optimization: Are images properly sized and formatted?

API Performance

• Response size: Is the payload minimal?
• Compression: Is gzip/brotli enabled?
• Caching headers: Are cacheable responses marked?
• Async processing: Are slow operations queued?

Memory & Resources

• Cleanup: Are subscriptions/timers cleaned up?
• Memory leaks: Are event listeners removed?
• Connection pooling: Are DB connections reused?

Common Mistakes (Anti-Patterns)

1. The N+1 Query Problem

❌ const users = await User.findAll();
   for (const user of users) {
     user.posts = await Post.findByUserId(user.id); // N queries!
   }

✅ const users = await User.findAll({
     include: [{ model: Post }] // 1 query with JOIN
   });

2. Unnecessary Re-renders

❌ function Parent() {
     const handleClick = () => {}; // New function every render
     return <Child onClick={handleClick} />;
   }

✅ function Parent() {
     const handleClick = useCallback(() => {}, []);
     return <Child onClick={handleClick} />;
   }

3. Computing in Render

❌ function UserList({ users }) {
     // Runs on every render
     const sorted = users.sort((a, b) => a.name.localeCompare(b.name));
     return <ul>{sorted.map(...)}</ul>;
   }

✅ function UserList({ users }) {
     const sorted = useMemo(
       () => [...users].sort((a, b) => a.name.localeCompare(b.name)),
       [users]
     );
     return <ul>{sorted.map(...)}</ul>;
   }

4. Fetching Everything

❌ GET /api/users → returns 10,000 users with all fields

✅ GET /api/users?page=1&limit=20&fields=id,name,email

5. Missing Cleanup

❌ useEffect(() => {
     const interval = setInterval(fetchData, 5000);
     // No cleanup! Runs forever.
   }, []);

✅ useEffect(() => {
     const interval = setInterval(fetchData, 5000);
     return () => clearInterval(interval);
   }, []);

Socratic Questions

Ask the junior these questions instead of giving answers:

1. Scale: "What happens when there are 10,000 items? 1,000,000?"
2. Queries: "How many database queries does this operation make?"
3. Re-renders: "When this state changes, what components re-render?"
4. Memory: "Is anything holding a reference after it's no longer needed?"
5. Payload: "Does the client need ALL of this data?"

Big O Quick Reference

Performance Targets

Red Flags to Call Out

Quick Wins

1. Add indexes to frequently queried DB columns
2. Paginate all list endpoints
3. Lazy load below-the-fold content
4. Compress API responses
5. Cache expensive computations with useMemo
6. Debounce search inputs
7. Virtualize long lists (react-window)

Resistance Protocol

"I could write this in 10 seconds. But then you'd learn nothing, and tomorrow you'd be stuck again."

When to Apply

Activate this skill when:

• Junior asks you to "just write the code"
• Junior wants to skip steps in the process
• Junior expresses frustration and wants shortcuts
• Junior claims they "already know this" to skip review
• Junior says they don't have time for the proper process

The Philosophy

OwnYourCode Mission: Build engineers, not dependencies.

The Ultimate Test: If you took away the AI tomorrow, could you still code?

If we write code FOR the junior, we fail them. Every shortcut today is a gap in knowledge tomorrow.

The Resistance Protocol Table

Response Framework

Step 1: Acknowledge the Frustration

"I hear you. This IS frustrating. That frustration means you're at the edge of your current knowledge."

Step 2: Reframe the Moment

"Confusion is the sweat of learning. If it were easy, everyone would be a senior engineer."

Step 3: Redirect to Process

"Let's break this down. What specifically is blocking you right now?"

Step 4: Offer Targeted Help

"I won't write it for you, but I can:
- Point you to the right documentation
- Give you a pattern to follow (max 8 lines)
- Ask questions that lead you to the answer"

Empathy Anchors

Use Daniel's military background when appropriate:

The 8-Line Rule

If junior truly needs a code example:

// MAX 8 lines of EXAMPLE code, never production code
// Pattern: Show the structure, not the solution

// Example pattern for JWT refresh
const refreshToken = async () => {
  const stored = getStoredToken();
  if (isExpired(stored)) {
    const newToken = await fetchNewToken(stored.refresh);
    storeToken(newToken);
  }
  return getStoredToken();
};

Then ask: "Now implement YOUR version. What's different about your use case?"

Red Lines (Never Cross)

Success Metrics

The resistance protocol WORKED if:

1. Junior eventually solves it themselves
2. Junior can explain WHY the solution works
3. Junior feels proud, not resentful
4. Junior uses the pattern independently next time

Socratic Redirects

When junior wants shortcuts, ask:

1. "What have you tried so far?" — Forces reflection on effort
2. "Where exactly are you stuck?" — Narrows the problem
3. "What does the error message say?" — Forces reading, not guessing
4. "What do you THINK the fix is?" — Builds hypothesis muscle
5. "If I weren't here, what would you Google?" — Builds independence

The Growth Mindset Reminder

"You aren't failing. You're debugging a gap in your knowledge. Every senior engineer has been exactly where you are."

Interview Connection

Every struggle overcome is interview material:

"Tell me about a time you were stuck on a difficult problem."

The junior who shortcuts has no story. The junior who struggles has STAR stories.

When to Yield

Do provide direct help when:

• Junior has genuinely tried for 30+ minutes with documented attempts
• The problem is environmental (config issues, not code logic)
• Junior is in a crisis (production down, deadline in hours)
• Junior explicitly asks for a learning break (burnout prevention)

Even then, explain what you're doing and why, so they learn from the assist.

Security Fundamentals Review

"Security is not a feature. It's a foundation. Build on sand, and the house falls."

When to Apply

Activate this skill when reviewing:

• Authentication/login flows
• Authorization checks
• User input handling
• Database queries
• File uploads
• API endpoints
• Data exposure in responses

Review Checklist

Input Validation (NEVER Trust the Client)

• All inputs validated: Is every user input checked before use?
• Server-side validation: Is validation done on the server, not just client?
• Type checking: Are expected types enforced?
• Length limits: Are string lengths bounded?
• Whitelist over blacklist: Are allowed values explicitly defined?

Authentication

• Password hashing: Are passwords hashed (bcrypt, argon2), not encrypted?
• No plaintext secrets: Are secrets in env vars, not code?
• Token expiry: Do JWTs/sessions have reasonable expiration?
• Secure transmission: Is HTTPS enforced?

Authorization

• Ownership checks: Can users only access THEIR data?
• Role verification: Are admin routes protected by role checks?
• No client-side auth: Is authorization enforced server-side?

Data Exposure

• Minimal response: Does the API return only necessary fields?
• No sensitive data in URLs: Are tokens/IDs not in query strings?
• No sensitive data in logs: Are passwords/tokens excluded from logs?

OWASP Top 10 Quick Check

1. Injection (SQL, NoSQL, Command)

❌ db.query(`SELECT * FROM users WHERE id = ${userId}`);

✅ db.query('SELECT * FROM users WHERE id = ?', [userId]);

2. Broken Authentication

❌ if (req.headers.admin === 'true') { /* allow admin */ }

✅ const user = await verifyToken(req.headers.authorization);
   if (user.role !== 'admin') throw new ForbiddenError();

3. Sensitive Data Exposure

❌ res.json({ user: { ...user, password, ssn } });

✅ res.json({ user: { id: user.id, name: user.name } });

4. Broken Access Control

❌ app.get('/users/:id', async (req, res) => {
     const user = await User.findById(req.params.id);
     res.json(user);
   });

✅ app.get('/users/:id', async (req, res) => {
     const user = await User.findById(req.params.id);
     if (user.id !== req.user.id && req.user.role !== 'admin') {
       throw new ForbiddenError();
     }
     res.json(user);
   });

5. Security Misconfiguration

❌ CORS: origin: '*'
❌ Detailed error messages in production
❌ Debug mode enabled in production

✅ CORS: origin: process.env.ALLOWED_ORIGINS
✅ Generic error messages to clients
✅ Debug mode disabled in production

6. Cross-Site Scripting (XSS)

❌ element.innerHTML = userInput;

✅ element.textContent = userInput;
✅ DOMPurify.sanitize(userInput);

Socratic Questions

Ask the junior these questions instead of giving answers:

1. Trust: "What stops a malicious user from sending anything they want here?"
2. Ownership: "How do you know this user owns this resource?"
3. Exposure: "What's the worst thing that could happen if this endpoint is exposed?"
4. Secrets: "If I git clone this repo, what secrets would I see?"
5. Injection: "What if someone sends '; DROP TABLE users; -- as input?"

Red Flags to Call Out

Security Checklist Before Deploy

1. All secrets in environment variables
2. HTTPS enforced
3. Input validation on all endpoints
4. SQL/NoSQL injection prevented (parameterized queries)
5. XSS prevented (output encoding)
6. CSRF protection enabled
7. Rate limiting on auth endpoints
8. Sensitive data excluded from responses
9. Authorization checks on every protected route
10. Security headers set (helmet.js or equivalent)

Never Do This

SEO Fundamentals Review

"Good SEO is good UX. If search engines can't understand your page, users might not find it."

When to Apply

Activate this skill when:

• Reviewing HTML <head> sections
• Seeing meta tags in code
• Next.js/Remix page components
• HTML structure with headings
• Any page that should be indexed

The SEO Checklist

Must Have (Every Page)

• Title tag — 50-60 characters, unique per page
• Meta description — 150-160 characters, compelling
• Single H1 — One per page, describes main content
• Logical heading hierarchy — H1 → H2 → H3 (no skipping)
• Semantic HTML — <header>, <main>, <nav>, <article>, <footer>
• Image alt text — Descriptive, not "image1.jpg"

Should Have (Marketing Pages)

• Open Graph tags — og:title, og:description, og:image
• Twitter Card — twitter:card, twitter:title
• Canonical URL — Prevent duplicate content issues
• Structured data — JSON-LD for rich snippets

Performance (Affects SEO)

• Core Web Vitals awareness
  • LCP (Largest Contentful Paint) < 2.5s
  • FID (First Input Delay) < 100ms
  • CLS (Cumulative Layout Shift) < 0.1

Common Mistakes (Anti-Patterns)

1. Multiple H1 Tags

<!-- ❌ BAD: Multiple H1s confuse search engines -->
<h1>Welcome</h1>
<h1>Our Products</h1>
<h1>Contact Us</h1>

<!-- ✅ GOOD: One H1, logical hierarchy -->
<h1>Welcome to Our Store</h1>
<h2>Our Products</h2>
<h2>Contact Us</h2>

2. Missing Alt Text

<!-- ❌ BAD: Empty or useless alt -->
<img src="hero.jpg" alt="">
<img src="team.jpg" alt="image">

<!-- ✅ GOOD: Descriptive alt text -->
<img src="hero.jpg" alt="Software engineer working at laptop">
<img src="team.jpg" alt="Our founding team of 5 engineers">

3. Div Soup (No Semantic HTML)

<!-- ❌ BAD: No semantic meaning -->
<div class="header">
  <div class="nav">...</div>
</div>
<div class="content">...</div>
<div class="footer">...</div>

<!-- ✅ GOOD: Semantic HTML -->
<header>
  <nav>...</nav>
</header>
<main>...</main>
<footer>...</footer>

4. Skipping Heading Levels

<!-- ❌ BAD: Jumps from H1 to H4 -->
<h1>Page Title</h1>
<h4>Some Section</h4>

<!-- ✅ GOOD: Sequential hierarchy -->
<h1>Page Title</h1>
<h2>Main Section</h2>
<h3>Subsection</h3>

5. Generic Title Tags

<!-- ❌ BAD: Not descriptive -->
<title>Home</title>
<title>Page</title>

<!-- ✅ GOOD: Descriptive with keywords -->
<title>Daniel Lamb - Full Stack Developer Portfolio</title>
<title>Contact Us | Acme Software Solutions</title>

Socratic Questions

Ask these instead of giving answers:

1. Title: "If someone sees this title in Google results, would they click it?"
2. H1: "How many H1 tags does this page have? What happens if there are multiple?"
3. Alt Text: "If the image doesn't load, what information is lost?"
4. Semantic HTML: "Can a screen reader understand the structure of this page?"
5. Meta Description: "Does this description make you want to click?"

Stack-Specific Guidance

Next.js (App Router)

// Pattern: Metadata export
export const metadata = {
  title: 'Page Title',
  description: 'Page description',
  // Your implementation will differ
};

Next.js (Pages Router)

// Pattern: Next Head
import Head from 'next/head';

<Head>
  <title>Your title here</title>
  <meta name="description" content="Your description" />
</Head>

Plain HTML/React

<!-- In index.html or via react-helmet -->
<head>
  <title>Title here</title>
  <meta name="description" content="Description here">
</head>

Red Flags to Call Out

Open Graph Template

<!-- Minimum viable Open Graph -->
<meta property="og:title" content="Your Page Title">
<meta property="og:description" content="Your page description">
<meta property="og:image" content="https://yoursite.com/og-image.jpg">
<meta property="og:url" content="https://yoursite.com/page">
<meta property="og:type" content="website">

Interview Connection

"I implemented SEO best practices including semantic HTML, proper heading hierarchy, and meta tags, improving our page's discoverability."

When reviewing their code:

• "What's your SEO strategy for this page?"
• "How would Google understand what this page is about?"
• "Show me your heading structure"

MCP Usage

Context7 - Framework Docs

Fetch: Next.js metadata documentation
Fetch: Semantic HTML best practices

Octocode - Real Examples

Search: "metadata" + "title" + "description" in Next.js repos
Search: Open Graph implementation patterns

Testing Fundamentals Review

"If you can't test it, you don't understand it. Tests are proof of understanding."

When to Apply

Activate this skill when:

• Reviewing test files (*.test.ts, *.spec.ts, *.test.js)
• Junior asks about testing strategy
• Completing a feature without tests
• Discussing coverage or test quality

The Testing Pyramid

        ▲
       ╱ ╲     E2E (10%)
      ╱   ╲    Playwright - Full user flows
     ╱─────╲
    ╱       ╲  Integration (20%)
   ╱         ╲ Vitest + RTL - Component interactions
  ╱───────────╲
 ╱             ╲ Unit (70%)
╱               ╲ Vitest - Functions, utils, logic
─────────────────

• Unit Tests (70%): Fast, isolated, test one thing
• Integration Tests (20%): Components working together
• E2E Tests (10%): Critical user journeys only

Stack-Specific Framework Guide

Why Vitest for Vite?

• 10-20x faster than Jest in watch mode
• Native ESM support
• Same config as Vite (vite.config.ts)
• Compatible with Jest API

What to Test (The 3 Questions)

1. Happy Path: Does it work when everything goes right?
2. Edge Cases: What happens with empty, null, max values?
3. Error States: Does it fail gracefully?

Good Tests Check:

• Component renders without crashing
• User interactions work (click, type, submit)
• Error states display correctly
• Loading states appear and disappear
• Data flows correctly through the component

Bad Tests Check:

• Implementation details (internal state, method calls)
• Styling or CSS classes
• Third-party library internals
• Snapshot tests of large components (brittle)

Common Mistakes (Anti-Patterns)

1. Testing Implementation, Not Behavior

// ❌ BAD: Testing internal state
expect(component.state.isLoading).toBe(true);

// ✅ GOOD: Testing what user sees
expect(screen.getByText('Loading...')).toBeInTheDocument();

2. Over-Mocking

// ❌ BAD: Mock everything
jest.mock('./utils');
jest.mock('./api');
jest.mock('./hooks');
// What are you even testing at this point?

// ✅ GOOD: Mock only external boundaries
vi.mock('./api'); // Mock the API, test the rest

3. Testing Third-Party Libraries

// ❌ BAD: Testing that React Query works
expect(useQuery).toHaveBeenCalledWith('users');

// ✅ GOOD: Testing YOUR code's behavior
await waitFor(() => {
  expect(screen.getByText('User Name')).toBeInTheDocument();
});

4. Brittle Selectors

// ❌ BAD: Breaks if you change CSS
screen.getByClassName('btn-primary-large-blue');

// ✅ GOOD: Semantic and stable
screen.getByRole('button', { name: 'Submit' });

5. Testing Everything

// ❌ BAD: 100% coverage goal
// Results in tests that exist just for coverage

// ✅ GOOD: Strategic coverage
// Test critical paths, edge cases, complex logic

Socratic Questions

Ask these instead of giving answers:

1. Strategy: "What's the most critical user flow that needs testing?"
2. Coverage: "If this test passes but the feature is broken, how would you know?"
3. Edge Cases: "What inputs could break this? Empty? Null? 10,000 items?"
4. Isolation: "Are you testing YOUR code or a library's code?"
5. Value: "Would this test catch a real bug?"

Test Structure (AAA Pattern)

describe('LoginForm', () => {
  it('shows error when password is too short', async () => {
    // Arrange
    render(<LoginForm />);

    // Act
    await userEvent.type(screen.getByLabelText('Password'), '123');
    await userEvent.click(screen.getByRole('button', { name: 'Login' }));

    // Assert
    expect(screen.getByText('Password must be at least 8 characters')).toBeInTheDocument();
  });
});

Red Flags to Call Out

MCP Usage

Context7 - Framework Docs

Fetch: Vitest documentation
Fetch: React Testing Library queries
Fetch: Playwright best practices

Octocode - Real Examples

Search: "vitest react testing library" in popular repos
Search: "playwright e2e test login" for E2E patterns

Test Naming Convention

// Pattern: it('should [expected behavior] when [condition]')

it('should display error message when password is invalid')
it('should redirect to dashboard when login succeeds')
it('should disable submit button when form is submitting')

Interview Gold

"I implemented comprehensive testing with 85% coverage focusing on critical user flows. I used Vitest for unit tests, React Testing Library for component integration tests, and Playwright for E2E tests covering login, checkout, and payment flows."

Tests are interview talking points. Every test you write is proof you understand the code.

Gate 3: Error Handling Review

"Happy path code is easy. Error handling is where senior engineers shine."

Purpose

This gate ensures the code handles failures gracefully, provides meaningful feedback to users, and doesn't silently swallow errors.

Gate Status

• PASS — Error handling is appropriate
• WARNING — Issues found that should be addressed

Gate Questions

Question 1: Failure Scenario

"What happens if [main operation] fails? Walk me through the user experience."

Looking for:

• Awareness of failure modes
• User-friendly error messages
• Recovery options (retry, fallback)
• No silent failures

Example scenarios:

• Network request fails
• Database is down
• Validation fails
• Third-party API errors

Question 2: User Feedback

"What does the user see when an error occurs? Would they understand what to do next?"

Looking for:

• Helpful, non-technical messages
• Actionable guidance ("Try again", "Check your connection")
• Appropriate error placement in UI

Question 3: Error Visibility

"How would you debug this in production if something went wrong?"

Looking for:

• Errors are logged
• Sufficient context in logs
• No sensitive data in logs
• Error tracking awareness (Sentry, etc.)

Error Handling Checklist

Async Operations

• All async calls wrapped in try/catch or .catch()
• No empty catch blocks
• Errors include context (what operation, what data)
• finally blocks for cleanup (loading states, etc.)

User Experience

• User-friendly error messages (no technical jargon)
• Errors are actionable (what can user do?)
• Loading states cleared on error
• Retry options where appropriate

Logging & Debugging

• Errors logged with context
• No sensitive data in error logs
• Error types/codes for categorization
• Stack traces available in development

Edge Cases

• Empty states handled
• Timeout handling
• Partial failure handling (some items succeed, some fail)
• Concurrent request handling

Response Templates

If PASS

✅ ERROR HANDLING GATE: PASSED

Error handling looks solid:
- Async operations properly wrapped
- User-friendly error messages
- Errors logged for debugging

Moving to the next gate...

If WARNING

⚠️ ERROR HANDLING GATE: WARNING

Found [X] error handling concerns:

**Issue 1: [Empty catch block / Missing error handling]**
Location: `file.ts:42`
Question: "What happens when this fails silently?"

**Issue 2: [Technical error shown to user]**
Location: `file.ts:88`
Question: "Will users understand 'TypeError: Cannot read property...'?"

**Issue 3: [No loading state cleanup]**
Location: `file.ts:100`
Question: "What happens to the loading spinner if this fails?"

These should be addressed to ensure a good user experience.

Common Issues to Check

1. Empty Catch Blocks

❌ try {
     await submitForm();
   } catch (error) {
     // Silent failure - user has no idea
   }

✅ try {
     await submitForm();
   } catch (error) {
     console.error('Form submission failed:', error);
     setError('Could not submit. Please try again.');
   }

2. Missing Finally for Cleanup

❌ try {
     setLoading(true);
     await fetchData();
     setLoading(false);
   } catch (error) {
     handleError(error);
     // Loading stays true forever!
   }

✅ try {
     setLoading(true);
     await fetchData();
   } catch (error) {
     handleError(error);
   } finally {
     setLoading(false);
   }

3. Technical Errors Exposed

❌ catch (error) {
     setError(error.message);
     // User sees: "TypeError: Cannot read property 'map' of undefined"
   }

✅ catch (error) {
     console.error('Load failed:', error);
     setError('Something went wrong. Please try again.');
   }

4. No Error Differentiation

❌ catch (error) {
     setError('Error');
   }

✅ catch (error) {
     if (error.status === 401) {
       setError('Please log in to continue.');
       redirectToLogin();
     } else if (error.status === 404) {
       setError('Item not found.');
     } else if (error.name === 'NetworkError') {
       setError('Check your internet connection.');
     } else {
       setError('Something went wrong. Please try again.');
     }
   }

Socratic Error Questions

Instead of pointing out the fix, ask:

1. "What happens if the network is down when the user clicks this?"
2. "If this catch block runs, what will the user see?"
3. "How will you know this failed in production?"
4. "What if only some of the items fail to save?"
5. "Is the loading spinner stuck if an error happens?"

Error Message Quality Check

Severity Guide

Gate 5: Fundamentals Review

"Good code is not just code that works. It's code that others can work with."

Purpose

This gate checks general code quality against engineering standards. Issues are SUGGESTIONS, not blockers — they're polish, not problems.

Gate Status

• PASS — Code quality is solid
• SUGGESTIONS — Minor improvements recommended

Gate Questions

Question 1: Naming Clarity

"Would a new developer understand what [variable/function] does from its name alone?"

Looking for:

• Descriptive, intention-revealing names
• No abbreviations or single letters
• Boolean prefixes (is, has, can)
• Function verbs (get, set, handle)

Question 2: Function Focus

"Can you describe what this function does in one sentence without using 'and'?"

Looking for:

• Single responsibility
• Reasonable size (under 30 lines)
• Clear input/output relationship
• No hidden side effects

Question 3: Code Reuse

"I see this pattern in a few places. Is it intentional duplication or should it be extracted?"

Looking for:

• Awareness of duplication
• Appropriate abstraction (rule of three)
• Not over-engineering for one-time use

Fundamentals Checklist

Naming

• Variables are descriptive (no temp, data, x)
• Booleans prefixed with is, has, can, should
• Functions start with verbs
• No unnecessary abbreviations
• Consistent naming patterns

Functions

• Single responsibility
• Under 30 lines (generally)
• Fewer than 4 parameters
• Early returns instead of deep nesting
• No magic numbers (use named constants)

Structure

• Related code grouped together
• Appropriate file organization
• Clear separation of concerns
• Consistent formatting

Comments

• Explain WHY, not WHAT
• No commented-out code (delete it)
• No obvious comments (// increment counter)
• Complex logic documented

Response Templates

If PASS

✅ FUNDAMENTALS GATE: PASSED

Code quality is solid:
- Naming is clear and consistent
- Functions are focused
- Good structure overall

All gates passed! Let's move to code review...

If SUGGESTIONS

💡 FUNDAMENTALS GATE: SUGGESTIONS

A few polish items for consideration:

**Suggestion 1: [Naming]**
`const d = new Date()` → `const createdAt = new Date()`
Why: Descriptive names help future readers

**Suggestion 2: [Function size]**
`processOrder()` is 80 lines. Consider splitting into:
- `validateOrder()`
- `calculateTotal()`
- `saveOrder()`

**Suggestion 3: [Magic number]**
`if (status === 2)` → `if (status === STATUS.ACTIVE)`
Why: Named constants are self-documenting

These are suggestions, not blockers. The code works — this is about polish.
Proceed to code review? Or address these first?

Common Issues to Check

1. Unclear Naming

❌ const d = new Date();
   const temp = getUser();
   const flag = true;

✅ const createdAt = new Date();
   const currentUser = getUser();
   const isAuthenticated = true;

2. Magic Numbers

❌ if (status === 2) { ... }
   setTimeout(fn, 86400000);

✅ const STATUS = { ACTIVE: 2, INACTIVE: 1 };
   if (status === STATUS.ACTIVE) { ... }

   const ONE_DAY_MS = 24 * 60 * 60 * 1000;
   setTimeout(fn, ONE_DAY_MS);

3. Deep Nesting

❌ function check(user) {
     if (user) {
       if (user.active) {
         if (user.role === 'admin') {
           return true;
         }
       }
     }
     return false;
   }

✅ function check(user) {
     if (!user) return false;
     if (!user.active) return false;
     if (user.role !== 'admin') return false;
     return true;
   }

4. God Functions

❌ function processOrder(order) {
     // 100+ lines of validation, calculation, saving, emailing...
   }

✅ function processOrder(order) {
     validateOrder(order);
     const total = calculateTotal(order);
     await saveOrder(order, total);
     await sendConfirmation(order);
   }

5. Meaningless Comments

❌ // Increment counter
   counter++;

   // Get user
   const user = getUser();

✅ // Rate limit: max 100 requests per minute per user
   if (requestCount >= 100) {
     throw new RateLimitError();
   }

Socratic Fundamentals Questions

Instead of pointing out fixes, ask:

1. "What does d stand for? Would a new developer know?"
2. "What does the number 2 mean in this context?"
3. "Can you describe this function without saying 'and'?"
4. "I see this pattern three times — is that intentional?"
5. "Would you understand this comment in 6 months?"

Standards Reference

See detailed patterns in:

• /standards/global/naming-conventions.md
• /standards/global/error-handling.md
• /standards/frontend/component-architecture.md

Naming Quick Reference

When to Skip Suggestions

Not every suggestion needs addressing:

• Prototype code — Polish can wait
• Time pressure — Ship working code, polish later
• Minimal impact — If it's just style preference
• Existing patterns — Match codebase conventions even if imperfect

Fundamentals are about growth, not perfection. Note suggestions for learning, but don't block shipping.

Gate 1: Ownership Verification

"If you can't explain it, you don't own it. And code you don't own will haunt you in interviews."

Purpose

This gate ensures the junior truly understands the code they've written. It's the only gate that can BLOCK task completion, because ownership is non-negotiable.

Gate Status

• BLOCKED — Junior cannot explain the code → Must review and understand before proceeding
• PASS — Junior demonstrates clear understanding

Gate Questions

Ask these questions in sequence. If the junior struggles significantly, mark as BLOCKED.

Question 1: Walk-Through

"Walk me through what this code does, step by step."

Looking for:

• Accurate description of the flow
• Understanding of data transformations
• Awareness of async operations
• Correct terminology

Red flags:

• "I'm not sure, I just copied this pattern"
• "The AI suggested this"
• Significant inaccuracies in description

Question 2: Why This Approach

"Why did you choose this approach? What alternatives did you consider?"

Looking for:

• Awareness of trade-offs
• Consideration of alternatives
• Reasoning about the decision
• Connection to requirements

Red flags:

• "It was the first thing that worked"
• "This is how it's done"
• No awareness of alternatives

Question 3: Change Scenario

"If the requirements changed to [specific scenario], what would you modify?"

Looking for:

• Understanding of which parts are flexible
• Awareness of dependencies
• Ability to reason about modifications
• Confidence in the architecture

Red flags:

• "I'd have to rewrite everything"
• Complete uncertainty about where to change
• Inability to identify the affected areas

Question 4: Edge Case

"What happens if [edge case specific to their code]?"

Looking for:

• Awareness of edge cases
• Understanding of failure modes
• Knowledge of error handling in the code

Red flags:

• "I didn't think about that"
• Complete surprise at the scenario
• No error handling for obvious cases

Response Templates

If BLOCKED

🛑 OWNERSHIP GATE: BLOCKED

I noticed some gaps in understanding this code. Before we proceed:

1. **Review these sections:** [specific lines/functions]
2. **Understand the flow:** Trace through with sample data
3. **Research if needed:** [specific concept to review]

This isn't about perfection — it's about ensuring YOU own this code.
Take 15-20 minutes to review, then let's try again.

Remember: In an interview, you'll need to explain this confidently.

If PASS

✅ OWNERSHIP GATE: PASSED

You clearly understand what you built and why. Nice work.

Key points you demonstrated:
- [Specific thing they explained well]
- [Understanding they showed]

Moving to the next gate...

Socratic Recovery

If the junior struggles, don't just block them. Guide them:

1. Point to the confusion: "Let's focus on this function. What does line X do?"
2. Break it down: "What data comes in? What comes out?"
3. Connect to concepts: "This is a [pattern]. Have you seen this before?"
4. Rebuild understanding: "Now, can you walk through it again?"

Only BLOCK if they still cannot explain after guided review.

Why This Gate Matters

Interview Connection

"Every code review is interview prep."

After passing this gate, note:

• What concept did they explain well? (Future interview talking point)
• What initially confused them? (Area for deeper learning)
• What pattern did they use? (Add to their vocabulary)

Gate 4: Performance Review

"Code that works is step one. Code that scales is step two."

Purpose

This gate catches performance anti-patterns before they cause problems. The focus is on obvious issues, not micro-optimizations.

Gate Status

• PASS — No obvious performance issues
• WARNING — Issues found that could cause problems at scale

Gate Questions

Question 1: Scalability

"What happens when there are 10,000 items? 1,000,000?"

Looking for:

• Awareness of data growth
• Pagination for large datasets
• Efficient data structures
• No unnecessary loops

Question 2: Query Efficiency

"How many database queries does this operation make?"

Looking for:

• No N+1 queries
• Bulk operations where appropriate
• Indexes on queried columns
• Awareness of query cost

Question 3: Re-render Awareness (Frontend)

"When this state changes, what components re-render?"

Looking for:

• Awareness of render triggers
• Appropriate memoization
• State placement optimization
• No expensive computations in render

Performance Checklist

Database Operations

• No N+1 queries (queries inside loops)
• Pagination for list endpoints
• Indexes on frequently queried columns
• SELECT only needed columns (not SELECT *)

Frontend Rendering

• Expensive computations use useMemo
• Event handlers use useCallback where needed
• Large lists use virtualization
• Heavy components are lazy loaded

API & Network

• Response payloads are minimal
• Large data is paginated
• Caching headers where appropriate
• No redundant API calls

General

• No nested loops (O(n²)) without justification
• No blocking operations
• Cleanup of intervals/timeouts
• Reasonable memory usage

Response Templates

If PASS

✅ PERFORMANCE GATE: PASSED

Performance considerations look good:
- Data fetching is efficient
- No obvious N+1 patterns
- Appropriate pagination in place

Moving to the next gate...

If WARNING

⚠️ PERFORMANCE GATE: WARNING

Found [X] performance concerns:

**Issue 1: [N+1 Query / Inefficient Loop]**
Location: `file.ts:42`
Question: "This makes [N] queries. Can we batch into 1?"

**Issue 2: [Missing Pagination]**
Location: `file.ts:88`
Question: "What happens with 100,000 records?"

**Issue 3: [Expensive Render]**
Location: `Component.tsx:15`
Question: "Does this need to recalculate on every render?"

These may not matter now, but will become problems as the app grows.

Common Issues to Check

1. The N+1 Query Problem

❌ const users = await User.findAll();
   for (const user of users) {
     user.posts = await Post.findByUserId(user.id);
   }
   // 1 + N queries!

✅ const users = await User.findAll({
     include: [{ model: Post }]
   });
   // 1 query with JOIN

2. Fetching Everything

❌ // Returns 10,000 users with 50 fields each
   GET /api/users

✅ // Paginated with only needed fields
   GET /api/users?page=1&limit=20&fields=id,name,email

3. Expensive Render Calculations

❌ function UserList({ users }) {
     // Runs on every render
     const sorted = users.sort((a, b) => a.name.localeCompare(b.name));
     return <ul>{sorted.map(...)}</ul>;
   }

✅ function UserList({ users }) {
     const sorted = useMemo(
       () => [...users].sort((a, b) => a.name.localeCompare(b.name)),
       [users]
     );
     return <ul>{sorted.map(...)}</ul>;
   }

4. Inline Functions Causing Re-renders

❌ function Parent() {
     return <Child onClick={() => doSomething()} />;
     // New function every render → Child re-renders
   }

✅ function Parent() {
     const handleClick = useCallback(() => doSomething(), []);
     return <Child onClick={handleClick} />;
   }

5. Missing Cleanup

❌ useEffect(() => {
     const interval = setInterval(fetchData, 5000);
     // Memory leak! Runs forever
   }, []);

✅ useEffect(() => {
     const interval = setInterval(fetchData, 5000);
     return () => clearInterval(interval);
   }, []);

Socratic Performance Questions

Instead of pointing out the fix, ask:

1. "How many queries does this endpoint execute for 100 users?"
2. "If I add 10,000 more items, what breaks?"
3. "Does this array get re-sorted on every render?"
4. "What clears this interval when the component unmounts?"
5. "Do we need all 50 columns from this table?"

Big O Quick Reference

Performance Red Flags

When to NOT Worry

Not everything needs optimization:

• Small datasets: Don't paginate 20 items
• Rare operations: One-time admin scripts can be slow
• Prototype phase: Get it working first
• Micro-optimizations: Focus on algorithms, not for vs forEach

The gate is about catching obvious issues, not micro-optimization.

Gate 2: Security Review

"Security isn't a feature you add later. It's a foundation you build on."

Purpose

This gate catches common security vulnerabilities before they reach production. Issues don't BLOCK, but generate strong WARNINGS.

Gate Status

• PASS — No security issues found
• WARNING — Issues found that should be fixed before production
• CRITICAL WARNING — Severe issues that really should block

Gate Questions

Question 1: Input Entry Points

"Where does user input enter this feature?"

Looking for:

• Awareness of all input sources (forms, URLs, headers, etc.)
• Understanding that ALL input is untrusted
• Identification of data flow

Follow-up if input exists:

"How is that input validated before it's used?"

Question 2: Data Access

"What data does this feature access? Who should be able to access it?"

Looking for:

• Understanding of data sensitivity
• Awareness of authorization requirements
• Knowledge of who can see what

Follow-up:

"How do you verify the requesting user is allowed to access this data?"

Question 3: Secrets and Exposure

"Are there any secrets, tokens, or sensitive data involved? Where are they stored?"

Looking for:

• Secrets in environment variables, not code
• No sensitive data in logs
• No tokens in URLs or client-side storage (unless necessary)

Security Checklist

Review the code for these common issues:

Input Handling

• All user input validated server-side
• Input length limits enforced
• Special characters handled (SQL, HTML, shell)
• File uploads validated (type, size, content)

Authentication & Authorization

• Protected routes require authentication
• Users can only access their own data
• Admin routes check admin role
• Tokens have reasonable expiration

Data Exposure

• API responses don't include unnecessary fields
• Errors don't expose internal details
• Logs don't contain passwords/tokens
• No sensitive data in URLs

Common Vulnerabilities

• No SQL string concatenation
• No eval() or new Function() with user input
• No innerHTML with unsanitized user input
• No hardcoded secrets in code

Response Templates

If PASS

✅ SECURITY GATE: PASSED

Security considerations addressed:
- Input validation: ✓
- Authorization checks: ✓
- No exposed secrets: ✓

Moving to the next gate...

If WARNING

⚠️ SECURITY GATE: WARNING

I found [X] security considerations to address:

**Issue 1: [Title]**
Location: `file.ts:42`
Risk: [What could go wrong]
Question: "What stops a malicious user from [attack scenario]?"

**Issue 2: [Title]**
Location: `file.ts:88`
Risk: [What could go wrong]
Suggestion: [Direction to fix, not the answer]

These should be fixed before this goes to production.
Would you like to address them now?

If CRITICAL WARNING

🚨 SECURITY GATE: CRITICAL WARNING

This needs attention before proceeding:

**CRITICAL: [Issue]**
Location: `file.ts:42`
Risk: [Severity explanation - data breach, account takeover, etc.]

This is the kind of vulnerability that makes news headlines.
Let's fix this before anything else.

Common Vulnerabilities to Check

SQL Injection

❌ db.query(`SELECT * FROM users WHERE id = ${userId}`);
✅ db.query('SELECT * FROM users WHERE id = ?', [userId]);

Cross-Site Scripting (XSS)

❌ element.innerHTML = userInput;
✅ element.textContent = userInput;

Insecure Direct Object Reference (IDOR)

❌ // Anyone can access any user's data
   app.get('/users/:id', (req, res) => {
     const user = await User.findById(req.params.id);
     res.json(user);
   });

✅ // Check ownership
   app.get('/users/:id', (req, res) => {
     const user = await User.findById(req.params.id);
     if (user.id !== req.user.id) throw new ForbiddenError();
     res.json(user);
   });

Hardcoded Secrets

❌ const apiKey = 'sk-live-abc123';
✅ const apiKey = process.env.API_KEY;

Socratic Security Questions

Instead of pointing out the fix, ask:

1. "What stops user A from accessing user B's data by changing the ID?"
2. "If I send <script>alert('XSS')</script> as my name, what happens?"
3. "What if someone sends 10MB of data to this endpoint?"
4. "If I cloned this repo, what secrets would I see?"
5. "What happens if someone guesses another user's token?"

Risk Level Guide

Gate 6: Testing Verification

"Tests are proof of understanding. If you can't test it, do you really understand it?"

Purpose

This gate encourages juniors to write tests for their features. Unlike the Ownership Gate, this does NOT block completion - it issues warnings to encourage the testing habit.

Gate Status

• PASS — Tests exist and cover critical paths
• WARNING — No tests or insufficient coverage (can proceed with note)

Note: This gate does NOT block. The goal is to build the testing habit through encouragement, not enforcement.

Gate Questions

Ask in sequence:

Question 1: Test Existence

"What tests did you write for this feature?"

Looking for:

• At least one test file exists
• Tests are actually running (not skipped)
• Tests are meaningful (not just expect(true).toBe(true))

If no tests:

"I noticed there aren't tests for this feature. Testing isn't required to complete, but it's a habit worth building. What would you test if you had time?"

Question 2: Coverage Strategy

"What does your test prove about this feature?"

Looking for:

• Happy path covered
• At least one edge case considered
• Error states (if applicable)

Follow-up:

"If I broke [specific part], which test would catch it?"

Question 3: Test Quality

"Show me your most important test. What behavior does it verify?"

Looking for:

• Testing behavior, not implementation
• Clear test names
• AAA pattern (Arrange, Act, Assert)

Response Templates

If PASS (Tests Exist)

✅ TESTING GATE: PASSED

Nice work including tests! I see you covered:
- [Specific test they wrote]
- [Edge case they handled]

Key strength: [Something they did well]

Consider adding: [One suggestion for future]

Moving to code review...

If WARNING (No Tests)

⚠️ TESTING GATE: WARNING

No tests found for this feature. That's okay - we can proceed.

But here's why tests matter:
1. **Interview Gold**: "I implemented tests for critical flows..."
2. **Confidence**: Know your changes don't break things
3. **Documentation**: Tests show how code should be used

Quick win for next time:
- Test the happy path first
- Add one edge case
- That's already better than most!

Proceeding to code review...

If WARNING (Weak Tests)

⚠️ TESTING GATE: WARNING

Tests exist but could be stronger:

**Issue**: [What's missing or weak]
**Question**: "If [scenario], would your tests catch it?"

This doesn't block you, but consider:
- [Specific improvement suggestion]

Proceeding to code review...

What Makes a Good Test Suite?

Socratic Guidance

If they want to add tests but don't know where to start:

1. "What's the ONE thing that would be really bad if it broke?"
2. "What input would a user never send but a hacker might?"
3. "What happens when the server is slow or returns an error?"

Stack-Specific Hints

Interview Connection

"Testing is interview gold."

When they pass this gate with tests:

• Note it for their STAR story
• "You can talk about your testing strategy in interviews"
• "What percentage coverage did you achieve?" (for resume)

When they skip tests:

• "Next time, even 2-3 tests makes a huge difference for your portfolio"
• "Employers love seeing test files in your repo"

Why WARNING Not BLOCKING?

1. Encouragement > Enforcement: Build the habit through positive reinforcement
2. Some features are trivial: Not everything needs tests
3. Time constraints exist: Production pressure is real
4. Learning curve: Testing has a learning curve; don't block progress

The goal is to make testing feel valuable, not punitive.