---
name: clean-code
description: Apply clean code principles, SOLID, and DRY practices. Use when writing, reviewing, or refactoring application code.
---

# Clean Code Guidelines

## 🎯 Purpose
Provide strict boundaries for coding style ensuring clean, maintainable, single-responsibility, and readable architecture.

**🚨 CRITICAL: If the task involves deep refactoring, architectural reviews, or you need to understand the 'Newspaper Readability', 'Declarative Layers' or formatting nuances, YOU MUST use the `read_file` tool to read `.ai/skills/clean-code/REFERENCE.md` BEFORE generating any code.**

## 🚨 Prohibitions (Thou Shalt Not)

- **NEVER write functions that do more than one thing.** If you can extract a meaningful function, do it.
- **NEVER mix levels of abstraction in one function.** High-level orchestration and low-level math/DB calls do not belong together (SLAB principle).
- **NEVER use flag arguments** (e.g., `delete(file, true)`). Split into two functions.
- **NEVER write functions with side effects** that don't match the name.
- **NEVER leave commented-out code or TODOs.** Delete them.
- **NEVER write comments that explain "what" the code does.** Comments are ONLY for explaining "why" (bugs, quirks, external constraints).
- **NEVER use unbraced `if`, `for`, or `while` statements.** Always use `{}` even for single lines.

## Workflows (Quality Checklist)

When returning code, actively verify:
1. **Naming:** Does the name reveal intent (`daysSinceLastPayment` vs `d`), is it searchable, and does it use a consistent vocabulary?
2. **Abstractions (SLAB):** Does the top-level function read declaratively (describing intent without loops or string parsing)? Are the mechanics hidden in bottom-layer imperative functions?
3. **Guard Clauses:** Are error cases and edge conditions returned early at the top of the function to avoid deep nesting?
4. **Formatting:** Are related declarations close together? Is there no "optical illusion" (like an unbraced `if` followed by misleading indentation)?

## ✅ / ❌ Examples

### Single Level of Abstraction (SLAB)
```typescript
// ❌ FORBIDDEN: Mixed levels of high-level policy and low-level mutation
function processOrder(order: Order): void {
  if (order.total < 100) {                     // high-level policy
    const discount = order.total * 0.1;        // low-level calc
    order.total -= discount;                   // mutation
  }
}

// ✅ REQUIRED: One level of abstraction per function
function processOrder(order: Order): void {
  const validated  = validateOrder(order);
  const discounted = applyDiscount(validated);
  saveOrder(discounted);
}
```

### Guard Clauses
```typescript
// ❌ FORBIDDEN: Deeply nested happy path
function handleUser(user: User): void {
  if (user != null) {
    if (user.isActive) {
      process(user);
    }
  }
}

// ✅ REQUIRED: Return early
function handleUser(user: User): void {
  if (user == null || !user.isActive) return;
  process(user);
}
```