ai-superpower/.ai/skills/clean-code/SKILL.md

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

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)

// ❌ 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

// ❌ 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);
}