code-simplification

Files (1)

• SKILL.md

SKILL.md (first lines)

# Code Simplification

> Inspired by the [Claude Code Simplifier plugin](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/agents/code-simplifier.md). Adapted here for the polyglot Mezon Mentor Bot / "MeKnow" project (Python + Go + TS, OpenSpec) as a process-driven skill.

## Overview

Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"

This is a polyglot repo. Every simplification must keep the **resolver-selected gates** green for the touched toolchain (Python: ruff/pyright/pytest; Go: go vet / test -race; TS: pnpm typecheck/lint/test) — the gate resolver (`.claude/workflows/lib/gate-resolver.js`) picks them by package — and respect the repo's hard invariants.

## When to Use

- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
- During code review when readability or complexity issues are flagged
- When you encounter deeply nested logic, long functions, or unclear names
- When refactoring code written under time pressure
- When consolidating related logic scattered across files
- After merging changes that introduced duplication or inconsistency

**When NOT to use:**

- Code is already clean and readable — don't simplify for the sake of it
- You don't understand what the code does yet — comprehend before you simplify
- The code is on a latency-sensitive path (retrieval / synthesize loop measured against the p95 <= 12s gate) and the "simpler" version would be measurably slower
- You're about to rewrite the module entirely — simplifying throwaway code wastes effort

## The Five Principles

### 1. Preserve Behavior Exactly

Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. In this repo this is non-negotiable around the **tenant_id scoping** (no cross-tenant leakage), the **server-side ACL** in `retrieve_kb`, the **citations-mandatory** filter (`refuse_if: no_citations`), **`temperature == 0`** on synthesize/cite/filter, and the **append-only** version lineage (`BotVersion`/`KBVersion`). If you're not sure a simplification preserves behavior, don't make it.

```
ASK BEFORE EVERY CHANGE:
→ Does this produce the same output for every input?
→ Does this maintain the same error behavior (same raised exceptions / wrapped errors / nils)?
→ Does this preserve the same side effects and ordering (DB writes, cache keys, citations)?
→ Is tenant_id still threaded and ACL still server-side?
→ Do all existing tests still pass without modification (the touched toolchain's gates)?
```

### 2. Follow Project Conventions

Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:

```
1. Read openspec/project.md and the relevant openspec/specs/<capability>/spec.md
   (and the docs/design/NNNN-*.md rationale it links)
2. Study how neighboring code handles similar patterns
3. Match the project's style for:
   - Python: ruff-clean (E/F/I/B/UP/ASYNC/SIM, line 100), pyright-clean, anthropic-sdk-python
     directly (no LangChain), tenant_id threaded, memo-shaped objects across stage boundaries
   - Go: wrapped errors fmt.Errorf("...: %w", err), ctx first param, table-driven tests, -race
   - TS (apps/portal): generated OpenAPI types (never hand-written), eslint-clean
```

Simplification that breaks project consistency is not simplification — it's churn.

### 3. Prefer Clarity Over Cleverness

Explicit code is better than compact code when the compact version requires a mental pause to parse.

```python
# UNCLEAR (Python): dense dict-literal indexing to pick a label
label = {True: "Admin", False: "User"}[user.is_admin]

# CLEAR: a small named function with guard returns
def stage_label(stage: Stage) -> str:
    match stage.status:
        case Status.DONE:    return "Done"
        case Status.REFUSED: return "Refused"
        case Status.RUNNING: return "Running"
        case _:              return "Queued"
```

```go
// UNCLEAR (Go): building a map with inline mutation in one expression-ish loop
counts := map[string]int{}
for _, m := range memos { counts[m.TenantID] = counts[m.TenantID] + 1 }

// CLEAR: a named intermediate and the idiomatic increment
countByTenant := make(map[string]int, len(memos))
for _, m := range memos {
	countByTenant[m.TenantID]++
}
```

```ts
// UNCLEAR (TS): nested ternary chain
const tier = u.admin ? (u.super ? "owner" : "admin") : "member";

// CLEAR: explicit branches
function tierOf(u: User): Tier {
  if (!u.admin) return "member";
  return u.super ? "owner" : "admin";
}
```

### 4. Maintain Balance

Simplification has a failure mode: over-simplification. Watch for these traps:

- **Inlining too aggressively** — removing a helper that gave a concept a name (e.g. `enforce_acl`, `assert_tenant`) makes the call site harder to read
- **Combining unrelated logic** — merging two simple functions into one complex function is not simpler
- **Removing "unnecessary" abstraction** — the `kb.*` MCP tool boundary and the `BotPolicy` interpreter exist on purpose (no LangChain, declarative-not-code); don't collapse them into inline calls
- **Optimizing for line count** — fewer lines is not the goal; easier comprehension is

### 5. Scope to What Changed

Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope (see `incremental-implementation`'s scope discipline). Unscoped simplification creates noise in diffs and risks unintended regressions.

## The Simplification Process

### Step 1: Understand Before Touching (Chesterton's Fence)

Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if it still applies.

```
BEFORE SIMPLIFYING, ANSWER:

From minhlucvan/emdesign, Apache-2.0.

More from minhlucvan/emdesign