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:

json
{
  "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.