docs: which subtask mechanism, for the operator who will not read a skill

The pi-task section already explained the tool in depth. What was missing was
the decision: given a subtask, which mechanism, and why. Adds an end-user
section built on the L0-L4 ladder — the child's context volume is the axis that
explains nearly every observed good and bad behaviour — plus when to use
neither.

Carries the measured cost so the choice is priced, not guessed: 9 runs,
$0.669 total, $0.0027 (fast, refused an over-budget spec in 2.5s) to $0.165
(balanced, 87s). Includes the jq one-liner, and the warning that a crashed run
leaves no result.json — one of the ten here is exactly that, so a rollup must
tolerate missing files rather than assume runs == directories.

Records that fork spend is NOT in that tree (pi-fork aggregates from the
parent's own toolResult entries into the status bar), so the two mechanisms
report spend in two different places and nothing adds them up today.

pi-global-AGENTS.md gets one cheat-sheet bullet so the choice is visible
without loading a skill, and names pi-task as a CLI rather than a tool.

Both files also carry the inverted capability-floor trap ([] = floor on,
null = floor off).
This commit is contained in:
2026-09-08 22:08:03 +02:00
parent 02af927f26
commit adfb553f5c
2 changed files with 96 additions and 0 deletions
+7
View File
@@ -17,6 +17,13 @@ Core triggers (cheat-sheet — the skill has the full guidance):
`deep`=opus (architecture, security, ambiguous debugging). Always state
decision authority, pass verified context, specify the deliverable, ask for
an "unsure about" section. Don't fork trivial or iterative work.
- **Task** (`pi-task`, a CLI at `/opt/pi-toolkit/bin/pi-task` — *not* a tool in
your list, you invoke it with bash) when the child must NOT inherit your
session: any brief containing a prohibition, anything needing a machine-checked
pass/fail envelope, a durable audit trail, or write-boundary enforcement over
named roots. Same ladder, different rung: `fork` is **L4** (child sees your
whole branch), `pi-task` is **L0–L2** (nothing / named files / curated facts).
Pick the lowest rung that can do the job. **L3** (truncated branch) is not built.
- **Recall** (`recall(<12-char-hex-id>)`) before a load-bearing action (edit
code, ship a change, assert a fact) that rests on a `[high]`/`[critical]`
observation or a reflection you did not produce this turn. The compaction