/fundamentals

name: fundamentals-gate
description: Verifies code quality including naming conventions, function size, and DRY principles. SUGGESTION gate that offers polish items during /own:done flow.

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

| Type | Pattern | Example | |------|---------|---------| | Variable | camelCase, descriptive | `userEmail`, `isLoading` | | Boolean | is/has/can/should prefix | `isActive`, `hasPermission` | | Function | verb + noun | `getUser()`, `handleSubmit()` | | Constant | UPPER_SNAKE_CASE | `MAX_RETRIES`, `API_URL` | | Class | PascalCase | `UserService`, `ApiClient` |

---

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.