flatten

Files (1)

• SKILL.md

SKILL.md (first lines)

# Flatten

When invoked, scan the specified file or directory for functions with deep nesting. Any code with a depth greater than 3 levels is excessive. Report findings with file paths and line numbers, then refactor each offending function using **extraction** and **inversion** to reduce nesting.

If the user has not specified a scope (file or directory), ask them which file or directory to focus on before proceeding.

## Core Rules

1. **Never nest more than 3 levels deep.** Count from the function body as level 1. An `if` inside the function body is level 2. A loop inside that `if` is level 3. Anything deeper must be refactored.

2. **Apply inversion first** -- it is the simpler technique. Flip conditions to put the failure or edge case first. Return, throw, or `continue` early. The happy path flows downward at the shallowest nesting depth.

3. **Apply extraction second** -- when inversion alone is not enough. Pull inner blocks (loop bodies, switch cases, deeply nested branches) into their own well-named functions. Each extracted function should have a single clear responsibility.

4. **Stack all validations at the top of a function as guard clauses.** Each guard checks one precondition and exits early if it fails. The core logic below the guards runs only when all preconditions are met.

5. **Extracted functions should be pure when possible** -- take inputs as parameters and return outputs. Avoid modifying external state. This makes the functions easier to understand and test.

6. **Add a doc comment to every extracted function.** The doc comment should be concise and describe *what* the function does and *what* it returns -- not *how* it works internally. Describe the interface, not the implementation. Use the language's standard doc format (JSDoc, pydoc, JavaDoc, `///` in Rust/C#, etc.).

7. **After refactoring, the top-level function should read like a table of contents** -- a sequence of named steps that describe what happens at a high level, with details pushed into sub-functions.

8. **Preserve existing behavior.** Do not change what the code does, only how it is structured. Run existing tests after refactoring to verify correctness.

## Procedure

1. **Find candidates.** Read the files in the user's specified scope. Identify functions where nesting exceeds 3 levels. Report each one with its file path, line number, and current max nesting depth.

2. **Assess each function.** Determine whether inversion, extraction, or both are needed:
   - If the deep nesting is caused by validation checks wrapping the main logic → **inversion** (guard clauses).
   - If the deep nesting is caused by large blocks inside loops or conditionals → **extraction** (pull into sub-functions).
   - If both → apply inversion first to flatten the outer structure, then extract remaining deep blocks.

3. **Refactor.** Apply the transformations. Name extracted functions to describe *what* they do, not *how*. Keep extracted functions in the same file/class as their caller unless they are independently reusable.

4. **Present changes.** Show the user what was changed and why, with a brief explanation for each function.

## Adapt to the User's Language

Apply these techniques using the idioms of whatever language the codebase uses. Guard clauses work in every language. Extraction means functions in procedural code, methods in OOP, or named closures in functional code.

---

## Examples

All examples below are original illustrations of the techniques. Adapt the style to match the user's actual codebase.

### Example A: Guard Clause Inversion (Simple)

A function that validates inputs and processes a payment, nested 4 levels deep:

**Before:**

```python
def process_payment(account, amount, currency):
    if account is not None:
        if amount > 0:
            if currency in SUPPORTED_CURRENCIES:
                rate = get_exchange_rate(currency)
                converted = amount * rate
                account.balance -= converted
                ledger.record(account.id, converted, currency)
                return Receipt(account.id, converted)
            else:
                raise ValueError(f"Unsupported currency: {currency}")
        else:
            raise ValueError("Amount must be positive")
    else:
        raise ValueError("Account is required")
```

The actual work (4 lines) is buried under 3 levels of validation. A reader must hold all three conditions in their head while reading the core logic.

**After:**

```python
def process_payment(account, amount, currency):
    if account is None:
        raise ValueError("Account is required")
    if amount <= 0:
        raise ValueError("Amount must be positive")
    if currency not in SUPPORTED_CURRENCIES:
        raise ValueError(f"Unsupported currency: {currency}")

    rate = get_exchange_rate(currency)
    converted = amount * rate
    account.balance -= converted
    ledger.record(account.id, converted, currency)
    return Receipt(account.id, converted)
```

Three guard clauses at the top declare the function's requirements. The core logic flows at the shallowest level. A reader can mentally discard the guards and focus on the payment logic.

---

### Example B: Loop Body Extraction

A function that processes orders inside a loop, with nested conditions for discounts and tax:

**Before:**

```typescript
function generateInvoice(orders: Order[]): Invoice {
    const lineItems: LineItem[] = [];

    for (const order of orders) {
        if (order.status === "confirmed") {
            let subtotal = 0;
            for (const item of order.items) {
                let price = item.unitPrice * item.quantity;
                if (item.category === "electronics" && item.quantity >= 10) {
                    price *= 0.9; // bulk discount
                } else if (item.category === "perishable") {
                    if (item.daysUntilExpiry < 3) {
                        price *= 0.5; // clearance
                    }
                }
                subtotal += price;
            }

From nitrictech/skills, MIT.

More from nitrictech/skills