adaptive-routing

Files (2)

• SKILL.md
• composition.md

SKILL.md (first lines)

# Adaptive Routing

This skill is the craft behind `approaches/rubric.md`. `approaches/rubric.md`
holds the rules; this skill says how to apply them.

## The mental model

You are not picking a process. You are computing one. The assessment has
three scored dimensions (`risk`, `familiarity`, `size`), two switches (`goal`,
`urgency`) and any domain labels. The three scored dimensions are three
independent questions, and the delivery approach is their composition -
heavier where they read high, lighter where they read low. A switch leans the
approach towards a reference shape. A domain label raises the floor. The composition is **biased** by
the routing strategies and **bounded** by the routing guardrails, both in
`${CLAUDE_PLUGIN_ROOT}/governance/routing-policy.md` (an unmigrated 5.x project
runs on its own copied `governance/`). The five reference shapes
(quick fix/regular/full/hotfix/spike) are shapes the composition tends to
land near, not boxes to sort into.

## The shipped defaults are enough - you work with them

`/compass:init` is optional. The shipped default preset carries active
default guardrails, default strategies, and a default routing policy, and the
plugin holds their prose in `${CLAUDE_PLUGIN_ROOT}/governance/`. A project's own
changes are entries in its `compass.yml`; `compass policy show` prints what is
in force, except that an unmigrated 5.x project runs on its own copied
`governance/` until `compass policy migrate`. If a project has no `compass.yml` and no project-specific additions,
that is a valid, complete governance state - you route against the shipped defaults <!-- vocabulary-scan: allow - route is a verb here -->
exactly as you would route against an extended set. <!-- vocabulary-scan: allow - route is a verb here -->
"assess and go on day one"
is honest precisely because the defaults are real, in-force content. Never
treat a project without a `compass.yml` as missing a prerequisite.

## Scoring the dimensions - heuristics

**risk** - *consequence, never effort.*
- The sign of `critical`: can this lose data, lose money, breach auth/privacy,
  or resist a clean rollback? If yes, it is critical even if it is one line.
- Critical risk alone does not bring the human sign-off of guardrail 5
  (`G5`); the labels do. When the change is one of them, apply `auth`,
  `payments`, `personal-data` or `migrations` as well as the risk. A
  migration that can lose data is labeled `migrations`, whatever its risk.
- The sign of `trivial`: is the worst case cosmetic, instantly obvious, and
  instantly reversible - with no data, money, auth, or other team touched?
- The common mistake: scoring risk by how hard the change is. A hard
  change can be contained; a trivial-looking change can be critical. Score the
  failure, not the work.

**Familiarity** - *new code, or old code, and is the old code mapped?*
- `brownfield-unmapped` is not a judgment of code quality - it means the
  behavior is not written down as scenarios. At medium size or more, with
  cross-cutting or critical risk, or with a domain label, it triggers a
  routing guardrail floor: `behavior-mapping` must run. Do not skip it. On
  an atomic or small change with trivial or contained risk and no domain
  label, the skill is advice (`RP-ADV-002`).
- "Trivially readable" greenfield or brownfield can be treated as mapped, but
  be honest - "I could figure it out" is not "it is written down."

**Size** - *the dimension humans get wrong most.*
- People under-estimate size far more than they over-estimate it. When
  genuinely torn between two values, take the higher one. Collapsing a stage
  that turned out easy is cheap; discovering during implementation that the
  delivery approach was too light is expensive and demoralizing.
- Anchor on concrete tests: `atomic` is one file and no design decision;
  `medium` has one or two design decisions; `large` has real architecture and
  is plausibly parallelisable.

**The switches** - *`goal` and `urgency` are read, not scored.* Either can
be left out. `goal: exploration` leans towards spike; `urgency: live-defect`
on an atomic or small change leans towards hotfix. Each one you set still
needs a `--justify`. Domain labels need none.

**Goal** - *the actual outcome, not the literal request.*
- Read `intent.md` if it exists. "Add a CSV export" under an `intent.md` that says "let
  finance self-serve" may need filters, scheduling, and permissions - the
  literal request under-describes the intent.
- Role is not scored. An `intent.md` or `positioning.md` on disk adds artifacts
  and gates through the artifact rules. That is the framework working, not overhead.
- One goal value is **exploration** - "I cannot frame this well
  enough to deliver it yet." Exploration composes towards the **spike** delivery approach the
  way live-defect urgency composes towards hotfix. Still score all three
  dimensions; the switch is what selects the shape. See "Composing a spike"
  in `composition.md`.

If you cannot justify a value in one honest line, **ask the human.** An
unjustified guess is worse than a question, every time.

## Composing and constraining

The CLI does both. You score the three dimensions, read the two switches and
the domain labels, and run
`compass approach evaluate --write --justify DIM="<why>"`, with one
`--justify` for each new or changed dimension or switch; it composes the first approach and
applies the floors, caps, immovable gates and artifact rules. That split is the
determinism boundary and it is the point of the whole design: judgment
produces the assessment, mechanism produces the approach.

The detail - including how a spike is composed - is in
`skills/adaptive-routing/composition.md`, for when a result needs
explaining. `--verbose` names every rule that fired.

## The de-scope ledger - the discipline that makes this auditable

Every phase or check the delivery approach collapses or
skips earns a row in the de-scope ledger, and each row needs an explicit
"safe to skip because…" line.

- **A skip with no justification is not allowed. If you cannot justify it, the
  phase runs.** This is non-negotiable - it is what separates "adaptive" from
  "arbitrary."
- Do not copy a reference shape's standing justification without checking it.
  Confirm it actually holds for *this* issue. quick-fix's "requirements review collapsed - the one
  scenario is unambiguous" is only valid if the scenario really is unambiguous.
- Cap-driven reductions are **not** de-scopes. If the `critical` risk
  cap pins the full approach to one worktree, record that as cap-driven in the
  orchestration section, not in the de-scope ledger. The ledger is for things the
  delivery approach chose to skip, not things a guardrail removed.
- The full approach's ledger is empty by definition. If you are writing de-scope
  rows on the full approach, you have mis-composed.

From ayeo-io/compass, Apache-2.0.

More from ayeo-io/compass