clean-code

# Clean Code - Pragmatic AI Coding Standards

> **CRITICAL SKILL** - Be **concise, direct, and solution-focused**.

---

## Core Principles

| Principle     | Rule                                                       |
| ------------- | ---------------------------------------------------------- |
| **SRP**       | Single Responsibility - each function/class does ONE thing |
| **DRY**       | Don't Repeat Yourself - extract duplicates, reuse          |
| **KISS**      | Keep It Simple - simplest solution that works              |
| **YAGNI**     | You Aren't Gonna Need It - don't build unused features     |
| **Boy Scout** | Leave code cleaner than you found it                       |

---

## Naming Rules

| Element       | Convention                                            |
| ------------- | ----------------------------------------------------- |
| **Variables** | Reveal intent: `userCount` not `n`                    |
| **Functions** | Verb + noun: `getUserById()` not `user()`             |
| **Booleans**  | Question form: `isActive`, `hasPermission`, `canEdit` |
| **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT`                    |

> **Rule:** If you need a comment to explain a name, rename it.

---

## Function Rules

| Rule                | Description                           |
| ------------------- | ------------------------------------- |
| **Small**           | Max 20 lines, ideally 5-10            |
| **One Thing**       | Does one thing, does it well          |
| **One Level**       | One level of abstraction per function |
| **Few Args**        | Max 3 arguments, prefer 0-2           |
| **No Side Effects** | Don't mutate inputs unexpectedly      |

---

## Code Structure

| Pattern           | Apply                             |
| ----------------- | --------------------------------- |
| **Guard Clauses** | Early returns for edge cases      |
| **Flat > Nested** | Avoid deep nesting (max 2 levels) |
| **Composition**   | Small functions composed together |
| **Colocation**    | Keep related code close           |

---

## AI Coding Style

| Situation             | Action                |
| --------------------- | --------------------- |
| User asks for feature | Write it directly     |
| User reports bug      | Fix it, don't explain |
| No clear requirement  | Ask, don't assume     |

---

## Anti-Patterns (DON'T)

| ❌ Pattern               | ✅ Fix                  |
| ------------------------ | ----------------------- |
| Comment every line       | Delete obvious comments |
| Helper for one-liner     | Inline the code         |
| Factory for 2 objects    | Direct instantiation    |
| utils.ts with 1 function | Put code where used     |
| "First we import..."     | Just write code         |
| Deep nesting             | Guard clauses           |
| Magic numbers            | Named constants         |
| God functions            | Split by responsibility |

---

## 🔴 Before Editing ANY File (THINK FIRST!)

**Before changing a file, ask yourself:**

| Question                        | Why                      |
| ------------------------------- | ------------------------ |
| **What imports this file?**     | They might break         |
| **What does this file import?** | Interface changes        |
| **What tests cover this?**      | Tests might fail         |
| **Is this a shared component?** | Multiple places affected |

**Quick Check:**

```
File to edit: UserService.ts
└── Who imports this? → UserController.ts, AuthController.ts
└── Do they need changes too? → Check function signatures
```

> 🔴 **Rule:** Edit the file + all dependent files in the SAME task.
> 🔴 **Never leave broken imports or missing updates.**

---

## Summary

| Do                     | Don't                     |
| ---------------------- | ------------------------- |
| Write code directly    | Write tutorials           |
| Let code self-document | Add obvious comments      |
| Fix bugs immediately   | Explain the fix first     |
| Inline small things    | Create unnecessary files  |
| Name things clearly    | Use abbreviations         |
| Keep functions small   | Write 100+ line functions |

> **Remember: The user wants working code, not a programming lesson.**

---

## 🔴 Self-Check Before Completing (MANDATORY)

**Before saying "task complete", verify:**

| Check                     | Question                          |
| ------------------------- | --------------------------------- |
| ✅ **Goal met?**          | Did I do exactly what user asked? |
| ✅ **Files edited?**      | Did I modify all necessary files? |
| ✅ **Code works?**        | Did I test/verify the change?     |
| ✅ **No errors?**         | Lint and TypeScript pass?         |
| ✅ **Nothing forgotten?** | Any edge cases missed?            |

> 🔴 **Rule:** If ANY check fails, fix it before completing.

---

## Verification Scripts (MANDATORY)

> 🔴 **CRITICAL:** Each agent runs ONLY their own skill's scripts after completing work.

### Agent → Script Mapping

| Agent                   | Script          | Command                                                                           |
| ----------------------- | --------------- | --------------------------------------------------------------------------------- |
| **frontend-specialist** | UX Audit        | `python ~/.{TOOL}/skills/frontend-design/scripts/ux_audit.py .`              |
| **frontend-specialist** | A11y Check      | `python ~/.{TOOL}/skills/frontend-design/scripts/accessibility_checker.py .` |
| **backend-specialist**  | API Validator   | `python ~/.{TOOL}/skills/api-patterns/scripts/api_validator.py .`            |
| **mobile-developer**    | Mobile Audit    | `python ~/.{TOOL}/skills/mobile-design/scripts/mobile_audit.py .`            |
| **database-architect**  | Schema Validate | `python ~/.{TOOL}/skills/database-design/scripts/schema_validator.py .`      |
| **security-auditor**    | Security Scan   | `python ~/.{TOOL}/skills/vulnerability-scanner/scripts/security_scan.py .`   |

| **performance-optimizer** | Lighthouse | `python ~/.{TOOL}/skills/performance-profiling/scripts/lighthouse_audit.py <url>` |
| **test-engineer** | Test Runner | `python ~/.{TOOL}/skills/testing-patterns/scripts/test_runner.py .` |
| **test-engineer** | Playwright | `python ~/.{TOOL}/skills/webapp-testing/scripts/playwright_runner.py <url>` |
| **Any agent** | Lint Check | `python ~/.{TOOL}/skills/lint-and-validate/scripts/lint_runner.py .` |
| **Any agent** | Type Coverage | `python ~/.{TOOL}/skills/lint-and-validate/scripts/type_coverage.py .` |
| **Any agent** | i18n Check | `python ~/.{TOOL}/skills/i18n-localization/scripts/i18n_checker.py .` |

> ❌ **WRONG:** `test-engineer` running `ux_audit.py`
> ✅ **CORRECT:** `frontend-specialist` running `ux_audit.py`

---

### 🔴 Script Output Handling (READ → SUMMARIZE → ASK)

**When running a validation script, you MUST:**

1. **Run the script** and capture ALL output
2. **Parse the output** - identify errors, warnings, and passes
3. **Summarize to user** in this format:

```markdown
## Script Results: [script_name.py]

### ❌ Errors Found (X items)

- [File:Line] Error description 1
- [File:Line] Error description 2

### ⚠️ Warnings (Y items)

- [File:Line] Warning description

### ✅ Passed (Z items)

- Check 1 passed
- Check 2 passed

**Should I fix the X errors?**
```

4. **Wait for user confirmation** before fixing
5. **After fixing** → Re-run script to confirm

> 🔴 **VIOLATION:** Running script and ignoring output = FAILED task.
> 🔴 **VIOLATION:** Auto-fixing without asking = Not allowed.
> 🔴 **Rule:** Always READ output → SUMMARIZE → ASK → then fix.