formal-decompose

---
name: formal-decompose
description: "Force mathematical problem decomposition before implementation. Use this skill when: the problem involves layout, positioning, scaling, spacing, or any spatial/geometric computation; there are competing constraints that need to be satisfied simultaneously; you need to define a mapping between two coordinate systems or domains; the user asks 'what are the constraints?', 'what's the optimization?', 'decompose this', or 'think mathematically'; you're about to write an algorithm and haven't formally specified its inputs, outputs, bounds, and invariants; or the user uses mathematical vocabulary (supremum, bound, constraint, mapping, invariant, scaling factor). This skill prevents writing code from vibes — it forces you to specify the problem formally before touching implementation."
---

# Formal Decompose

Before writing any algorithm or spatial computation, decompose the problem mathematically. Specify inputs, outputs, constraints, bounds, and invariants. No code until the formal specification is clear.

## When to Use

- Any problem involving positioning, layout, scaling, or spacing
- Competing constraints that must be satisfied simultaneously
- Mappings between coordinate systems (reference canvas → render canvas)
- Algorithms with bounds or clamp behavior
- Any situation where "it should look good" needs to become "it must satisfy these properties"

## The Process

### Step 1: Identify the Variables

List every variable in the problem. For each one, classify it:

```
Variable: [name]
Type: CONSTANT (hardcoded) | COMPUTED (derived from other variables) | DYNAMIC (known only at runtime)
Value/Formula: [exact value or how it's computed]
Source: [which file/function produces this]
```

### Step 2: Identify the Constraints

List every property the solution must satisfy. Use formal language:

```
Constraint 1: [description]
Formal: [mathematical expression — e.g., "node_width < sqrt(area / N) - margin"]
Type: HARD (must never be violated) | SOFT (desirable but can be relaxed)
What enforces it: [which code/algorithm ensures this]
```

### Step 3: Identify the Optimization Objective

What is the algorithm trying to maximize or minimize?

```
Objective: [e.g., "maximize space utilization while maintaining uniform spacing"]
Formal: [e.g., "maximize min(gap_i) for all adjacent node pairs i"]
Trade-offs: [what gets worse when the objective improves?]
```

### Step 4: Identify the Mappings

If the problem involves transforming between coordinate systems:

```
Domain: [source coordinate system — e.g., "reference canvas, 1920x800"]
Range: [target coordinate system — e.g., "render area, viewport - 48px - explanation height"]
Mapping: [the transformation — e.g., "affine scaling via fitView(padding=0.2)"]
Preserves: [what properties are invariant under the mapping — e.g., "relative spacing ratios, non-intersection of edges"]
```

### Step 5: Identify the Invariants

What properties must hold across all states (e.g., across all layers, all viewport sizes, all input graphs)?

```
Invariant: [description]
Formal: [e.g., "for all layers i, node positions are a subset of the final layer's positions"]
What could break it: [e.g., "recomputing layout per layer instead of slicing"]
```

### Step 6: Specify the Algorithm

Only now write pseudocode. Reference the variables, constraints, and bounds from above:

```
INPUT: [formal input specification]
OUTPUT: [formal output specification]

1. [step] — satisfies Constraint [N]
2. [step] — bounded by [upper/lower bound]
...

POSTCONDITION: [what's true after the algorithm runs]
```

## Example from This Project

The font-sizing algorithm was decomposed as:

```
Variables:
- diagramArea: CONSTANT (1920 * 800)
- nodeCount: COMPUTED (from input graph)
- upperBound: COMPUTED (sqrt(diagramArea / nodeCount) - margin)
- fontSize: COMPUTED (iterative, starts at 18)
- charWidth: COMPUTED (fontSize * 0.6)

Constraints:
1. HARD: node_width < upperBound (nodes must fit in available space)
2. HARD: node_width >= 120px (minimum readability)
3. HARD: node_width <= 35% viewport width (no single node dominates)
4. SOFT: fontSize should be as large as possible (readability)
5. HARD: one global fontSize for all nodes (visual consistency)

Objective: maximize fontSize subject to all constraints

Algorithm:
  for fontSize = 18 down to 8:
    compute all node widths at this fontSize
    if all widths < upperBound: return fontSize
  return 8
```

## Key Principles

- **No code without formal spec.** If you can't state the constraints mathematically, you don't understand the problem well enough to code it.
- **Classify every variable.** Confusing a CONSTANT with a DYNAMIC variable (like the hardcoded viewport dimensions) causes architectural errors that are expensive to fix later.
- **Name the invariants.** If you can't state what must be preserved, you can't verify your code preserves it.
- **Mappings need domain and range.** "fitView scales things" is vague. "fitView maps reference canvas (1920x800) to render area (viewport - 48px - explanation height) via affine scaling preserving aspect ratio and relative spacing" is precise.
- **Competing constraints need explicit trade-offs.** If maximizing space conflicts with uniform spacing, say so. Don't silently optimize one at the expense of the other.