complexity-detection

Complexity Detection

A deterministic scoring rubric. Five axes, 0–4 each, summed to 0–20.

Axes

| Axis | 0 | 1 | 2 | 3 | 4 |

|-----------------------|------------------|-------------------|-------------------|----------------------|---------------------|

| Files touched | 0–2 | 3–5 | 6–10 | 11–20 | 20+ |

| Type | chore / format | refactor | feature | cross-cutting | architectural |

| Judgment required | mechanical | low-ambiguity | medium | high | critical (sec/prod) |

| Cross-component | single module | two modules | three modules | many within one repo | multi-repo |

| Novelty | known pattern | rare pattern | novel | research needed | unknown unknowns |

Total score maps to:

| Score | Depth |

|--------|------------|

| 0 – 6 | quick |

| 7 – 13 | standard |

| 14+ | thorough |

Override signals

Upgrade one step regardless of score when any of these are true:

• Security-sensitive: authentication, authorization, crypto, secrets, PII.
• Data migration that is not reversible.
• Public API shape change (breaking).
• Performance-critical hot path with an existing SLA.

Downgrade one step only when all of these are true:

• Zero new dependencies.
• Existing tests cover the change.
• No user-visible behaviour change.
• Single file, single function.

Per-depth defaults

| Depth | Token budget | Model tier | Review | Tests |

|----------|--------------|------------|-----------|-----------------------------|

| quick | 8 000 | haiku | optional | smoke |

| standard | 20 000 | sonnet | required | unit + integration |

| thorough | 45 000 | sonnet/opus| mandatory | unit + integration + E2E |

These defaults are recorded in .cavekit/config.json under task_budgets

and consumed by the cavekit-router.cjs model router.

How agents score

The ck:complexity subagent (haiku) receives a task description and returns

a JSON blob:

{
  "score": 11,
  "depth": "standard",
  "axes": {
    "files": 2, "type": 2, "judgment": 2, "cross_component": 2, "novelty": 3
  },
  "overrides_applied": []
}

/ck:map calls this agent per task to set depth in the task registry. If

the agent produces a score in the "thorough" band with a novelty of 4 and a

security override, it may return needs_research: true, which /ck:map must

translate into an upstream ck:researcher task dependency before the work

itself.

Integration points

• /ck:sketch — runs complexity scoring on the whole domain to set the kit's

complexity: frontmatter.

• /ck:map — runs it per task to assign depth.
• /ck:make — reads depth to size the task budget and pick the review

intensity.

• ck:complexity agent — pure-haiku worker; does nothing else.

Anti-patterns

• Using one depth for every task in a kit "for consistency." Cost up, signal

down.

• Padding depth to "be safe" — if the budget is oversized, the model wastes

tokens exploring. Right-size, then raise only when verification fails.

• Ignoring overrides — scoring a login flow as "quick" because it touches one

file. Security overrides exist for exactly this reason.