diff --git a/lib/effort-shift.md b/lib/effort-shift.md new file mode 100644 index 0000000..71be69b --- /dev/null +++ b/lib/effort-shift.md @@ -0,0 +1,57 @@ +# Effort shift — phase-level reasoning effort on the main loop (BDR-NEXT) + +Shared include, companion of `lib/model-gate.md`: the gate fixes WHICH model +reflects, this include fixes HOW HARD each phase thinks. The rungs are the +user's: low (fix a line, run a script) · medium (day-to-day) · high +(refactor, resisting bug) · xhigh (architecture, audit before validation) · +max (stuck error, judged need). + +## Mechanics (verified on Claude Code 2.1.283) + +- A skill's `effort:` frontmatter applies from the moment it loads to the + end of the turn: on the user's `/skill` and on a `Skill(...)` call by + Claude in an interactive session. Last loaded wins, both directions. The + prompt cache survives a shift. +- Dispatched agents run on their own `effort:` pin, never on a shift. + Unpinned agents inherit the level in force at dispatch. +- Headless sessions (`-p`, `claude agents`, SDK) ignore skill-level effort: + the run stays at the session level. `CLAUDE_CODE_EFFORT_LEVEL` beats every + frontmatter; keep it unset (the session banner warns). + +## Shifters + +`Skill(effort-low)` · `Skill(effort-medium)` · `Skill(effort-high)` · +`Skill(effort-xhigh)` · `Skill(effort-max)`. One tool call, one-line body. +Typed by the user, `/effort-max` is a turn-scoped max: the relaunch lever +after a STOP. `ultrathink` only adds an in-context nudge; the API level +does not move. + +## Wiring — per orchestrator + +1. A dispatch span starts (executor, collector, fan-out) → + `Skill(effort-medium)`. +2. Reflection resumes after a dispatch span (challenge synthesis, verdict, + plan revision) → `Skill(effort-)`. Concretely: + the line before every `lib/challenge-plan.md` call. +3. The bookkeeping tail (memory commit, doc commit) → `Skill(effort-low)`. +4. Escalation → `Skill(effort-max)`, then the skill's own level again once + the diagnosis is produced. Automatic points: verify-secure loop caps + (GATE 0 floor, GATE 1 conformity, GATE 2 security) and ship-feature + STEP 4b. Not automatic, by doctrine: the challenge fail-safe (a mute + challenger is an infrastructure failure) and "gone WRONG → STOP" (STOP + precedes any further reasoning); their STOP text names the level + reached and suggests `/effort-max` for the relaunch. + +## Re-assert + +- After any nested `Skill(...)` whose frontmatter carries a different + effort (feat → commit-change), reload the orchestrator's own level. +- After a prose gate that ends the turn, the resumed turn runs at the + session level. If the resumed phase is reflection, its first step is + `Skill(effort-)`; dispatch and orchestration phases need + nothing. + +## Never + +- A shift never inside a dispatched agent: pins rule there. +- Max is for diagnosis, not for retrying the same fix harder. diff --git a/lib/model-gate.md b/lib/model-gate.md index 97aab7b..d75bd86 100644 --- a/lib/model-gate.md +++ b/lib/model-gate.md @@ -45,3 +45,7 @@ site — `model: "fable"` when the child performs reflection/orchestration on the main loop's behalf (skill-runners), otherwise its complexity tier (opus = dispatched judgment, sonnet = execution/collection, haiku = short mechanical probes). + +Effort is the second axis of the same table (BDR-NEXT): every typed agent +carries an `effort:` pin next to `model:`, and the main loop shifts per phase +through `lib/effort-shift.md`. Nothing dispatched inherits either axis. diff --git a/lib/tests/effort-routing.test.sh b/lib/tests/effort-routing.test.sh index a50db5d..abe0bb6 100755 --- a/lib/tests/effort-routing.test.sh +++ b/lib/tests/effort-routing.test.sh @@ -56,6 +56,13 @@ for s in brainstorming writing-plans; do done has "install-plugins.sh" 'effort: xhigh' +# ── 5) shifter skills + include (spec D4) +for l in low medium high xhigh max; do fm_has_effort "skills/effort-$l/SKILL.md" "$l"; has "skills/effort-$l/SKILL.md" "name: effort-$l"; done +has "lib/effort-shift.md" 'Headless sessions' +has "lib/effort-shift.md" 'Skill(effort-max)' +has "lib/effort-shift.md" 'never inside a dispatched agent' +has "lib/model-gate.md" 'lib/effort-shift.md' + # ── summary (later tasks insert their locks ABOVE this line) printf 'effort-routing census: %d pass, %d fail\n' "$pass" "$fail" [ "$fail" -eq 0 ] diff --git a/skills/effort-high/SKILL.md b/skills/effort-high/SKILL.md new file mode 100644 index 0000000..cbeaeaa --- /dev/null +++ b/skills/effort-high/SKILL.md @@ -0,0 +1,6 @@ +--- +name: effort-high +description: Investigation shift. Deeper reasoning for diagnosis, LOCATE, contract drafting, refactor judgement inside feat, hotfix and bugfix runs. +effort: high +--- +Effort shifted to high for the rest of this turn (lib/effort-shift.md). Continue with the caller's next step. diff --git a/skills/effort-low/SKILL.md b/skills/effort-low/SKILL.md new file mode 100644 index 0000000..16da6a4 --- /dev/null +++ b/skills/effort-low/SKILL.md @@ -0,0 +1,6 @@ +--- +name: effort-low +description: Bookkeeping shift. Lowers reasoning to the cheapest level for the rest of the turn: journal lines, memory commits, capitalize, release bookkeeping, status output. +effort: low +--- +Effort shifted to low for the rest of this turn (lib/effort-shift.md). Continue with the caller's next step. diff --git a/skills/effort-max/SKILL.md b/skills/effort-max/SKILL.md new file mode 100644 index 0000000..06de425 --- /dev/null +++ b/skills/effort-max/SKILL.md @@ -0,0 +1,6 @@ +--- +name: effort-max +description: Escalation shift. Maximum reasoning when a verify or security loop hits its cap, a gate fails twice, or error recovery starts in ship-feature. +effort: max +--- +Effort shifted to max for the rest of this turn (lib/effort-shift.md). Continue with the caller's next step. diff --git a/skills/effort-medium/SKILL.md b/skills/effort-medium/SKILL.md new file mode 100644 index 0000000..6115c86 --- /dev/null +++ b/skills/effort-medium/SKILL.md @@ -0,0 +1,6 @@ +--- +name: effort-medium +description: Orchestration shift. Standard reasoning between two dispatches: read a subagent report, pick the next step, relay a gate verdict, route a branch. +effort: medium +--- +Effort shifted to medium for the rest of this turn (lib/effort-shift.md). Continue with the caller's next step. diff --git a/skills/effort-xhigh/SKILL.md b/skills/effort-xhigh/SKILL.md new file mode 100644 index 0000000..6a60abd --- /dev/null +++ b/skills/effort-xhigh/SKILL.md @@ -0,0 +1,6 @@ +--- +name: effort-xhigh +description: Reflection shift. Deep reasoning for brainstorm, planning, challenge synthesis and audit verdicts before a human validation gate. +effort: xhigh +--- +Effort shifted to xhigh for the rest of this turn (lib/effort-shift.md). Continue with the caller's next step.