# Effort Protocol

## Purpose

Define how BALDART skills (and, by extension, agents) choose a **reasoning
effort** level: a per-skill *baseline* declared in frontmatter, plus a portable
*inline override* the user can pass at invocation time. The goal is to let
routine skills run lean and reasoning-heavy skills run deep — and to let the
user dial that up or down for a single run without touching config or
environment.

## Scope

**In**: The `effort:` frontmatter key, its baseline-per-skill rubric, the
`effort=<level>` inline-override convention, and how a skill body reacts to it.
**Out**: The native Claude Code effort knob mechanics themselves (slider,
`/effort` command, `CLAUDE_CODE_EFFORT_LEVEL`) — those are documented by Claude
Code, not by BALDART. This protocol only governs how skills *use* them.

## Background — the native knob and its precedence

Claude Code supports an `effort:` frontmatter key on skills and subagents with
values `low | medium | high | xhigh | max` (availability varies by model). When
that skill/subagent is active, its frontmatter effort overrides the session
level. The resolution order, highest first, is:

```
CLAUDE_CODE_EFFORT_LEVEL (env)  >  effort: frontmatter  >  /effort session level  >  model default
```

Two consequences shape this protocol:

1. **The frontmatter sits *above* the session `/effort` level.** So a user
   cannot raise a skill's effort just by running `/effort high` first — the
   frontmatter wins. Only the global env var beats it.
2. **A running skill cannot mutate the effort knob itself.** There is no tool
   for a skill to re-set its own effort mid-run.

Therefore the inline override below does **not** drive the native knob. It is a
**body-level reasoning escalation**: the skill reads the token from its
arguments and engages the corresponding *thinking directive* (`think hard` …
`ultrathink`), which the harness interprets from the text. This is fully
portable — no env var, no consumer config.

## Tiering rubric — choosing a skill's baseline

Assign the frontmatter `effort:` baseline by the skill's dominant cognitive
load, not by how "important" it feels:

| Baseline | When | Examples of work |
|----------|------|------------------|
| `low`    | mechanical, lookup, narration over a deterministic CLI | git plumbing, listing, scaffolding from a fixed template |
| `medium` | standard authoring/implementation/review work | most skills — design, docs, tests, scaffolding with judgment |
| `high`   | deep multi-step reasoning, architecture, end-to-end orchestration, structured planning | PRD authoring, root-cause analysis, deep code review |
| `xhigh` / `max` | reserved — set only when a skill is *consistently* a hard reasoning problem | (rare; prefer raising via inline override instead of pinning the baseline) |

Prefer a conservative baseline plus inline escalation over a permanently high
baseline: a `medium` skill the user can push to `high` for a hard run costs less
across the common case than a skill pinned `high` for every trivial invocation.

## Inline override — `effort=<level>`

**Convention.** The user may pass the token `effort=<low|medium|high|xhigh|max>`
anywhere in the invocation arguments, e.g.:

```
/prd effort=high  Build a referral program with tiered rewards
/simplify effort=low
```

**Parsing contract (every skill that honors overrides MUST follow this):**

1. **Detect once, at kickoff.** Inspect `$ARGUMENTS` for a case-insensitive
   `effort=<level>` token. Model the parse on the existing `-stats` flag in the
   `prd` skill — detect early, before the arguments are consumed as content.
2. **Strip the token.** Remove `effort=<level>` from the argument string before
   using the remainder as the user's actual input (feature text, target, etc.).
   The token is control metadata, never part of the payload.
3. **Validate.** If the level is not one of the five valid values, ignore the
   token (treat as baseline) and note it; do not error out.

## Level → behavior mapping (the body contract)

Once the effective level is known (inline override if present and valid, else
the frontmatter baseline), the skill applies:

| Effective level | Reasoning behavior in the body |
|-----------------|--------------------------------|
| `low`    | No extended thinking. Execute directly and tersely; skip optional deliberation steps. |
| `medium` | Normal operation — the skill's default reasoning. |
| `high`   | Engage **`think hard`** at each decision point / phase boundary. |
| `xhigh`  | Engage **`think harder`** at each decision point / phase boundary. |
| `max`    | Engage **`ultrathink`** at each decision point / phase boundary. |

**Honest limits.** Escalation *upward* is reliable (thinking keywords deepen
reasoning regardless of the frontmatter baseline). De-escalation *below* the
frontmatter baseline is best-effort: the body can skip optional deliberation,
but it cannot lower the native budget the frontmatter already set — only the env
var can. Skills should therefore pick a baseline they are comfortable paying for
on every run.

## The canonical body block

Every skill that ships an `effort:` baseline pastes a short `## Effort` section
into its body (right after `## Project Context`, or after the title for skills
without a Project Context header). Keep it dense — cite this module, do not
re-explain the mapping:

```markdown
## Effort

**Baseline:** `effort: <level>` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.
```

A copy-paste starter lives at `framework/templates/skill-effort.snippet.md`.
The `skill-creator` skill emits both the `effort:` frontmatter key and this
block for every new skill.
