kiss

What this skill does

# KISS — Simplification Opportunity Detection

Analyze source code and architecture for **simplification opportunities** — places where
accidental complexity can be reduced without losing capability. Produce actionable
findings with severity ratings, dimension scores, code locations, and concrete
simplification suggestions.

The framing matters: this is not about reporting what IS complex, but about identifying
what CAN be simplified. Essential complexity (inherent to the problem domain) is not
a simplification opportunity. Accidental complexity (introduced by our choices) is.

## Dimensions

Five dimensions, each targeting a different axis of simplification:

| Dimension | Question It Answers | Reference |
|-----------|-------------------|-----------|
| **Complexity** | Where can control flow, cognitive load, or function structure be simplified? | `references/complexity.md` |
| **Abstraction** | Where can unnecessary layers, interfaces, or indirection be removed? | `references/abstraction.md` |
| **Redundancy** | Where can dead, duplicated, or unused code be eliminated? | `references/redundancy.md` |
| **Coupling** | Where can dependencies be loosened or dependency chains shortened? | `references/coupling.md` |
| **Architecture** | Where can system-level infrastructure or layering be consolidated? | `references/architecture.md` |

## Subcommands

| Command Pattern | Scope | Reference |
|----------------|-------|-----------|
| `kiss` / `kiss all` / `kiss check` | All five dimensions | All references |
| `kiss complexity` | Code Complexity | `references/complexity.md` |
| `kiss abstraction` | Over-Abstraction | `references/abstraction.md` |
| `kiss redundancy` | Redundancy | `references/redundancy.md` |
| `kiss coupling` | Coupling & Dependencies | `references/coupling.md` |
| `kiss architecture` | Architecture Complexity | `references/architecture.md` |

When no subcommand is specified, default to all five dimensions.
When a dimension is mentioned by name (even without "kiss"), match it.

## Workflow

### 1. Identify Target Code

Determine what code to analyze:
- When files or a directory are provided, use those.
- When a class/module is referenced by name, locate it.
- When ambiguous, ask which files or directories to scan.

Supported languages: any (Python, Java, TypeScript, C#, C++, Kotlin, Go, Rust, etc.).
Adapt checks to the idioms of the target language — simplicity looks different across
languages and paradigms.

### 2. Load Dimension References

Before analyzing, read the reference file(s) for the requested dimension(s):

- `references/complexity.md` — code complexity simplification
- `references/abstraction.md` — over-abstraction simplification
- `references/redundancy.md` — redundancy elimination
- `references/coupling.md` — coupling reduction
- `references/architecture.md` — architecture consolidation

For a full audit (`kiss all`), read all five.

### 3. Analyze

For each target file/class, apply the simplification patterns from the loaded references.

**Per-dimension scoring:** For each dimension analyzed, assign a score from 1–5:

| Score | Label | Meaning |
|-------|-------|---------|
| 1 | Minimal | Few or no simplification opportunities. Code is as simple as the problem allows. |
| 2 | Low | Minor opportunities exist but are low-priority. |
| 3 | Moderate | Several opportunities that would meaningfully reduce cognitive load or maintenance cost. |
| 4 | High | Significant accidental complexity. Simplification would substantially improve the codebase. |
| 5 | Critical | Accidental complexity dominates. The code is harder than the problem it solves. |

Think carefully about each pattern — not every heuristic match is a true opportunity.
Consider context, project size, language idioms, and pragmatism. Essential complexity
is not a simplification target.

### 4. Report Findings

Present findings using this structure:

#### Per Finding

```
**[DIMENSION] Simplification Opportunity — Severity: HIGH | MEDIUM | LOW**
Location: `filename.py`, function `name`, lines ~XX-YY
Opportunity: What can be simplified and why simplifying it matters.
Approach: Concrete simplification with brief code sketch if helpful.
```

Severity guidelines:
- **HIGH**: Active maintenance pain, blocks understanding, or causes bugs.
  Simplifying this delivers immediate value.
- **MEDIUM**: Unnecessary complexity that will slow development as the codebase
  grows. Simplifying prevents future pain.
- **LOW**: Minor opportunity, worth noting but fine to defer.

#### Dimension Scores

After all findings, provide a dimension scorecard:

```
| Dimension     | Score | Label    |
|---------------|-------|----------|
| Complexity    | 3/5   | Moderate |
| Abstraction   | 2/5   | Low      |
| Redundancy    | 4/5   | High     |
| Coupling      | 2/5   | Low      |
| Architecture  | 1/5   | Minimal  |
```

Only include dimensions that were analyzed.

#### Summary

- **Count table**: `| Dimension | HIGH | MEDIUM | LOW |`
- **Top 3 priorities**: Which simplifications to tackle first and why.
- **Overall assessment**: One paragraph on the codebase's simplicity health —
  how much of its complexity is essential vs accidental, and the highest-leverage
  simplification theme.

### 5. Refactor Mode (Optional)

When a fix or simplification is requested (e.g., "fix this", "simplify it",
"show me the simpler version"), produce simplified code that resolves the identified
opportunities. Explain each change briefly.

## Pragmatism Guidelines

These are guidelines, not laws. Apply judgment:

- **Scale matters.** Small utility scripts and prototypes get a lighter touch. Don't
  flag a 30-line script for having a few extra lines of defensive code.
- **Conscious trade-offs are not violations.** When a rationale exists for a design
  choice, acknowledge it rather than insisting on purity.
- **Language idioms matter.** Java naturally has more layers than Python. Go repeats
  error handling by design. Functional code uses composition patterns that look complex
  but are idiomatic. Judge against the language's norms.
- **Prefer actionable over exhaustive.** Five important findings beat twenty trivial ones.
  Focus on what delivers the most simplification value.
- **Essential complexity is not a target.** Complex domains produce complex code. KISS
  targets accidental complexity — the complexity we introduced, not the complexity the
  problem demands.
- **Threshold awareness.** Use the metric thresholds in each reference as guidelines,
  not rigid cutoffs. A function with cyclomatic complexity of 11 in a state machine
  is fine; the same in a utility helper is not.

## Example Interaction

**User**: `kiss complexity` (with a file attached)

**Claude**:
1. Reads `references/complexity.md`
2. Analyzes the attached file for complexity simplification opportunities
3. Reports findings with locations, severity, and simplification approaches
4. Provides dimension score and summary with priorities