From a8899c6ca71524b817b8e7f0dcaf86cdd6bf32bf Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 05:31:33 +0000 Subject: [PATCH 01/22] docs(topics): lock round-1 brief for pocock-course-lanes interview Six-lane structure, claim-ladder vetting standard, per-lane definition of done, and course-source provenance home locked via /planning:interview; rounds 2+ (ordering, dispatch model, session mechanics) still open. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 91 +++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/topics/pocock-course-lanes/PLAN.md diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md new file mode 100644 index 000000000..4dbdf014c --- /dev/null +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -0,0 +1,91 @@ +# pocock-course-lanes + +Interview in progress (`/planning:interview me`, round 2 open). This Brief persists locked +decisions incrementally so a cloud-session loss never discards resolved branches; the working +ledger lives in the topic's memory slice (`.work/pocock-course-lanes/`, disposable per session). + +## Brief + +### TLDR + +Vet the AI Hero course lessons (plan mode, grilling, compaction, handoff, phase boundaries, +auto-compaction) against this marketplace's plugins in six independent lanes — each lane +interview-first with our own skills, each ending in recorded adopt/reject/track decisions, filed +work items for any plugin change, and a lane summary. Source material is course content — a +distinct source from the already-audited mattpocock/skills repo (SSOT current at v1.2.3 +`@84fdeff`). + +### Goal + +Every opinionated claim in the five pasted lessons is *represented*: mapped to a decision row, a +filed work item, or an explicit not-relevant note — nothing silently dropped. The lanes: + +1. **plan-mode/asset-rush** — his plan-mode critique vs our interview→plan sequencing; audit + whether `lock` / auto-synthesize is a licensed exception or a quiet re-introduction of the + asset rush. +2. **grilling↔interview parity** — course-lesson deltas against `planning:interview` (expected + mostly confirmation; small tree). +3. **compaction doctrine** (merges the Compaction + Auto-Compaction lessons) — + fork-beats-compaction vs his compact-as-default; the `context-guard` evidence-degraded marker + vs his steered-compact-for-QA case; auto-compact stance; `autoCompactWindow` and + compaction-mechanics claims verified against official docs. +4. **handoff** — his 15-line skill vs our save-point engine; the purpose-argument adoption + candidate; handoff-file expiry/accumulation; ephemerality philosophy (OS temp vs memory + tier). +5. **phase-boundaries decision tree** — element-by-element re-audit of the + `session-flow:workflow` continuation router against the *course* version of his tree (the + SSOT audited repo `PHASE-BOUNDARIES.md`, not this lesson); includes subagent-not-a-terminal + and the AFK criterion. +6. **shared vocabulary + provenance** — which dictionary terms (smart zone, primary/secondary + source, AFK, design concept, phase boundary) we adopt as ubiquitous language; establishes + `docs/upstream/aihero-course.md`. Runs last; harvests from all other lanes. + +### Constraints + +- **Interview-first per lane**: each lane opens with `/planning:interview me `, using + marketplace skills throughout (`discovery:explore` / `discovery:research`, + `planning:brainstorm`, discipline skills as fits). +- **Claim ladder** (vetting standard): (i) harness-behavior claims → verified live against + current official docs before being repeated or acted on; (ii) empirical quality claims → + classified folklore-vs-measured, `context-guard`'s measured bands as baseline, his figures + recorded as anchors never adopted as numbers; (iii) design opinions → decided + adopt/reject/track against our plugin philosophy, never "verified" by research. +- **Lanes discuss and decide; they do not implement.** Plugin changes leave the lane as filed + work items and execute via the normal implementation pipeline. +- **Cloud durability**: decisions are promoted into committed-and-pushed artifacts (this file, + the provenance doc, tracker items) the moment they lock; `.work/` is a per-session cache and + is never load-bearing. + +### Acceptance criteria + +- Six lanes each closed with the three fixed outputs: adopt/reject-with-reason/track-on-event + rows in `docs/upstream/aihero-course.md`, work items filed for every decided plugin change, + and a lane summary in the lane's topic slice. +- A coverage index in this topic maps every lesson claim to its disposition (decision row / + filed item / not-relevant note). +- `docs/upstream/aihero-course.md` exists with its own recheck-trigger discipline + (lesson-updated, not release-named) and is cross-linked from + `docs/upstream/mattpocock-skills.md`. + +### Captured assumptions + +- Discussions are user+Claude working sessions; no external participants — hence topic dirs + + tracker items rather than GitHub Discussions. (Round 1 probe drew no contrary constraint; + flip to Discussions if that changes.) + +### Out-of-scope + +- Executing plugin changes inside a lane session. +- Re-auditing the mattpocock/skills repo itself (SSOT current; recheck trigger unchanged). + +### Deferred questions + +- Q6 (arbiter: USER-RESERVED) — lane ordering / priority. +- Q7 (arbiter: USER-RESERVED) — dispatch model: which explore/research runs fire now in + background vs at lane open. +- Q8 (arbiter: USER-RESERVED) — per-session management + durability mechanics (end-of-session + ritual, branch policy for lane docs). + +## Plan + +*(empty — `/planning:plan` fills this after the Brief locks)* From c6455faeb99a623818113290873b827f0b856423 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 05:42:00 +0000 Subject: [PATCH 02/22] docs(topics): record pre-lane upstream recheck for pocock-course-lanes recheck-against-upstream vs mattpocock/skills HEAD 068b6e0: inventory map verified intact (35 skills, mappings confirmed), no new release; unreleased drift noted (invocation-reach invariant hardened via #878/ #880, diagnosing-bugs post-mortem step removed) for lane-6 bookkeeping. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 33 +++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index 4dbdf014c..61254eebc 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -86,6 +86,39 @@ filed work item, or an explicit not-relevant note — nothing silently dropped. - Q8 (arbiter: USER-RESERVED) — per-session management + durability mechanics (end-of-session ritual, branch policy for lane docs). +## Upstream recheck — 2026-08-17 (pre-lane gate) + +`/discipline:recheck-against-upstream` run against mattpocock/skills HEAD `068b6e0` +(2026-08-15) from the audited baseline v1.2.3 `@84fdeff`; shallow clone at +`/workspace/mattpocock/skills` (session-local, disposable). Findings: + +- **Inventory intact**: 35 skills, zero additions/removals/renames — the v1.2 map's + his↔ours rows are structurally accurate; grilling→`planning:interview`, + handoff→`session-flow:handoff`, phase-boundaries→`session-flow:workflow continue` + mappings all confirmed. +- **No new release**: latest tag is still v1.2.3, so the SSOT's release-based recheck + triggers have NOT fired; all drift below is unreleased main. +- **Invocation-reach invariant hardened** (PRs #878/#880, `.agents/invocation.md`): + cross-skill dependencies standardized on "Call the Skill tool with \"name\"" (one skill + per call; his stated reason: higher hit rate than bare `/name` prose, harness-neutral); + user-invoked skills declared unreachable from any skill — preconditions on them must be + phrased "tell the user to run /x". This is the SSOT's *tracked* writing-for-agents + strand: substance has landed on main with changesets, release pending — the tracked + row's trigger will fire on the next release. Portable authoring question for OUR skills + (cross-skill invocation phrasing) → lane 6 candidate. +- **`diagnosing-bugs` dropped its post-mortem step** (Phase 6 "Cleanup + post-mortem" → + "Cleanup"; the "what would have prevented this bug → improve-codebase-architecture" + handoff removed). Relevant to the SSOT's diagnosing-bugs TRACK row when its release + trigger fires. +- **Rest of the diff**: em-dash/phrasing cosmetics (grilling #879, others) — no delta to + our derived skills. +- **Skipped**: nothing — every changed file since baseline was inspected (15 skill files + + `.agents/invocation.md`). + +Verdict: our map and SSOT audit clean at their recorded baseline; no doc corrections +required now. Annotating the two TRACK rows with the landed-but-unreleased evidence is +lane-6 bookkeeping. + ## Plan *(empty — `/planning:plan` fills this after the Brief locks)* From 51d2a90c09aad62ecc3dedf547b952095f95f67a Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 05:52:22 +0000 Subject: [PATCH 03/22] docs(topics): lock full brief for pocock-course-lanes (rounds 2-3) All nine interview questions decided: lane order, dispatch model, cloud-durability mechanics, decision-matrix skill scope (evolve the session-flow continuation router, suggest-by-default), and lane 4's use-case boundary evaluation (session-chain handoff vs his crossing- boundaries taxonomy). Register gate clean (9/9 answered, brief=ok). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 38 +++++++++++++++++++------ 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index 61254eebc..d375fbe3d 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -1,8 +1,9 @@ # pocock-course-lanes -Interview in progress (`/planning:interview me`, round 2 open). This Brief persists locked -decisions incrementally so a cloud-session loss never discards resolved branches; the working -ledger lives in the topic's memory slice (`.work/pocock-course-lanes/`, disposable per session). +Brief locked via `/planning:interview me` (rounds 1–3, all nine questions decided; register +gated clean). The working ledger lives in the topic's memory slice +(`.work/pocock-course-lanes/`, disposable per session — this committed file is the durable +record). ## Brief @@ -31,7 +32,12 @@ filed work item, or an explicit not-relevant note — nothing silently dropped. compaction-mechanics claims verified against official docs. 4. **handoff** — his 15-line skill vs our save-point engine; the purpose-argument adoption candidate; handoff-file expiry/accumulation; ephemerality philosophy (OS temp vs memory - tier). + tier). **Use-case boundary evaluation** (user, round 3): our dominant real use is a hard + session-chain handoff — dumb-zone escape → session-ID chain → whole-picture reconstruction + for retrospectives; functionally a compact-replacement that regathers — while his taxonomy + centers on crossing boundaries (other agent, other repo, colleague, forked side task). + Decide which use cases our handoff officially owns, which route elsewhere, and whether the + session-chain/retrospective use deserves first-class support. 5. **phase-boundaries decision tree** — element-by-element re-audit of the `session-flow:workflow` continuation router against the *course* version of his tree (the SSOT audited repo `PHASE-BOUNDARIES.md`, not this lesson); includes subagent-not-a-terminal @@ -78,13 +84,27 @@ filed work item, or an explicit not-relevant note — nothing silently dropped. - Executing plugin changes inside a lane session. - Re-auditing the mattpocock/skills repo itself (SSOT current; recheck trigger unchanged). +### Decided in rounds 2–3 (previously deferred) + +- Q6 — lane order: handoff → phase-boundaries → compaction → plan-mode → grilling → + vocabulary/provenance. +- Q7 — dispatch: one background `/discovery:research` for the harness-claims bundle + (`autoCompactWindow`, compaction mechanics, plan-mode behavior — verified against current + official docs); `/discovery:explore` and `/planning:brainstorm` fire per lane at open; + nothing else speculative. (The pre-lane inventory recheck already ran — see below.) +- Q8 — durability: git + GitHub are the only durable spine; `.work/` never load-bearing; + every session ends with clean-stop semantics (commit + push + issue updates), never a + machine-local handoff file; one GitHub issue per lane; contract branch PRs when locked, + then one branch + PR per lane. +- Q9 — decision-matrix skill: evolve `session-flow:workflow`'s `continue` router (no new + skill) to consume session history, the overarching plan, work-item state, and the + context-guard zone; **suggest-by-default, autonomous only as an explicit opt-in**, designed + around instruction-audit check I23 (no exit menus injected into model context). This is + lane 5's build deliverable. + ### Deferred questions -- Q6 (arbiter: USER-RESERVED) — lane ordering / priority. -- Q7 (arbiter: USER-RESERVED) — dispatch model: which explore/research runs fire now in - background vs at lane open. -- Q8 (arbiter: USER-RESERVED) — per-session management + durability mechanics (end-of-session - ritual, branch policy for lane docs). +*(none — all nine questions decided)* ## Upstream recheck — 2026-08-17 (pre-lane gate) From 44e9afe57474e8081bd7f6debafeb5444c48f1e3 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 05:55:57 +0000 Subject: [PATCH 04/22] docs(topics): add lane index (#2899-#2904) to pocock-course-lanes contract Six lane issues filed in locked run order; background harness-claims research dispatch recorded with its memory-slice path. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index d375fbe3d..b1facbbeb 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -106,6 +106,21 @@ filed work item, or an explicit not-relevant note — nothing silently dropped. *(none — all nine questions decided)* +## Lane index (filed 2026-08-17, in locked run order) + +| Lane | Issue | Scope | +|------|-------|-------| +| 1 handoff | [#2899](https://github.com/melodic-software/claude-code-plugins/issues/2899) | use-case boundaries, purpose argument, expiry, ephemerality | +| 2 phase boundaries | [#2900](https://github.com/melodic-software/claude-code-plugins/issues/2900) | tree re-audit + context-driven continuation router (build deliverable) | +| 3 compaction doctrine | [#2901](https://github.com/melodic-software/claude-code-plugins/issues/2901) | fork-beats-compaction, auto-compact stance, evidence-degraded marker, harness claims | +| 4 plan-mode | [#2902](https://github.com/melodic-software/claude-code-plugins/issues/2902) | asset-rush critique vs interview-first sequencing, lock-mode audit | +| 5 grilling parity | [#2903](https://github.com/melodic-software/claude-code-plugins/issues/2903) | course-lesson deltas vs planning:interview | +| 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | aihero-course.md, term adoption, SSOT TRACK annotations, coverage index | + +Background research dispatched pre-lane: harness-claims bundle → +`.work/pocock-course-lanes/harness-claims/` (memory tier; re-dispatch `/discovery:research` if +the slice is gone before lane 3/4 consume it). + ## Upstream recheck — 2026-08-17 (pre-lane gate) `/discipline:recheck-against-upstream` run against mattpocock/skills HEAD `068b6e0` From d466d8a983c1b830de271ed5bfc4d56c5fcf248d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 06:08:55 +0000 Subject: [PATCH 05/22] docs(topics): promote verified harness-claims verdicts into the contract Research gated clean, fresh-context verifier applied, C3 cured via the shipped binary's min(1e5).max(1e6) validation schema. Durable verdict table added so lanes 3-5 can cite verified claims (with corroboration labels) even if the memory-tier evidence slice is gone. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index b1facbbeb..b07631719 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -118,8 +118,28 @@ filed work item, or an explicit not-relevant note — nothing silently dropped. | 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | aihero-course.md, term adoption, SSOT TRACK annotations, coverage index | Background research dispatched pre-lane: harness-claims bundle → -`.work/pocock-course-lanes/harness-claims/` (memory tier; re-dispatch `/discovery:research` if -the slice is gone before lane 3/4 consume it). +`.work/pocock-course-lanes/harness-claims/` (memory tier; full evidence + fetch logs live there; +re-dispatch `/discovery:research` if the slice is gone and a lane needs the evidence detail). + +## Harness-claims verdicts (verified 2026-08-17 — durable summary) + +Research run gated clean (artifact + coverage gates exit 0); fresh-context verifier graded +corroboration; parent cured C3 with a binary-schema probe and applied project fit. Verdicts safe +for lanes 3–5 to cite, with corroboration labels: + +| # | Course claim | Verdict | Corroboration | +|---|---|---|---| +| C1–C2 | `autoCompactWindow` exists; controls when auto-compact fires | CONFIRMED | two-pool (docs + binary) | +| C3 | range 100,000–1,000,000 tokens | CONFIRMED | two-pool (docs + binary schema `min(1e5).max(1e6)`) | +| C4 | compaction "seeds a fresh session" | **REFUTED** — same session continues over a structured summary; only fork/`--fork-session` makes a new session ID | two-pool | +| C5 | messages queue during compaction | UNDOCUMENTED — verify empirically before teaching | n/a | +| C6 | `/compact [instructions]` accepts focus instructions | CONFIRMED | single-pool (docs only) | +| C7 | Shift+Tab cycling / `--permission-mode plan` entry | CONFIRMED (no fixed press count) | two-pool | +| C8 | ExitPlanMode approval flow (+ newer EnterPlanMode tool) | CONFIRMED (flow details docs-only) | two-pool | +| C9 | `/plan` views the current plan | PARTIALLY TRUE — `/plan [description]` exists but ENTERS plan mode; no documented command views the plan | absence half two-pool; positive half docs-only | + +Cures for the single-pool rows when convenient: run `/compact ` and `/plan` in a +live interactive session (Tier-0). ## Upstream recheck — 2026-08-17 (pre-lane gate) From bcf4813cde363f3d7b23367a2f951bfd6847f2b1 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 07:33:51 +0000 Subject: [PATCH 06/22] docs(topics): close the pocock-course-lanes interview (user confirmed) Shared understanding confirmed; contract final. Next action recorded: open lane 1 (#2899) in a fresh session. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index b07631719..49a9da22e 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -1,9 +1,11 @@ # pocock-course-lanes Brief locked via `/planning:interview me` (rounds 1–3, all nine questions decided; register -gated clean). The working ledger lives in the topic's memory slice -(`.work/pocock-course-lanes/`, disposable per session — this committed file is the durable -record). +gated clean; **user confirmed the shared understanding 2026-08-17 — interview closed**). The +working ledger lives in the topic's memory slice (`.work/pocock-course-lanes/`, disposable per +session — this committed file is the durable record). Next action: open lane 1 +([#2899](https://github.com/melodic-software/claude-code-plugins/issues/2899)) in a fresh +session via `/work-items:work 2899`. ## Brief From 50347c9984e2664fb561025eb758e3fef55ce36b Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 07:39:11 +0000 Subject: [PATCH 07/22] docs(topics): amend Q8 execution model to single session chain, one PR User-directed post-lock amendment: lanes run as a handoff/clear/resume chain on this branch with dedicated context per lane; all six lanes commit here and one PR ships at the very end (replaces per-lane branches + PRs). Durable-spine and clean-stop discipline unchanged. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index 49a9da22e..a556f45d2 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -95,9 +95,16 @@ filed work item, or an explicit not-relevant note — nothing silently dropped. official docs); `/discovery:explore` and `/planning:brainstorm` fire per lane at open; nothing else speculative. (The pre-lane inventory recheck already ran — see below.) - Q8 — durability: git + GitHub are the only durable spine; `.work/` never load-bearing; - every session ends with clean-stop semantics (commit + push + issue updates), never a - machine-local handoff file; one GitHub issue per lane; contract branch PRs when locked, - then one branch + PR per lane. + every session ends with clean-stop semantics (commit + push + issue updates); one GitHub + issue per lane. + **Amended 2026-08-17 (user, post-lock):** execution model is a single session CHAIN on THIS + branch, not per-lane branches/PRs. Each lane transition is `/session-flow:handoff` → + `/clear` → paste the resume prompt (dedicated context per lane, chain continuity via + `previous_handoff` + session ids — the same generic process this contract was built with: + interview-first, skills, explore/research, decisions committed as they land). All six lanes + commit to `claude/plan-mode-discussion-55kszx`; ONE PR at the very end when all lanes are + closed. The handoff files are a convenience layer inside the container; the committed + contract remains the durable record (clean-stop discipline unchanged). - Q9 — decision-matrix skill: evolve `session-flow:workflow`'s `continue` router (no new skill) to consume session history, the overarching plan, work-item state, and the context-guard zone; **suggest-by-default, autonomous only as an explicit opt-in**, designed From 1d54cd46a1bf6a0b8fcefe902ec6d740626c47b0 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 14:46:08 +0000 Subject: [PATCH 08/22] docs(topics): apply approved audit amendments to pocock-course-lanes brief MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit planning:audit-answers (two fresh-context validators, rationale withheld): Q3 challenged by both — claim-ladder bucket ii rewritten to "instrumented zone readings + declared judgment-default bands" per context-guard's own reader contract; Q6 challenged by one — lane 1 now creates the aihero-course.md skeleton (fixed row schema, divergence-at- re-fetch triggers), lane 6 consolidates. Editorial: six-lesson count, run-order-only lane numbering, Q9 lane label, Q8 prune-gate + resume- degradation obligations recorded; SSOT row-35 correction queued to lane 6. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 82 +++++++++++++++++-------- 1 file changed, 58 insertions(+), 24 deletions(-) diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index a556f45d2..e9827fb65 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -20,33 +20,38 @@ distinct source from the already-audited mattpocock/skills repo (SSOT current at ### Goal -Every opinionated claim in the five pasted lessons is *represented*: mapped to a decision row, a -filed work item, or an explicit not-relevant note — nothing silently dropped. The lanes: +Every opinionated claim in the six pasted lessons is *represented*: mapped to a decision row, a +filed work item, or an explicit not-relevant note — nothing silently dropped. The lanes, +**numbered in locked run order** (matching the lane index — this is the ONLY lane numbering this +contract uses; audit fix 2026-08-17): -1. **plan-mode/asset-rush** — his plan-mode critique vs our interview→plan sequencing; audit - whether `lock` / auto-synthesize is a licensed exception or a quiet re-introduction of the - asset rush. -2. **grilling↔interview parity** — course-lesson deltas against `planning:interview` (expected - mostly confirmation; small tree). -3. **compaction doctrine** (merges the Compaction + Auto-Compaction lessons) — - fork-beats-compaction vs his compact-as-default; the `context-guard` evidence-degraded marker - vs his steered-compact-for-QA case; auto-compact stance; `autoCompactWindow` and - compaction-mechanics claims verified against official docs. -4. **handoff** — his 15-line skill vs our save-point engine; the purpose-argument adoption +1. **handoff** — his 15-line skill vs our save-point engine; the purpose-argument adoption candidate; handoff-file expiry/accumulation; ephemerality philosophy (OS temp vs memory tier). **Use-case boundary evaluation** (user, round 3): our dominant real use is a hard session-chain handoff — dumb-zone escape → session-ID chain → whole-picture reconstruction for retrospectives; functionally a compact-replacement that regathers — while his taxonomy centers on crossing boundaries (other agent, other repo, colleague, forked side task). Decide which use cases our handoff officially owns, which route elsewhere, and whether the - session-chain/retrospective use deserves first-class support. -5. **phase-boundaries decision tree** — element-by-element re-audit of the + session-chain/retrospective use deserves first-class support. **Also creates the + `docs/upstream/aihero-course.md` skeleton** (audit amendment A2 — see below). +2. **phase-boundaries decision tree** — element-by-element re-audit of the `session-flow:workflow` continuation router against the *course* version of his tree (the SSOT audited repo `PHASE-BOUNDARIES.md`, not this lesson); includes subagent-not-a-terminal - and the AFK criterion. + and the AFK criterion. Carries the effort's build deliverable (the context-driven router — + Q9). +3. **compaction doctrine** (merges the Compaction + Auto-Compaction lessons) — + fork-beats-compaction vs his compact-as-default; the `context-guard` evidence-degraded marker + vs his steered-compact-for-QA case; auto-compact stance; `autoCompactWindow` and + compaction-mechanics claims verified against official docs. +4. **plan-mode/asset-rush** — his plan-mode critique vs our interview→plan sequencing; audit + whether `lock` / auto-synthesize is a licensed exception or a quiet re-introduction of the + asset rush. +5. **grilling↔interview parity** — course-lesson deltas against `planning:interview` (expected + mostly confirmation; small tree). 6. **shared vocabulary + provenance** — which dictionary terms (smart zone, primary/secondary - source, AFK, design concept, phase boundary) we adopt as ubiquitous language; establishes - `docs/upstream/aihero-course.md`. Runs last; harvests from all other lanes. + source, AFK, design concept, phase boundary) we adopt as ubiquitous language; owns the + coverage index, term adoption, and final consolidation of `docs/upstream/aihero-course.md` + (skeleton created by lane 1 per A2). Runs last; harvests from all other lanes. ### Constraints @@ -55,9 +60,14 @@ filed work item, or an explicit not-relevant note — nothing silently dropped. `planning:brainstorm`, discipline skills as fits). - **Claim ladder** (vetting standard): (i) harness-behavior claims → verified live against current official docs before being repeated or acted on; (ii) empirical quality claims → - classified folklore-vs-measured, `context-guard`'s measured bands as baseline, his figures - recorded as anchors never adopted as numbers; (iii) design opinions → decided - adopt/reject/track against our plugin philosophy, never "verified" by research. + classified against **instrumented zone readings plus `context-guard`'s declared + judgment-default bands (named provenance)** — his figures recorded as anchors never adopted + as numbers *(amended 2026-08-17 per audit A1: the prior "measured bands as baseline" wording + was refuted by both validators — context-guard's own reader contract states the shipped band + thresholds are "declared judgment defaults", not measurements; only the zone readings are + measured. The honest distinction vs his figures is provenance-and-tunability, not + measurement)*; (iii) design opinions → decided adopt/reject/track against our plugin + philosophy, never "verified" by research. - **Lanes discuss and decide; they do not implement.** Plugin changes leave the lane as filed work items and execute via the normal implementation pipeline. - **Cloud durability**: decisions are promoted into committed-and-pushed artifacts (this file, @@ -71,9 +81,13 @@ filed work item, or an explicit not-relevant note — nothing silently dropped. and a lane summary in the lane's topic slice. - A coverage index in this topic maps every lesson claim to its disposition (decision row / filed item / not-relevant note). -- `docs/upstream/aihero-course.md` exists with its own recheck-trigger discipline - (lesson-updated, not release-named) and is cross-linked from - `docs/upstream/mattpocock-skills.md`. +- `docs/upstream/aihero-course.md` exists with its own recheck-trigger discipline — triggers + phrased as **divergence-at-re-fetch** (a read-time re-fetch finds a lesson no longer matching + the record; the form `docs/conventions/upstream-drift/README.md` sanctions), never bare + "when the lesson updates" — and is cross-linked from `docs/upstream/mattpocock-skills.md`. + Skeleton (row schema + trigger form, inherited from the upstream-drift four-part record and + the SSOT attribution-table shape) is created by lane 1; lane 6 owns the coverage index, term + adoption, and final consolidation (audit amendment A2). ### Captured assumptions @@ -105,16 +119,36 @@ filed work item, or an explicit not-relevant note — nothing silently dropped. commit to `claude/plan-mode-discussion-55kszx`; ONE PR at the very end when all lanes are closed. The handoff files are a convenience layer inside the container; the committed contract remains the durable record (clean-stop discipline unchanged). + **Audit-discovered obligations (2026-08-17, both validators):** (a) the CI + `contract-slice-prune-gate` red-lines any PR whose net diff adds or edits under + `docs/topics/**` — the ONE final PR must therefore carry a prune commit removing the parent + topic dir and every opened lane slice, their substance preserved via PR-body paste + + pointers per the topic-docs contract-slice lifecycle (durable outcomes live on in + `aihero-course.md`, the issues, and the PR body — the git+GitHub spine claim still holds); + (b) the paste-resume directive references a `.work/` handoff file a recycled container + loses — expected degradation: resume from this committed contract + the lane issue instead. - Q9 — decision-matrix skill: evolve `session-flow:workflow`'s `continue` router (no new skill) to consume session history, the overarching plan, work-item state, and the context-guard zone; **suggest-by-default, autonomous only as an explicit opt-in**, designed around instruction-audit check I23 (no exit menus injected into model context). This is - lane 5's build deliverable. + lane 2's build deliverable (phase-boundaries — run-order numbering per the lane index). ### Deferred questions *(none — all nine questions decided)* +### Audit record (2026-08-17, `/planning:audit-answers` — user approved) + +Two fresh-context validators independently re-examined all nine decisions with the +recommendation rationale withheld. Merged outcome: Q1, Q2, Q4, Q5, Q7, Q8, Q9 CONFIRMED with +evidence; Q3 CHALLENGED by **both** validators (the "measured bands" premise — amended per A1, +in Constraints); Q6 CHALLENGED by one (the `aihero-course.md` creation contradiction — amended +per A2: lane 1 creates the skeleton with fixed row schema, lane 6 consolidates). Editorial +fixes applied in the same pass: six-lesson count, run-order-only lane numbering, Q9's lane +label, divergence-at-re-fetch trigger phrasing, and the Q8 prune-gate + resume-degradation +obligations. Lane-6 bookkeeping gained one item: correct the SSOT row-35 "our measured bands +stand" overclaim to match context-guard's own "declared judgment defaults" language. + ## Lane index (filed 2026-08-17, in locked run order) | Lane | Issue | Scope | From ffb014590cfcf9ac58568f7189c5b4a70912fa18 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 15:10:18 +0000 Subject: [PATCH 09/22] docs(upstream): close aihero lane 1 (handoff) with provenance rows and summary Creates docs/upstream/aihero-course.md (skeleton per audit amendment A2: four-part row schema and divergence-at-re-fetch trigger form fixed at creation) with lane 1's nine decision rows; cross-links it from the mattpocock-skills SSOT; adds the lane summary slice. Decisions: use-case UNION with routing signals (#2956), purpose argument adopted as trailing free text (#2955), OS-temp placement and silent expiry rejected (confirms the #1477 finding-4 verdict), do-not-duplicate rule adopted, model invocation kept, 15-line minimalism rejected. New gap filed: context-guard zone capture silent in cloud sessions (#2957). Refs #2899. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-lane-1/SUMMARY.md | 62 ++++++++++++++++++++++++ docs/upstream/aihero-course.md | 70 ++++++++++++++++++++++++++++ docs/upstream/mattpocock-skills.md | 4 ++ 3 files changed, 136 insertions(+) create mode 100644 docs/topics/pocock-lane-1/SUMMARY.md create mode 100644 docs/upstream/aihero-course.md diff --git a/docs/topics/pocock-lane-1/SUMMARY.md b/docs/topics/pocock-lane-1/SUMMARY.md new file mode 100644 index 000000000..33be3a05e --- /dev/null +++ b/docs/topics/pocock-lane-1/SUMMARY.md @@ -0,0 +1,62 @@ +# Lane 1 summary: handoff (issue #2899) + +First of six vetting lanes under the `pocock-course-lanes` contract +(`docs/topics/pocock-course-lanes/PLAN.md`). Closed 2026-08-17. Scope: the course handoff lesson +and upstream `skills/productivity/handoff/SKILL.md` (read at `068b6e0`) against our +`session-flow` save-point engine. + +## Decisions (register Q10 through Q19; rows in `docs/upstream/aihero-course.md`) + +- **Use-case boundary (Q10):** UNION. Our session-chain use (dumb-zone escape, session-ID chain, + retrospective reconstruction) becomes a named first-class use case alongside his + crossing-boundaries taxonomy (other agent, other repo, colleague, forked side task). + Deliverable is routing signals for which form to use when, filed as #2956. +- **Purpose argument (Q11/Q16):** ADOPT as optional trailing free text, + `[file|prompt] [topic] [purpose...]`. Emphasis-only tailoring; never drops sections; the + resume-prompt shape (find-handoff detection contract) is untouched; Original-goal immutability + wins over a contradicting purpose. Filed as #2955. +- **Placement and expiry (Q12/Q13):** keep `/handoffs/` (memory tier), REJECT OS + temp, accumulation by design, cleanup is user-controlled removal and never silent expiry. + Confirms the #1477 finding-4 rejection rather than reversing it (retention is load-bearing for + retro chain-walk and find-handoff recovery). +- **Worktree caveat (Q17):** a handoff written inside a worktree dies with + `git worktree remove`; acceptable only when the worktree completes as a merged PR unit; + otherwise write from the main checkout or rely on clean-stop's preserve-before-remove step. + Wording lands via #2956. +- **Promote-on-value (Q18):** default no uplift; promote the content, never the file. Durable + value moves into committed artifacts (topic contract, issue, PR body); no handoff file is ever + committed. Via #2956. +- **Do-not-duplicate rule (Q14):** ADOPT explicitly in the skill body, mirroring upstream + wording. Via #2956. +- **Model invocation (Q15):** REJECT his `disable-model-invocation: true`. Keep model-invocable + under strict trigger discipline; proactive handoff prompting and instrument-triggered forks + depend on it, and user-only skills lose skill-to-skill reach. +- **Minimalism and parity rows:** 15-line minimalism REJECTED (the engine is accumulated + incident response; prompt-only mode is our minimal tier); suggested-skills section and + redaction COVERED at parity or stronger. + +## Work items filed (changes execute outside the lane) + +- #2955: purpose argument across the save-point engine (behavior change). +- #2956: routing-signals table, do-not-duplicate rule, worktree caveat, promote-content rule + (skill-body and reference wording). +- #2957: context-guard zone capture is statusline-teed and silent in cloud/headless sessions + (surfaced while deciding Q15; verified live in this container). + +## Parked to other lanes + +- Lane 2 (#2900): the non-interactive continuation pattern the user described (worker emits the + handoff at a fork point; an orchestrator, standing in for the human, kills the worker and + seeds a fresh agent with the resume prompt). This is the continuation-router build's + territory. +- Lane 3 (#2901): zone-signal availability in cloud (see #2957) affects the compaction-doctrine + discussion. + +## Process notes + +- Grounding: fresh-context explore of the session-flow handoff engine + (verified PASS, 14/14 sampled claims confirmed) plus the prior inline explore; #1477 + finding-4 rationale fetched verbatim before deciding the expiry axis. +- This lane also created the `docs/upstream/aihero-course.md` skeleton per audit amendment A2 + (row schema and divergence-at-re-fetch trigger form fixed at creation); lane 6 (#2904) owns + the coverage index and consolidation. diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md new file mode 100644 index 000000000..d262f3b45 --- /dev/null +++ b/docs/upstream/aihero-course.md @@ -0,0 +1,70 @@ +# Upstream source: AI Hero course lessons (Matt Pocock) + +Provenance record for everything in this marketplace vetted against the AI Hero course lessons +(Matt Pocock's course on working with coding agents). This is a distinct source from the +[mattpocock/skills](https://github.com/mattpocock/skills) repository, whose record is the SSOT at +[mattpocock-skills.md](mattpocock-skills.md): the course is prose lessons with no releases, tags, +or changelogs, so it needs its own recheck regime. Where a lesson restates something the skills +repo also ships, the row cites both bases. + +Vetting ran as six lanes on the `pocock-course-lanes` contract +(issues [#2899](https://github.com/melodic-software/claude-code-plugins/issues/2899) through +[#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904)). Lanes decide but +never implement: every ADOPT row points at a filed work item; changes execute through the normal +pipeline. + +## Row schema (fixed at creation, per amendment A2) + +Each row is a four-part record per +[docs/conventions/upstream-drift/README.md](../conventions/upstream-drift/README.md): the claim, +the basis it was derived against, the as-of date, and a recheck trigger. Columns: + +| Lesson claim | Ours | Verdict | Reasoning, basis, as-of | + +Verdicts: **ADOPT** (with the filed work item), **REJECT** (with reason), **TRACK** (on a named +event), **COVERED** (already present at parity or stronger, with evidence). + +**Recheck trigger, all rows (fixed at creation):** divergence at re-fetch. A read-time re-fetch +of the row's basis (the lesson text, or the upstream artifact the row cites) finds the source no +longer matching the record; the divergence, never the lookup, fires the row, and a firing follows +the upstream-drift maintenance procedure. A row may state a stronger trigger inline; bare "when +the lesson updates" is not a valid trigger form here because the course publishes no observable +update signal. + +## Lane 1: handoff (issue #2899, decided 2026-08-17) + +Basis for all lane 1 rows: the course handoff lesson as captured in the lane contract +(`docs/topics/pocock-course-lanes/PLAN.md`, 2026-08-17) plus upstream +`skills/productivity/handoff/SKILL.md` read live at `068b6e0` (2026-08-17). Our side read live +the same day: `plugins/session-flow/skills/handoff/SKILL.md`, +`plugins/session-flow/reference/save-point.md`, `plugins/session-flow/reference/structure.md` +(exploration verified by a fresh-context agent, 14/14 sampled claims confirmed). + +| Lesson claim | Ours | Verdict | Reasoning, basis, as-of | +|---|---|---|---| +| Handoff serves crossing boundaries: another agent, another repo, a colleague, a forked side task | `session-flow:handoff` "When to invoke" list; "sharing state with another session or machine" bullet | **ADOPT** (as a union) | User decision (#2899 comment 1): our dominant session-chain use (dumb-zone escape, session-ID chain, retrospective reconstruction) is named first-class ALONGSIDE his taxonomy, not instead of it; the deliverable is explicit routing signals for which form to use when. Filed: [#2956](https://github.com/melodic-software/claude-code-plugins/issues/2956). As-of 2026-08-17 | +| A single purpose argument ("What will the next session be used for?") tailors the doc to the next session's focus | No purpose argument; surface is `[file\|prompt] [topic]`; intent lives in the verbatim Original goal section | **ADOPT** | Shape decided in-lane: optional trailing free text `[file\|prompt] [topic] [purpose...]`; tailors emphasis only (Resumption brief lead, Suggested skills selection, Remaining-actions order); never drops sections; never alters the resume-prompt shape (find-handoff detection contract); Original-goal immutability wins on conflict. Filed: [#2955](https://github.com/melodic-software/claude-code-plugins/issues/2955). As-of 2026-08-17 | +| Save the handoff to the OS temp directory, not the current workspace | `/handoffs/` (default `.work/handoffs/`), memory tier, self-gitignored | **REJECT** | Placement is load-bearing for us: retro's `previous_handoff` chain-walk, find-handoff recovery, and the cross-machine origin line all depend on workspace placement; OS-temp volatility is the failure class upstream's own corpus hit (temp-sweep in mattpocock/skills#306 context, durability ask in #482). His self-cleaning benefit is replaced by user-controlled removal. Confirms the #1477 finding-4 verdict (PR #1560). As-of 2026-08-17 | +| Lifecycle: temp placement self-cleans, so files never accumulate | Accumulation by design ("Multiple handoffs accumulate in the directory, fine", structure.md); nothing expires files | **REJECT** (silent expiry) | User decision (#2899 comment 1): handoffs stay primarily ephemeral in a location we control; cleanup is user-controlled removal, never silent expiry or OS cleanup. Retention is load-bearing (chain-walk, recovery, carry-forward), which is the recorded #1477 finding-4 rationale (issue comment 5084364831); this lane confirms rather than reverses it. Promote-content-never-file rule and worktree caveat filed: [#2956](https://github.com/melodic-software/claude-code-plugins/issues/2956). As-of 2026-08-17 | +| Do not duplicate content captured in other artifacts (specs, plans, ADRs, issues, commits, diffs); reference by path or URL | Partial: "Summarize; never transcribe" (File roles), "reference it rather than restating" (Decisions); no general rule | **ADOPT** | User decision (#2899 comment 1): state the general rule explicitly in the skill body, mirroring upstream's wording; explicit over implicit. Filed: [#2956](https://github.com/melodic-software/claude-code-plugins/issues/2956). As-of 2026-08-17 | +| Include a suggested-skills section naming what the next agent should invoke | Suggested skills is a mandatory section of the handoff structure | **COVERED** | Present at parity or stronger (presence-gated per-skill suggestions, structure.md mandatory section set). As-of 2026-08-17 | +| Redact sensitive information (API keys, passwords, PII) | Mandatory redaction step with the git-remote-userinfo strip exception | **COVERED** | Ours is the more specified form of the same rule. As-of 2026-08-17 | +| `disable-model-invocation: true`: only the user triggers a handoff | Model-invocable under strict trigger discipline (instrument signal, observed drift, user report; never self-estimated budget) | **REJECT** | User decision (round 5): proactive "we should hand off now" prompting is wanted, and instrument-triggered forks plus skill-to-skill reach (his own invocation-reach invariant makes user-only skills unreachable from other skills) depend on model invocation. Token cost of carrying triggers acknowledged and accepted. Known gap: the zone instrument is statusline-teed and silent in cloud/headless sessions, filed as [#2957](https://github.com/melodic-software/claude-code-plugins/issues/2957). As-of 2026-08-17 | +| A handoff skill needs only ~15 lines | Three-layer engine (skill, shared save-point engine, structure doc) | **REJECT** | The engine's size is accumulated incident response, not up-front design: claim provenance and constraint re-scan from his own failure corpus (#1477, PR #1560), loop re-arm (#1447/#1515), rooted resume paths (#1780), Original-goal immutability (#1906), background-continuation disambiguation (#2115). Our minimal tier already exists as prompt-only mode (writes no file, documented retro-gap cost). As-of 2026-08-17 | + +House decisions recorded alongside the rows (not lesson claims): the worktree caveat (a handoff +written inside a worktree dies with `git worktree remove`; acceptable only when the worktree +completes as a merged PR unit) and the promote-content-never-file rule (durable value is promoted +into committed artifacts; no handoff file is ever committed). Both in +[#2956](https://github.com/melodic-software/claude-code-plugins/issues/2956). + +## Lanes 2 through 5 + +Rows land here as each lane closes: phase boundaries (#2900), compaction doctrine (#2901), +plan mode (#2902), and interview parity (#2903). + +## Coverage index and consolidation + +Owned by lane 6 ([#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904)): +the per-lesson coverage index mapping every claim to its disposition, dictionary-term adoption, +and final consolidation of this document. diff --git a/docs/upstream/mattpocock-skills.md b/docs/upstream/mattpocock-skills.md index ac0b39ab8..1c579b63f 100644 --- a/docs/upstream/mattpocock-skills.md +++ b/docs/upstream/mattpocock-skills.md @@ -14,6 +14,10 @@ baseline in `review`) are not provenance records and stay in place. attribution table below — re-audit the affected row(s). Release notes name skills explicitly (`gh release view -R mattpocock/skills`). +**Sibling source:** the AI Hero course lessons (same author, prose lessons with no release +signal) are recorded separately in [aihero-course.md](aihero-course.md), under its own +divergence-at-re-fetch recheck regime. + ## Attribution table | Upstream skill / source | Ours | Relation | What was taken / rejected | From 64fe359e66aa59911002735accdef48fdcb3c136 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 17:40:43 +0000 Subject: [PATCH 10/22] docs(upstream): close aihero lane 2 (phase boundaries) with rows and router design Lane 2 (#2900) decisions: ten provenance rows for the course phase-boundaries lesson, the Q20-Q23 register (AFK edge adopt-modified, informant-seam inputs, two-tier autonomy, eval and drift items), and the lane summary. Work items filed: #2971 (router evolution), #2972 (router evals), #2973 (reader-contract drift). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-lane-2/SUMMARY.md | 66 ++++++++++++++++++++++++++++ docs/upstream/aihero-course.md | 43 ++++++++++++++++-- 2 files changed, 106 insertions(+), 3 deletions(-) create mode 100644 docs/topics/pocock-lane-2/SUMMARY.md diff --git a/docs/topics/pocock-lane-2/SUMMARY.md b/docs/topics/pocock-lane-2/SUMMARY.md new file mode 100644 index 000000000..0f5b4752d --- /dev/null +++ b/docs/topics/pocock-lane-2/SUMMARY.md @@ -0,0 +1,66 @@ +# Lane 2 summary: phase boundaries (issue #2900) + +Second of six vetting lanes under the `pocock-course-lanes` contract +(`docs/topics/pocock-course-lanes/PLAN.md`). Closed 2026-08-17. Scope: the course lesson +"Clear, Compact, Handoff, Or Subagent" against the `session-flow:workflow` continuation router +(`context/continuation.md`), plus the effort's build deliverable: the Q9 context-driven router +evolution. The lane ran across two sessions (a stale resume prompt caused one hop through the +lane-1 handoff; state was reconstructed from the ledger and the verified explore slice with no +loss). + +## Decisions (register Q20 through Q23; rows in `docs/upstream/aihero-course.md`) + +- **Subagent terminal / AFK criterion (Q20, user-delegated):** ADOPT modified. The AFK question + becomes a router edge pointing to `session-flow:orchestrate` for the spawn-brief decision; + delegation stays non-terminal so orchestrate keeps spawn ownership and + continue-in-background's explicit-intent launch gate is untouched (the router suggests, never + launches). Filed in #2971. +- **Router inputs (Q21):** via existing informants. Plan, work-item state, and session history + arrive through presence-gated pointers to orient's read patterns, reconcile's liveness answer, + the workflow checklist, and the work-item seam, exactly as the zone seam consumes + context-guard's reader contract. No duplicated reads; zone stays word-only. +- **Autonomy meaning (Q22):** both tiers. Top level: per-invocation explicit opt-in + (`continue auto` or explicit user words; never a standing config) executes the routed + mechanism. Worker level: the orchestrator relay parked from lane 1 (worker emits its handoff + at a fork point; the orchestrator retires the worker and seeds a fresh agent with the resume + prompt) is codified as the autonomous tier for delegated work. I23-clean: initiative comes + from the user's opt-in or the orchestrator, never injected context. +- **Eval and hygiene debt (Q23):** file both. Router eval coverage (zero evals, one + already-regressed ordering invariant) as #2972; the context-guard + `reference/reader-contract.md:185-207` pre-0.5.0 advisory-injection drift (verifier finding) + as #2973. + +## Fact-graded dispositions (claim ladder, no user decision owed) + +- His "compact seeds a new session" wording: REJECT as a harness claim (verdict C4, two-pool + REFUTED; same session continues over a structured summary). +- Numeric anchors 30k/80k/150k and the ~150k smart zone: recorded as folklore anchors with named + provenance, never adopted as numbers (claim-ladder bucket ii, amendment A1). +- Handoff-narrowing: REJECT, confirming the lane-1 UNION decision and the prior repo-tree + rejection. +- Boundary-only discipline, ordered first-yes-wins, clear-when-disposable, compact-last with + steering, reasoning-verbatim continue criterion, primary-to-secondary trade: COVERED at parity + or stronger. + +## Work items filed (changes execute outside the lane) + +- #2971: the Q9 router evolution (informant-seam inputs, AFK edge, suggest-by-default, + two-tier autonomy, I23 reconciliation). +- #2972: router eval coverage, to land with or before #2971. +- #2973: context-guard reader-contract advisory-injection section update to the 0.5.0 + audience split. + +## Parked to other lanes + +- Lane 6 (#2904): dictionary-term adoption surfaced here (primary/secondary source, smart zone, + AFK, phase boundary) and the SSOT "measured bands" wording correction (already on lane 6's + list per amendment A1). + +## Process notes + +- Grounding: fresh-context explore of the router and its siblings + (`.work/pocock-lane-2/`, gate exit 0, verifier PASS 23/23 with parent write-back); course + lesson cached verbatim in the same slice; harness claims cited from the durable verdict table + in the lane contract rather than re-researched. +- The verifier's new find (reader-contract drift) became #2973, demonstrating the + write-back loop paying for itself. diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index d262f3b45..4f195c657 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -58,10 +58,47 @@ completes as a merged PR unit) and the promote-content-never-file rule (durable into committed artifacts; no handoff file is ever committed). Both in [#2956](https://github.com/melodic-software/claude-code-plugins/issues/2956). -## Lanes 2 through 5 +## Lane 2: phase boundaries (issue #2900, decided 2026-08-17) -Rows land here as each lane closes: phase boundaries (#2900), compaction doctrine (#2901), -plan mode (#2902), and interview parity (#2903). +Basis for all lane 2 rows: the course lesson "Clear, Compact, Handoff, Or Subagent" (verbatim +paste, 2026-08-17, session cache). Our side read live the same day: +`plugins/session-flow/skills/workflow/context/continuation.md`, the workflow SKILL.md, the +sibling continuation skills, and `plugins/context-guard/reference/reader-contract.md` +(exploration verified by a fresh-context agent, 23/23 sampled claims confirmed). The repo-side +tree (`PHASE-BOUNDARIES.md`) was previously audited in the SSOT (ask-matt row, +[mattpocock-skills.md](mattpocock-skills.md)); rows below cite that audit where the course +restates it. + +| Lesson claim | Ours | Verdict | Reasoning, basis, as-of | +|---|---|---|---| +| The five-option decision belongs at the phase boundary only; work the questions in order; they are subjective judgment calls | Router runs "at a phase boundary"; compact edge is boundary-only; "ask in order, first yes wins"; mid-stage with a healthy window the step is skipped; judgment tests govern degraded or unknown zones | **COVERED** | Parity: boundary-only trigger, ordered first-yes-wins discipline, and the judgment-call framing were all recorded at parity in the prior repo-tree audit; the course version adds nothing new here. As-of 2026-08-17 | +| Five options: continue, clear, compact, handoff, subagent | Derived outcome set of six terminals (continue, `/clear`, `session-flow:handoff`, `session-flow:continue-in-background`, `session-flow:clean-stop`, `/compact`); subagent delegation is non-terminal via `session-flow:orchestrate` | **COVERED** (stronger) | Our outcome set is derived from installed mechanisms, adding clean-stop (machine going away) and user-gated background continuation his tree lacks; the subagent difference is decided in the AFK row below. As-of 2026-08-17 | +| Compact "compresses your context and seeds a new session with it" | No such claim anywhere in the family; fork-vs-compaction tradeoff owned by handoff | **REJECT** (as a harness claim) | Refuted harness claim: verdict C4 in the pocock-course-lanes contract (two-pool, 2026-08-17): compaction continues the SAME session over a structured summary; only fork or `--fork-session` makes a new session id. The lesson's operational advice (compact last, steer the summary) is unaffected and covered below. As-of 2026-08-17 | +| Continue first when the next phase needs this phase as a primary source; the implementation wants the grilling reasoning verbatim | Q2 prefers continue "when the next stage consumes this stage's reasoning verbatim; a summary of the reasoning is not the reasoning" | **COVERED** (previously ADOPTED) | The course version confirms the criterion already adopted from the repo tree in the v1.2 sync (PR #2082); ours zone-gates it (never overrides a degraded zone, where handoff remains the route). As-of 2026-08-17 | +| Numeric anchors: 30k tokens after grilling means continue; 80k with a small task fits; 150k means leave; smart zone budget ~150k | No inlined numbers; the router consumes only the context-guard zone word per its reader contract; band values live in the contract as declared judgment defaults | **REJECT** (as adopted numbers) | Claim-ladder bucket ii (amendment A1): his figures are recorded as folklore anchors with named provenance, never adopted as numbers; our baseline is instrumented zone readings plus context-guard's declared judgment-default bands. Confirms the repo-tree rejection of the ~150k figure without repeating its "measured bands" overclaim (lane-6 correction pending). As-of 2026-08-17 | +| Clear when the context is irrelevant and disposable; the cheapest move, takes zero time | Q3: `/clear`, "the cheapest reset, asked before any writing mechanism: capturing state nothing needs is pure cost" | **COVERED** | Parity; ours orders it after the hard-fact questions (machine going away, explicit background request) with each edge's ordering purpose stated. As-of 2026-08-17 | +| Handoff is narrow: only for passing to another agent, another directory or colleague, or forking a mid-phase side task | Q4 handoff covers state-must-survive as well as boundary crossing; the session-chain use is named first-class per lane 1 | **REJECT** (the narrowing) | Confirms both the lane-1 UNION decision (issue 2899) and the prior repo-tree rejection: the narrowing contradicts our fork-beats-compaction stance, where handoff replaces compaction in a deep window with nothing travelling at all. Routing-signals deliverable already filed: [#2956](https://github.com/melodic-software/claude-code-plugins/issues/2956). As-of 2026-08-17 | +| AFK criterion: if the task can run away-from-keyboard with no steering, spawn a subagent (a tree terminal) | Delegation is deliberately non-terminal, owned by `session-flow:orchestrate`; autonomous feasibility lives in Q1's feasibility half | **ADOPT** (modified) | Q20 decision (user-delegated to the session, 2026-08-17): adopt the AFK question as a router edge that points to orchestrate for the spawn-brief decision; delegation stays non-terminal so orchestrate keeps spawn ownership, and continue-in-background's explicit-intent launch gate is untouched because the router suggests and never launches. Filed: [#2971](https://github.com/melodic-software/claude-code-plugins/issues/2971). As-of 2026-08-17 | +| Compact is the default, not the first reach; it sits at the bottom; pass it a steering instruction | Q5 fallthrough: `/compact` "at a phase boundary only, with a steering hint naming what the summary must keep", ordered last deliberately | **COVERED** (stronger) | Parity or stronger: ours adds the least-intelligent-point warning and defers the full tradeoff to handoff's "Fork beats compaction when the window is deep". `/compact [instructions]` support is verdict C6, CONFIRMED docs-only single-pool. As-of 2026-08-17 | +| Every move except continue converts a primary source into a secondary source; pay the lossiness only when staying costs more | Q2's reasoning-verbatim criterion embodies the same trade; handoff owns the fork-vs-compact statement of it | **COVERED** | The concept is present without the dictionary vocabulary; adopting the terms (primary and secondary source, smart zone, AFK, phase boundary) is lane-6 territory ([#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904)). As-of 2026-08-17 | + +House decisions recorded alongside the rows (not lesson claims), all from the lane interview +(Q21-Q23, 2026-08-17): the Q9 router evolution consumes plan, work-item state, and session +history via presence-gated pointers to the existing informants (orient's read patterns, +reconcile's liveness answer, the workflow checklist, the work-item seam), never duplicated +reads; autonomy is two-tier (a per-invocation explicit `auto` opt-in at top level, mirroring +continue-in-background's explicit-words precedent and never a standing config, plus the +orchestrator relay codified as the autonomous tier for delegated work) with the I23 +reconciliation stated in the build item; the router's missing eval coverage and the +context-guard reader-contract drift are filed as their own items. Filed: +[#2971](https://github.com/melodic-software/claude-code-plugins/issues/2971), +[#2972](https://github.com/melodic-software/claude-code-plugins/issues/2972), +[#2973](https://github.com/melodic-software/claude-code-plugins/issues/2973). + +## Lanes 3 through 5 + +Rows land here as each lane closes: compaction doctrine (#2901), plan mode (#2902), and +interview parity (#2903). ## Coverage index and consolidation From da87537a37b1bec813d7540c89f3ac739ec2249d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 20:15:44 +0000 Subject: [PATCH 11/22] docs(topics): add public-repo content boundary to pocock-course-lanes The repo is public (the v1.2 map's "private marketplace" line is stale; queued to lane 6). Course lesson text is memory-tier only, never committed; provenance rows paraphrase and cite. Lesson sources for lanes 1-5 recorded at their .work paths with the re-paste fallback. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index e9827fb65..e23941ef8 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -73,6 +73,14 @@ contract uses; audit fix 2026-08-17): - **Cloud durability**: decisions are promoted into committed-and-pushed artifacts (this file, the provenance doc, tracker items) the moment they lock; `.work/` is a per-session cache and is never load-bearing. +- **PUBLIC-REPO content boundary (added 2026-08-17):** this repository is PUBLIC (verified via + the repo listing; note the v1.2 map's "Claude-only private marketplace" line is stale — a + lane-6 bookkeeping correction). Course lesson text is paid content and must NEVER be + committed: lesson sources live only in the memory tier + (`.work/pocock-course-lanes/lessons/01`–`05`, numbered by lane run order; lane 6 harvests and + has no single lesson). If the slice is gone when a lane opens, ask the user to re-paste that + lane's lesson — never fetch-and-commit it. Provenance rows in `aihero-course.md` PARAPHRASE + and cite lesson claims; they never reproduce lesson content wholesale. ### Acceptance criteria From 2b3e87db298f2787babcc15cd292f56563a55cda Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 20:24:51 +0000 Subject: [PATCH 12/22] docs(topics): commit lane lesson sources to the topic slice (user decision) User authorized committing the AI Hero lesson texts (framing around his MIT-licensed public skills): five attributed source files under lessons/, numbered by lane run order, durable across containers and pruned with the slice in the final PR. Contract constraint amended accordingly; aihero-course.md rows still paraphrase and cite. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 18 +- .../lessons/01-handing-off.md | 120 +++++++++ .../02-clear-compact-handoff-subagent.md | 123 +++++++++ .../03-compaction-and-auto-compaction.md | 243 ++++++++++++++++++ .../lessons/04-why-plan-mode-sucks.md | 110 ++++++++ .../lessons/05-grill-execute-clear.md | 112 ++++++++ 6 files changed, 718 insertions(+), 8 deletions(-) create mode 100644 docs/topics/pocock-course-lanes/lessons/01-handing-off.md create mode 100644 docs/topics/pocock-course-lanes/lessons/02-clear-compact-handoff-subagent.md create mode 100644 docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md create mode 100644 docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md create mode 100644 docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index e23941ef8..4b2149b55 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -73,14 +73,16 @@ contract uses; audit fix 2026-08-17): - **Cloud durability**: decisions are promoted into committed-and-pushed artifacts (this file, the provenance doc, tracker items) the moment they lock; `.work/` is a per-session cache and is never load-bearing. -- **PUBLIC-REPO content boundary (added 2026-08-17):** this repository is PUBLIC (verified via - the repo listing; note the v1.2 map's "Claude-only private marketplace" line is stale — a - lane-6 bookkeeping correction). Course lesson text is paid content and must NEVER be - committed: lesson sources live only in the memory tier - (`.work/pocock-course-lanes/lessons/01`–`05`, numbered by lane run order; lane 6 harvests and - has no single lesson). If the slice is gone when a lane opens, ask the user to re-paste that - lane's lesson — never fetch-and-commit it. Provenance rows in `aihero-course.md` PARAPHRASE - and cite lesson claims; they never reproduce lesson content wholesale. +- **Lesson-source handling (amended 2026-08-17, user decision):** this repository is PUBLIC + (the v1.2 map's "Claude-only private marketplace" line is stale — a lane-6 bookkeeping + correction). The user reviewed the flag and authorized committing the lesson texts — they are + framing around his MIT-licensed public skills — so the sources live TRACKED at + `docs/topics/pocock-course-lanes/lessons/01`–`05` (numbered by lane run order; lane 6 + harvests and has no single lesson), attributed to aihero.dev in each header, durable across + containers for the life of the effort, and PRUNED with the topic slice in the final PR (the + contract-slice-prune-gate enforces this), so they never merge to the default branch. + Provenance rows in `aihero-course.md` still paraphrase and cite rather than reproduce — + that doc is durable-tier and permanent. ### Acceptance criteria diff --git a/docs/topics/pocock-course-lanes/lessons/01-handing-off.md b/docs/topics/pocock-course-lanes/lessons/01-handing-off.md new file mode 100644 index 000000000..79ef9fa91 --- /dev/null +++ b/docs/topics/pocock-course-lanes/lessons/01-handing-off.md @@ -0,0 +1,120 @@ + + +# Handing Off + + + Start the lesson: the `/handoff` skill added to `.agents/skills/` + + +In the previous exercise, I showed you how [compaction](https://www.aihero.dev/ai-coding-dictionary/compaction) works: you take one [session](https://www.aihero.dev/ai-coding-dictionary/session)'s [primary source](https://www.aihero.dev/ai-coding-dictionary/primary-source), summarize it into a [secondary source](https://www.aihero.dev/ai-coding-dictionary/secondary-source), and seed a new session with it. + +Compaction, though, has some constraints. It can only compact within the same directory, and it can only compact within the same [agent](https://www.aihero.dev/ai-coding-dictionary/agent). + +For instance, if we did some implementation with Claude and wanted to [hand off](https://www.aihero.dev/ai-coding-dictionary/handoff) to another AI agent like Codex to review it, how would we do that with compaction? We can't. + +## The /handoff skill + +There is one way to do it though, and I encounter this situation so often that I made a [skill](https://www.aihero.dev/ai-coding-dictionary/skill) for it. + +The theory is straightforward: instead of compacting inside the agent (in memory), you create a `handoff.md` file, a markdown file. That markdown file is totally portable. You can do anything you like with it. + +- Feed it into Codex +- Pass it to an agent in another directory +- Send it to a colleague +- Use it to hand off a side task you discovered mid-feature + +One really great situation is when you're working on a feature, you notice a random bug that's unrelated to what you're building, and you want to fix it later in a separate session. You can just create a [handoff artifact](https://www.aihero.dev/ai-coding-dictionary/handoff-artifact) and come back to it. + +### Looking at the skill + +First, run `npm run reset` and choose the handoff skill lesson from the list. + +If we look inside the skill directory, we have a `/handoff` skill. Like most of my skills, it's pretty short. + +```markdown +Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace. +``` + +One useful feature here is that it saves to the temporary directory of the user's OS. This means these handoff documents are designed to be ephemeral. They're not going to be saved locally in your project, and they won't be stored in any memory. They will be deleted when your computer resets, or whenever the OS decides to clear the temporary directory. + +(OS stands for operating system: Windows, Mac, Linux, whatever.) + +## Using handoff in practice + +Let me show you how this works. I'm going to resume a previous session and work with the star rating review system. + +We're at around 89k [tokens](https://www.aihero.dev/ai-coding-dictionary/token), which might be a good moment to hand off. To use the `/handoff` skill, I'm going to run the command and pass it a reason: + +``` +/handoff pass to Codex to review +``` + +Just like with compact, we give the `/handoff` skill a reason for the handoff. This tells it the purpose of the next session. + +It comes back and [requests permission](https://www.aihero.dev/ai-coding-dictionary/permission-request) to write to the temporary directory. Perfect. + +Now we can see the handoff file. It's a really nice, detailed secondary source of all the things we might need to review. It looks fairly similar to the compacted documents we saw before: nice and detailed, with lots of file references and everything else. + +The handoff document includes: + +- What the feature is +- Files to review (with git status / git diff instructions) +- Key decisions or bugs fixed mid-session +- Known pre-existing issues (not part of this change) +- Verification already done +- Project conventions the diff should conform to +- Review angles worth probing +- Suggested skills for the next session + +The way I would seed this into a new session is to open it in a separate window. I've just run `/clear`, so I've got a totally empty session. Now I can use the `@` symbol to reference the file: + +``` +@/tmp/handoff-course-star-ratings-review.md +``` + +Once this gets seeded, it gets immediately read into the [context window](https://www.aihero.dev/ai-coding-dictionary/context-window) and it's ready for review. + +I'll just cancel out of that because I don't actually want it to do the review right now. + +## /handoff vs. Compact + +That's how the `/handoff` skill works. It's really nice for: + +- Passing work to separate agents +- Saving a document you can send to a colleague +- Handing off to another agent in a different repo to fix a bug you encountered + +It's just like compaction, except a little bit more flexible and a little bit more involved. + +I wouldn't say that handoff is a total replacement for compaction. Here's when to use each: + +| When | Use | +| ------------------------------------------------ | ------------------------------------------------------------------ | +| Staying in the same directory | Compaction | +| Retaining context of the previous conversation | Compaction | +| Don't care about retaining previous conversation | Compaction (especially because you can queue up messages after it) | +| Passing to a different agent | `/handoff` | +| Handing off to another repo | `/handoff` | +| Sending to a colleague | `/handoff` | + +Compaction is still really good. `/handoff` is nice too, but the linking to the next conversation is a little bit more involved, and it's only really useful if you're getting something out of it. + +We're going to do a full comparison in the next lesson. Nice work, and I'll see you there. + + + + + diff --git a/docs/topics/pocock-course-lanes/lessons/02-clear-compact-handoff-subagent.md b/docs/topics/pocock-course-lanes/lessons/02-clear-compact-handoff-subagent.md new file mode 100644 index 000000000..78ef2b10c --- /dev/null +++ b/docs/topics/pocock-course-lanes/lessons/02-clear-compact-handoff-subagent.md @@ -0,0 +1,123 @@ + + +# Clear, Compact, Handoff, Or Subagent + +In the coding [sessions](https://www.aihero.dev/ai-coding-dictionary/session) we've done so far with [agents](https://www.aihero.dev/ai-coding-dictionary/agent), you might have noticed that they break down into pretty discrete chunks. We've had a [grilling](https://www.aihero.dev/ai-coding-dictionary/grilling) phase, then an implementation phase, and then a QA phase at the end. We [compacted](https://www.aihero.dev/ai-coding-dictionary/compaction) before we started QA-ing. + +These phases are loosely defined. They're really just chunks of work within a coding session. Each phase is composed of two parts: the actual phase itself (the running of the grilling, implementation, or QA), and the boundaries between them. + +The boundaries are really important. They represent a decision point where you're deciding what to do with the session at each phase boundary. + +## Understanding Phase Boundaries + +By the time we finished grilling, we were only at about 30k [tokens](https://www.aihero.dev/ai-coding-dictionary/token). It made sense to continue directly on with the implementation. That meant the implementation could rely on the [primary source](https://www.aihero.dev/ai-coding-dictionary/primary-source) of the grilling without any kind of [secondary source](https://www.aihero.dev/ai-coding-dictionary/secondary-source) lossiness there. + +But by the time we finished implementation and we wanted to QA it, we decided to compact it. We'd used up our [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) really, and we wanted to get rid of all the cruft and just use the good stuff for the QA. + +The way to come to those decisions isn't particularly obvious. You actually have **five choices** for things you can do at these phase boundaries. + +## Your Five Options + +| Option | What It Does | +| ------------ | --------------------------------------------------------------- | +| **Continue** | Stay in the current session, no context switch needed | +| **Clear** | Totally clear your context window and start fresh | +| **Compact** | Compress your context and seed a new session with it | +| **Handoff** | Create a markdown file summarizing the session to pass anywhere | +| **Subagent** | Spawn a subagent to handle the task and report back | + +Wielding these five options is not trivial. I've created a decision tree to help you navigate them. + +## The Decision Tree: Start At The Top + +When you've reached the end of a phase and you're not quite sure what to do, you start here. + +### Question 1: Can You Continue? + +**Does it make sense to continue in the current session?** + +This is a fairly rich decision in itself. Between grilling and implementation, it obviously makes sense to continue because we've got that rich primary source that we need. We don't want to discard it for when we get to the implementation. + +You may also want to continue if you just have enough smart zone budget left. If you're at 80k tokens maybe and you know the task is pretty small and is going to fit inside the smart zone, then yes, you can just continue. + +If you decide that you **do need to do something**, then we need to go down this little decision tree. + +### Question 2: Is Your Context Irrelevant To The Next Task? + +If you need to do something, ask yourself: **is all the information in this session totally disposable?** + +In other words, all the explorations, the decisions that were made in that session - is it totally irrelevant to what comes next? + +**If yes, clear your context window.** Clearing is the most efficient path if you can take it because it takes zero time. You're just deleting information. Then you have the most smart zone available to you. You're going back to a blank slate. + +However, if you clear the context with relevant information inside, you're losing information that might have been useful later. Imagine if I cleared rather than compacted when I went to QA. This means that the QA would know absolutely nothing about the implementation, which maybe is okay - it could figure it out from the git commits. But it would also lose all the information from the grilling as well. + +It would lose the reasoning behind the decisions that I had made. Both phases were important for the QA that then followed. So clearing just wasn't an option. + +**If no, your context is relevant.** Move to the next question. + +### Question 3: Do You Need To Hand Off? + +This is specifically about the handoff [skill](https://www.aihero.dev/ai-coding-dictionary/skill). The handoff skill is relatively narrow compared to the other options. + +You'll only need to do the handoff when you need to: + +- Pass work to another agent +- Pass work to another directory or another colleague +- Fork off a side task you discovered mid-phase without derailing the current session + +For instance, you might find something during grilling that also needs to be tackled. You can just hand off to another session while you're doing that. + +**If yes, use handoff** (`/handoff`). **If no, move to the next question.** + +### Question 4: Can The Task Be Done AFK? + +**[AFK](https://www.aihero.dev/ai-coding-dictionary/afk) means away from keyboard.** You're not touching the keyboard. You're just watching the agent go and you cannot intervene. + +This means the task is well-scoped. The agent can do it without needing your intervention at all. + +Let's imagine we wanted to do an [automated review](https://www.aihero.dev/ai-coding-dictionary/automated-review) on the implementation before [human review](https://www.aihero.dev/ai-coding-dictionary/human-review) got there. Automated review is where you send the agent into the codebase and you get it to look at the changes and check if it's broken anything or done anything weird. + +We could have compacted at this point (we're at 150k tokens from the implementation), then run the review in the main session. But since the human isn't needed for automated review, we might as well run it in a subagent. That means we just get it to run in its own context window. We don't affect the main session. + +This is a really common pattern for automated review, and it's one that we'll touch on in this course. + +**If yes, spawn a subagent.** **If no, move to the final option.** + +## The Default: Compact + +This is the bottom of the decision tree. When your context is relevant, when you want to do something with the context, and you can't continue, when you don't need to use a handoff, and when the task needs to be done with you there - then compact is the solution. + +Compact compresses your context window and seeds a new session with the good stuff. You keep what matters and discard what doesn't. + +## These Are Subjective Decisions + +These questions are not objective. There's a little bit of subjectivity, a little bit of taste in there too. You will find your own answers to these questions as you continue your work and continue working with agents. + +But I hope this concept of phases, of what you do at phase boundaries, really sinks in. This is one of the fuzziest decisions, the most interesting decisions you're going to make when you're AI coding. It's one that demands a lot of discussion and a lot of wisdom. + +[Join the Discord](https://aihero.dev/discord) and talk about these situations. Use this shared language when you discuss different scenarios. + + + + + + diff --git a/docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md b/docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md new file mode 100644 index 000000000..7a90dbf45 --- /dev/null +++ b/docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md @@ -0,0 +1,243 @@ + + +# Compaction + +When building features with an [agent](https://www.aihero.dev/ai-coding-dictionary/agent), you eventually reach the end of the "[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)" - the part of the [context window](https://www.aihero.dev/ai-coding-dictionary/context-window) where your [model](https://www.aihero.dev/ai-coding-dictionary/model) works best. What happens next? + +If you continue in that same [session](https://www.aihero.dev/ai-coding-dictionary/session), results [degrade](https://www.aihero.dev/ai-coding-dictionary/attention-degradation) slowly. The agent sends all previous [tokens](https://www.aihero.dev/ai-coding-dictionary/token) with every request. Those tokens are cheaper because they've been [cached](https://www.aihero.dev/ai-coding-dictionary/cache-tokens), but you're still operating in a higher latency, less capable environment. + +More importantly: how many of those tokens are actually useful? A lot of them are just noise from the work itself - file reads, file writes, files in different states as you move through the project. + +## The Naive Solution: Starting Fresh + +One option is to totally [clear](https://www.aihero.dev/ai-coding-dictionary/clearing) the [context](https://www.aihero.dev/ai-coding-dictionary/context) and start a new session. But this comes with a hidden cost. + +When you clear the context, the agent loses crucial understanding from the initial conversation. It has to re-explore and re-establish everything it knew before. You might prompt it like this: + +``` +we are going to do QA on the stuff that's literally just been worked on. +Can you go and explore it so you understand the reasons behind its existence? +``` + +The agent will do that exploration, but it's also lost some of the crucial reasoning from your initial conversation. + +It can re-explore the code and re-read what you built, but that re-exploration is lossy - you've lost a lot of the actual _why_ behind what you constructed. + +## Introducing Compaction + +This is where [**compaction**](https://www.aihero.dev/ai-coding-dictionary/compaction) comes in. Instead of clearing the context entirely, compaction takes the context from your current session, squeezes it down, and seeds a fresh session with it. + +Think of it like a [hand-off](https://www.aihero.dev/ai-coding-dictionary/handoff) between sessions that you control - similar to using a [sub-agent](https://www.aihero.dev/ai-coding-dictionary/subagent), but in reverse. The session history is summarized, then it seeds a fresh session you can continue working from. + +| Approach | Tokens | Quality | Downsides | +| ------------------------ | ------ | --------------------------- | ----------------------------------------------- | +| Continue current session | 156k+ | Full context, lots of noise | High latency, dumb zone results | +| Clear and start fresh | ~5k | Clean slate | Must re-explore everything, lossy understanding | +| Compaction | ~28k | Summarized context | Lossy compression, secondary source | + +Compaction saves re-exploration. Without it, you'd spend a ton of tokens just re-discovering context you'd already established. + +## How Compaction Works in Practice + +In your agent, you run the `/compact` command with a summarization instruction: + +``` +/compact Yeah, we're going to do some QA in this area. +``` + +This instruction matters. The thing doing the summarization is a language model, so it needs context to highlight relevant information. Your instruction doesn't need to be detailed - one sentence is often enough. + +When you launch the compaction, the agent shows a UI where it's compacting the conversation. + +Here's a useful tip: you can queue messages inside the compaction UI. Once compaction finishes, your queued message runs automatically - no need to sit around waiting. + +### What Gets Preserved + +When compaction finishes, it outputs a summary with several key elements: + +- **Primary request and intent** - what you originally asked for +- **Full agreed [spec](https://www.aihero.dev/ai-coding-dictionary/spec)** - all the decisions you confirmed +- **Key technical concepts** - important domain knowledge +- **File references** - pointers to critical files, plus some files retained verbatim +- **Errors and fixes** - what went wrong and how you solved it +- **Problem solving** - your approach and reasoning +- **All user messages** - everything you said +- **Pending tasks** - work still to do + +Here's what the token compression looks like: + +From the original session with ~156,000 tokens, the compaction summary reduced it to around 28,300 tokens. That 150k becomes 30k - giving you plenty of room back in the smart zone. + +``` +Model: claude-opus-4 +Tokens: 28.3k / 1m (3%) + +| Category | Tokens | Percentage | +|-------------------------|--------|------------| +| System prompt | 2.9k | 0.3% | +| System tools | 4.5k | 0.5% | +| Messages | 20.7k | 2.1% | +| Free space | 971.7k | 97.2% | +``` + +For example, a line from the summary might read: + +``` +- app/lib/comments.ts (new): MIN_COMMENT_LENGTH = 1, + MAX_COMMENT_LENGTH = 5000 (client-safe, mirrors ratings.ts) +``` + +This is extremely dense compression of everything you did in that previous session. + +## The Trade-off: Information Loss + +Compaction isn't without downsides. Think of it using historical terms: + +- The [**primary source**](https://www.aihero.dev/ai-coding-dictionary/primary-source) is your initial session - the record from people there at the time +- The **secondary source** is the summary - a historical summary, which is lossy compression of the primary source + +Compaction is the first hand-off mechanism you've seen that preserves context between sessions. But all hand-off mechanisms suffer from the same issue: whenever you create a secondary source, you lose information. + +However, you're gaining efficiency. Here's the trade-off: + +| Approach | Information | Noise | Maneuverability | +| ----------------------------- | ----------- | ----- | --------------- | +| Primary source (continue) | Full | Lots | Limited | +| Secondary source (compaction) | Lossy | Less | More room | + +If you continue with the primary source, you have all the information but probably along with a lot of noise. If you use the secondary source, you have more room to maneuver and less space being used up, but you might lose some of the nuances from the primary source. + +## When Compaction Shines + +However, in the exact situation where you want to do QA on a finished piece of work, compaction is a cast-iron great place to use it. You're not re-implementing. You're not making architectural decisions. You're validating something that's already complete. + +This is an introduction to compaction. You'll see how it compares to clearing and other mechanisms in upcoming lessons. + + + + + + +# Auto-Compaction + +You might be wondering: what happens if you try to push past the [context window](https://www.aihero.dev/ai-coding-dictionary/context-window) limit? Opus 4.8, which is what we're using, has 1 million [tokens](https://www.aihero.dev/ai-coding-dictionary/token) of context. What happens if you go for 1 million and 1? + +If you send a [request](https://www.aihero.dev/ai-coding-dictionary/model-provider-request) to Anthropic that has 1,000,001 tokens in it, you will get an error. The [model](https://www.aihero.dev/ai-coding-dictionary/model) simply cannot process that many tokens. + +Your [agent](https://www.aihero.dev/ai-coding-dictionary/agent) has built-in protections against hitting this hard limit. When you get to a certain point, it will [automatically compact](https://www.aihero.dev/ai-coding-dictionary/autocompact) your [session](https://www.aihero.dev/ai-coding-dictionary/session). + +## Finding Auto-Compact in Your Agent + +You can see this setting in your agent by typing the `/config` command and then searching for `auto-compact`. The matching settings appear at the top. + +The relevant configuration shows: + +``` +Auto-compact: true +``` + +with a description: "Automatically compact conversation when context fills" + +Auto-compaction exists in every single agent [harness](https://www.aihero.dev/ai-coding-dictionary/harness), because every harness has this problem. Every harness has a window in which, if you hit it, the system will pause your session and automatically compact what's in there. + +You used to be able to see this by typing `/context` to view the autocompact buffer inside the context breakdown. But it appears that teams have made it slightly more obscure. + +## Customizing the Auto-Compact Window + +One interesting thing you can do is customize the auto-compact window itself. Inside your `~/.claude/settings.json` file, you can adjust when auto-compaction fires: + +```json +{ + "autoCompactWindow": 250000 +} +``` + +If you want it to automatically compact after 250,000 tokens, you can totally do that. The setting accepts values from 100,000 to 1,000,000 tokens. + +## The Promise: Context Management Goes Away + +The promise of auto-compaction is really quite nice. Imagine a world where you didn't have to think about phase boundaries at all, didn't have to think about the [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone), didn't have to think about [context](https://www.aihero.dev/ai-coding-dictionary/context) at all. + +This decision tree would simply not be needed: + +- Continue the session +- Clear the session +- Hand it off +- Spawn a subagent +- Compact + +You would just auto-compact at the right moments. In fact, you will see a lot of people online saying that auto-compaction just handles all of their problems for them. + +## Why Auto-Compaction Is Actually Really Difficult + +However, it turns out that auto-compaction is an incredibly difficult problem to solve. And it's really, really painful to get wrong. + +### Compacting in the Middle of a Phase Is Dangerous + +Think back to a typical session with a [grilling](https://www.aihero.dev/ai-coding-dictionary/grilling) phase and an implementation phase, separated by a phase boundary. + +If someone forced you to put in a compact somewhere in this session, you would probably say that the safest place to do it would be at the phase boundary, between grilling and implementation. + +But what would happen if you compacted in the middle of a grilling session? You'd be working with only a summary of what had been done before. What I've found when this has occasionally happened is that the agent really does lose its way quite often and just forgets stuff you were talking about just before. + +The same is true in implementation, and it's often worse: + +- The agent will often lose its way completely +- The second half of the implementation phase will use a totally different coding style from the first part +- It will lose its train of thought and forget features it was supposed to implement + +### You Lose Control of the Handoff + +There's another problem: when you automatically compact, there's no opportunity for you to say what you should compact and what the intention of the next session is going to be. + +The little summarization notes that you pass to the [handoff document](https://www.aihero.dev/ai-coding-dictionary/handoff-artifact) or you pass to `/compact` are really key for getting it to compact the correct things. Auto-compaction gives you no equivalent hook. + +## The Better Approach: Human Control + +So will mid-phase compacting always be bad? Probably not, although it feels like it's going to be a hard problem no matter what the model is. It's a very tricky, difficult problem to solve. + +My attitude in general is to increase the skill of the human instead of increasing the demand on the harness and the model. I tend to prefer the human having control of this decision tree, rather than just passing it off to the agent. + +It's a one-time learning curve that the human has to go through, and it will just get you better and better results the better you get at it. More of your sessions are going to be in the smart zone and you're going to have better control. + +## The Real Rule + +In my opinion, if you're hitting the auto-compact buffer, if you're automatically compacting, then something is probably going wrong. + +Instead, you should be in control. You should be the one deciding whether you continue the session, clear the session, hand it off, spawn a subagent, or compact. + +When you own that decision, you get better code. + + + + + + diff --git a/docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md b/docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md new file mode 100644 index 000000000..3a3520d24 --- /dev/null +++ b/docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md @@ -0,0 +1,110 @@ + + +# Why Plan Mode Sucks + +In our previous lesson, we saw how an [agent](https://www.aihero.dev/ai-coding-dictionary/agent) behaves under normal conditions. The results were not great. What really troubled me was the pattern: the agent prompted, explored the codebase, then immediately began implementing. + +There was no verification with us about whether it was building the right thing. There was no attempt at alignment between the AI and us. + +In that run, we were actually lucky. The agent built the thing we wanted pretty well. There were some issues and a critical bug, but it worked. However, this rush to create an asset is really dangerous in AI and something I always try to slow down. + +## Plan mode: a buffer between exploration and implementation + +Most agents ship with something called [**plan mode**](https://www.aihero.dev/ai-coding-dictionary/agent-mode). The intention of plan mode is to have a planning [session](https://www.aihero.dev/ai-coding-dictionary/session) before any work is done. This planning session creates a plan document that you read, review, and then decide whether to continue (maybe with modifications). Only when you're happy with the plan do you proceed. + +Let me show you how this works in practice. + +```bash +npm run reset +``` + +This resets the codebase to the main branch, clearing out the existing course rating implementation from the previous lesson. + +Next, I'll open up the agent and enable plan mode by cycling through the [permission modes](https://www.aihero.dev/ai-coding-dictionary/permission-mode) using `shift+tab` until the input footer reads "plan mode on". + +Now I'll paste in the original prompt: + +``` +I would like to create a course review system where students can review courses by leaving a star rating. We don't want to add written reviews, just star rating. These reviews will then be visible everywhere that courses are visible. We want to show the average rating on the courses in the list page and on the course page itself. +``` + +After submitting, the agent should explore the codebase to understand the structure, then come back with a plan. This plan mode acts like a little buffer between exploration and implementation. A moment where we can align before continuing. + +## The plan it generates + +Now the agent has finished exploration and is writing the plan. This is roughly how most agents handle plan mode. The behavior is similar across different tools. + +I can view the plan by typing `/plan`: + +This gives me a quite detailed output of everything the agent is going to do, along with some key decisions: + +- **One user per rating per course** - makes sense +- **Averages are computed on read** - looks fine +- **Empty state:** courses with zero ratings show "No ratings yet" rather than zero stars - makes sense +- **Who can rate:** enrolled users only - makes sense + +## The critical issue: plan mode is still rushing + +Here's the problem: instead of rushing to create an implementation, the agent rushed to create a plan which reads exactly like the implementation would. + +It's given me the exact implementation it's going to do: + +- Database table structure +- Service names and functions +- Component names +- Route modifications +- Testing strategy + +It's still rushing to create an asset. The plan is the asset now, not the code. + +## The root cause: sycophantic trait of agents + +This feeling of premature completion, of rushing to get to the end, is a [sycophantic](https://www.aihero.dev/ai-coding-dictionary/sycophancy) trait of agents. When you tell it you want to produce something, it will go produce that thing. + +It won't necessarily stop to make sure it's done the legwork to ensure you're aligned on how it should look. + +This is really bad because it leads to a failure mode that happens constantly: the agent builds the wrong thing. + +On a relatively simple feature like course ratings, it doesn't matter too much. But on a more complicated feature, it really matters. + +## What this means in practice + +Imagine if a human developer behaved this way. They just said, "Yes, I know how to build that," and they went ahead and did it. There would be no alignment whatsoever. There would be no sense of a shared understanding being developed. + +In the book ["The Design of Design"](https://www.amazon.co.uk/Design-Essays-Computer-Scientist/dp/0201362988) by Frederick P. Brooks Jr. (the author of "The Mythical Man-Month"), there's a concept called the [**design concept**](https://www.aihero.dev/ai-coding-dictionary/design-concept). + +A design concept is not an asset. It's the concept floating around in the room when humans are designing something. Everyone has a slightly different idea of it, but as conversations develop and you work towards understanding what you're building, everything starts to sharpen. + +In both plan mode and the version we saw before, there's no design concept here. There's no moment to check in with each other to make sure we're actually aligned on what we're building. + +We got an okay result the first time we ran it, but I guarantee on more complex features, this would quickly go wrong. + +## A different approach + +The approach I've designed tries to sidestep this issue. It takes away the sycophantic asset rush. What you end up with, I hope, is a feeling of greater alignment with the agent - like you're both on the same page. + +I'm going to explain that in the next lesson. + + + + + + diff --git a/docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md b/docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md new file mode 100644 index 000000000..bb489b526 --- /dev/null +++ b/docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md @@ -0,0 +1,112 @@ + + +# The Grill-Execute-Clear Loop + + + Start the lesson: the `/grill-me` skill added to `.agents/skills/` + See my solution: lesson comments built from the grilled spec + + +Before you start building features, you need to understand what you're building. Most developers skip this step and rush straight into coding, which leads to wasted time and solutions that don't quite fit the problem. + +The `/grill-me` [skill](https://www.aihero.dev/ai-coding-dictionary/skill) forces you to pause. It interviews you relentlessly until you reach a shared understanding of what you're trying to build. Only then do you implement. + +This is the grill-execute-clear loop. You [grill](https://www.aihero.dev/ai-coding-dictionary/grilling) until you understand. You execute the solution. You [clear](https://www.aihero.dev/ai-coding-dictionary/clearing) your mind and move to the next feature. + +## The Grilling Skill + +The grilling skill works by building a design tree. Every decision branches into the decisions that hang off it. + +It asks questions in rounds. The frontier is every decision whose prerequisites are already settled. The skill asks the whole frontier at once, then waits for your answers. + +As you answer, the frontier expands. New questions unlock. Previously blocked decisions become answerable. + +The [session](https://www.aihero.dev/ai-coding-dictionary/session) ends when the frontier is empty: every branch visited, nothing left silently assumed. Only then should you implement. + +## Your Task + +Build lesson comments for the course platform. Students and instructors should be able to comment on individual lesson pages. + +Imagine browsing to a lesson like "Connecting to a Database" or "CRUD Operations". On that page, students should be able to ask questions, share insights, and discuss the lesson content with other students and instructors. + +This is deliberately open-ended, just like the previous exercise with course star ratings. But this time, instead of rushing to implement, you're going to use `/grill-me` to explore the feature space first. + +The skill will ask you questions like: + +- Who can comment? Only enrolled students? Instructors too? +- Can users edit or delete their own comments? +- Should comments be threaded, or flat? +- Do comments need moderation? +- Should users get notifications when someone replies? + +You might not have thought about all of these. That's the point. The grilling process surfaces the decisions you need to make before you write any code. + +## Steps To Complete + +### Get the Skill + +- [ ] Run `npm run reset` to pull in the `/grill-me` skill + +This brings the repository up to the current lesson's commit, which includes the grilling skill in your `.agents/skills/` directory. + +### Invoke the Skill + +- [ ] Clear your terminal and run your [agent](https://www.aihero.dev/ai-coding-dictionary/agent) + +In your agent [harness](https://www.aihero.dev/ai-coding-dictionary/harness), you'll invoke the skill differently depending on your setup. In agent code, it's typically `/` followed by the skill name. + +- [ ] Type `/` to open the skill picker, then select `grill-me` + +This invokes the grilling skill and puts you into interview mode. + +### Start the Discussion + +- [ ] Write a loose, non-comprehensive prompt about lesson comments + +You don't need to be thorough here. The agent will ask clarifying questions. + +``` +/grill-me +I want to add comments to lessons so students can ask questions and discuss. +``` + +This kicks off a discussion. The agent will start building the design tree and asking about the decisions that hang off this feature. + +### Work Through the Grilling + +- [ ] Answer each round of questions as the agent asks them + +The agent will ask multiple questions per round. Answer them all before the next round begins. Your answers reshape the design tree and unlock new questions. + +- [ ] Keep going until the frontier is empty + +When the agent says the session is done and you've reached a shared understanding, you're ready to implement. + +This might take many rounds. That's the point. You're thinking through the problem before you code it. + +### Implement the Feature + +- [ ] Once you have a shared understanding, implement lesson comments + +Now that you know what you're building, write the code. + +- [ ] Test your implementation in the browser + +Students and instructors should be able to comment on lesson pages. The comments should persist and be visible to other users. + +### Verify Your Work + +- [ ] Run the app and navigate to a lesson page + +Pick a course you're enrolled in. Find a lesson like "Connecting to a Database" or "CRUD Operations". + +- [ ] Add a comment as a student + +Your comment should appear on the page. + +- [ ] Switch users and verify the comment is visible + +The comment you added should be visible when you switch to a different user and return to the same lesson. From 619b845fc997ee3f1e8981b0d526574e611ec289 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 20:53:27 +0000 Subject: [PATCH 13/22] docs(topics): make the lane index a live roadmap with status column Lanes 1-2 recorded CLOSED with their closing commits and filed items; lane 3 marked NEXT (chain handoff written, unconsumed). Closing lane sessions update their row in the closing commit so progress persists across handoffs in this one file. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index 4b2149b55..46bf9b2f3 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -161,14 +161,20 @@ stand" overclaim to match context-guard's own "declared judgment defaults" langu ## Lane index (filed 2026-08-17, in locked run order) -| Lane | Issue | Scope | -|------|-------|-------| -| 1 handoff | [#2899](https://github.com/melodic-software/claude-code-plugins/issues/2899) | use-case boundaries, purpose argument, expiry, ephemerality | -| 2 phase boundaries | [#2900](https://github.com/melodic-software/claude-code-plugins/issues/2900) | tree re-audit + context-driven continuation router (build deliverable) | -| 3 compaction doctrine | [#2901](https://github.com/melodic-software/claude-code-plugins/issues/2901) | fork-beats-compaction, auto-compact stance, evidence-degraded marker, harness claims | -| 4 plan-mode | [#2902](https://github.com/melodic-software/claude-code-plugins/issues/2902) | asset-rush critique vs interview-first sequencing, lock-mode audit | -| 5 grilling parity | [#2903](https://github.com/melodic-software/claude-code-plugins/issues/2903) | course-lesson deltas vs planning:interview | -| 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | aihero-course.md, term adoption, SSOT TRACK annotations, coverage index | +| Lane | Issue | Status (as-of 2026-08-17) | Scope | +|------|-------|--------|-------| +| 1 handoff | [#2899](https://github.com/melodic-software/claude-code-plugins/issues/2899) | **CLOSED** (`ffb01459`; filed #2955–#2957) | use-case boundaries, purpose argument, expiry, ephemerality | +| 2 phase boundaries | [#2900](https://github.com/melodic-software/claude-code-plugins/issues/2900) | **CLOSED** (`64fe359e`; filed #2971–#2973) | tree re-audit + context-driven continuation router (build deliverable) | +| 3 compaction doctrine | [#2901](https://github.com/melodic-software/claude-code-plugins/issues/2901) | **NEXT** (handoff written, unconsumed) | fork-beats-compaction, auto-compact stance, evidence-degraded marker, harness claims | +| 4 plan-mode | [#2902](https://github.com/melodic-software/claude-code-plugins/issues/2902) | open | asset-rush critique vs interview-first sequencing, lock-mode audit | +| 5 grilling parity | [#2903](https://github.com/melodic-software/claude-code-plugins/issues/2903) | open | course-lesson deltas vs planning:interview | +| 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | open | aihero-course.md consolidation (created by lane 1 per A2), term adoption, SSOT TRACK annotations + row-35 and "private marketplace" corrections, coverage index | + +This table is the persistent roadmap: each closing lane session updates its row (status + +closing commit + filed items) in the same commit that closes the lane, so any fresh session +reads current progress from this file alone. Lesson sources: `lessons/01`–`05` beside this +file. The handoff chain (`.work/handoffs/*-handoff-pocock-lane-N.md`, `previous_handoff` +links) carries per-session state; this file carries the journey. Background research dispatched pre-lane: harness-claims bundle → `.work/pocock-course-lanes/harness-claims/` (memory tier; full evidence + fetch logs live there; From e064f23f804d0c850e0e479f6c580c4c011b7a21 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 22:13:01 +0000 Subject: [PATCH 14/22] docs(upstream): close aihero lane 3 (compaction doctrine) with rows and summary Lane 3 (#2901) decisions, register Q24-Q30 under the user's standing acceptance: compact-as-default rejected (fork-beats-compaction stands); steered-compact-for-QA carve-out rejected with the marker's recorded trigger field as the track-on-event observable; auto-compact stance adopted convergent; primary/secondary-source terms routed to lane 6 with the transcript-lossless refinement; C5 recorded-unknown, C6 keeps its single-pool label; Boris 63-64 cited as vendored nuance. Twelve rows appended, summary written, roadmap row updated. Filed: #2995. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 4 +-- docs/topics/pocock-lane-3/SUMMARY.md | 44 +++++++++++++++++++++++++ docs/upstream/aihero-course.md | 40 ++++++++++++++++++++-- 3 files changed, 83 insertions(+), 5 deletions(-) create mode 100644 docs/topics/pocock-lane-3/SUMMARY.md diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index 46bf9b2f3..1ae159c82 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -165,8 +165,8 @@ stand" overclaim to match context-guard's own "declared judgment defaults" langu |------|-------|--------|-------| | 1 handoff | [#2899](https://github.com/melodic-software/claude-code-plugins/issues/2899) | **CLOSED** (`ffb01459`; filed #2955–#2957) | use-case boundaries, purpose argument, expiry, ephemerality | | 2 phase boundaries | [#2900](https://github.com/melodic-software/claude-code-plugins/issues/2900) | **CLOSED** (`64fe359e`; filed #2971–#2973) | tree re-audit + context-driven continuation router (build deliverable) | -| 3 compaction doctrine | [#2901](https://github.com/melodic-software/claude-code-plugins/issues/2901) | **NEXT** (handoff written, unconsumed) | fork-beats-compaction, auto-compact stance, evidence-degraded marker, harness claims | -| 4 plan-mode | [#2902](https://github.com/melodic-software/claude-code-plugins/issues/2902) | open | asset-rush critique vs interview-first sequencing, lock-mode audit | +| 3 compaction doctrine | [#2901](https://github.com/melodic-software/claude-code-plugins/issues/2901) | **CLOSED** (filed #2995; Q24–Q30) | fork-beats-compaction, auto-compact stance, evidence-degraded marker, harness claims | +| 4 plan-mode | [#2902](https://github.com/melodic-software/claude-code-plugins/issues/2902) | **NEXT** | asset-rush critique vs interview-first sequencing, lock-mode audit | | 5 grilling parity | [#2903](https://github.com/melodic-software/claude-code-plugins/issues/2903) | open | course-lesson deltas vs planning:interview | | 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | open | aihero-course.md consolidation (created by lane 1 per A2), term adoption, SSOT TRACK annotations + row-35 and "private marketplace" corrections, coverage index | diff --git a/docs/topics/pocock-lane-3/SUMMARY.md b/docs/topics/pocock-lane-3/SUMMARY.md new file mode 100644 index 000000000..64b0b0b49 --- /dev/null +++ b/docs/topics/pocock-lane-3/SUMMARY.md @@ -0,0 +1,44 @@ +# Lane 3 summary: compaction doctrine (#2901) + +Closed 2026-08-17. Vetted the merged Compaction + Auto-Compaction lessons (source committed at +`docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md`) against the +house doctrine: the handoff skill's fork-beats-compaction section, the continuation router's +compact-last-with-steering edge, and context-guard's evidence-degraded marker and zone contract. + +## Decisions (register Q24-Q29, provenance: user's standing acceptance of this session's recommendations) + +- **Q24 compact-as-default: REJECTED.** His compaction lesson's "saves re-exploration" default + framing loses to fork-beats-compaction; his own phase-boundaries lesson places compact at the + tree's bottom, converging with our last-resort-with-steering edge. No change to house doctrine. +- **Q25 steered-compact-for-QA carve-out: REJECTED, track-on-event.** Evidence degradation is + trigger-independent; his own AFK criterion routes finished-work QA to a subagent. Key fact: + `post-compact-mark.sh` already records `trigger: manual|auto|unknown`, so differentiation is + buildable the day real evidence justifies it; that recorded field is the reopen observable. +- **Q26 auto-compact stance: ADOPTED (convergent).** "Auto-compact firing means the boundary + decision was left too late; the human owns it" matches the instrumented design (operator-only + menus per check I23). Filed #2995: context-guard documents the verified config surfaces + (autoCompactWindow 100k-1M, env-var precedence, C1-C3 two-pool) and the zones-below-trigger + guidance. +- **Q27 primary/secondary-source vocabulary: ADOPT terms, REJECT the irrecoverability half.** + In Claude Code the on-disk JSONL transcript persists losslessly across compaction; only the + model-visible context turns secondary. Term adoption executes in lane 6. +- **Q28 C5/C6: recorded, not blocked.** C5 (queueing during compaction) stays UNDOCUMENTED and + untaught; C6 keeps its docs-only single-pool label; the interactive probe remains an open cure. +- **Q29 Boris sections 63-64: cited as vendored nuance.** Aligned with house stance; 300k-400k + rot reports and the 400000 env-var practice held as named anchors, never adopted numbers; + vendored content stays unedited. + +## Outputs + +- Rows: `docs/upstream/aihero-course.md` "Lane 3" section (12 rows + house-decisions paragraph). +- Work item filed: #2995 (context-guard auto-compact-window documentation). No other plugin + change decided; Q24/Q25/Q27 dispositions require none. +- Lane-6 parcels: primary/secondary-source term adoption (with the transcript refinement); + C4-refutation phrasing available for the coverage index. + +## Notes for later lanes + +- Lane 4 consumes C7-C9 verdicts (plan-mode mechanics; C9-positive single-pool label). +- The #2957 cloud zone-signal gap was weighed here: it does not change Q26's disposition (the + stance is about who owns the decision, not the instrument's availability in one environment), + but #2995's docs should acknowledge headless/cloud sessions lack the statusline tee. diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index 4f195c657..768e205bc 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -95,10 +95,44 @@ context-guard reader-contract drift are filed as their own items. Filed: [#2972](https://github.com/melodic-software/claude-code-plugins/issues/2972), [#2973](https://github.com/melodic-software/claude-code-plugins/issues/2973). -## Lanes 3 through 5 +## Lane 3: compaction doctrine (issue #2901, decided 2026-08-17) -Rows land here as each lane closes: compaction doctrine (#2901), plan mode (#2902), and -interview parity (#2903). +Basis: the merged Compaction and Auto-Compaction lessons (source: +`docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md`), graded against +the verified harness verdicts C1-C6 in the contract's table, the context-guard evidence-degraded +marker and reader contract, and the handoff skill's fork-beats-compaction doctrine. Register +Q24-Q29; answers locked under the user's standing acceptance of this session's recommendations +(register provenance in the topic ledger). + +| Lesson claim | Ours | Verdict | Reasoning, basis, as-of | +|---|---|---|---| +| Past the smart zone, continuing degrades results slowly; cached tokens are cheaper but the environment is less capable | context-guard zones (smart/acceptable/dumb) + the router's judgment tests | **COVERED** | The operational rule (leave a degraded window) is the zone doctrine; his degradation narrative is bucket-ii material graded against instrumented zone readings plus declared judgment-default bands (A1 baseline), never adopted as numbers. As-of 2026-08-17 | +| Clearing loses the "why"; re-exploration after a bare clear is lossy | Router Q3 reserves `/clear` for disposable context; the handoff save-point exists to carry the why | **COVERED** (stronger) | His lesson compares only continue/clear/compact; the handoff-file fork he introduces one lesson later beats his own trichotomy for the retain-the-why case, which is exactly our fork-beats-compaction ordering. As-of 2026-08-17 | +| Compaction "takes the context, squeezes it down, and seeds a fresh session" | No such claim in the family; compact edge documented as same-session | **REJECT** (harness claim) | Verdict C4 REFUTED (two-pool): compaction continues the SAME session over a structured summary; only fork or `--fork-session` makes a new session id. The lesson and its quiz answer ("seeds a fresh session in memory") both carry the refuted mechanics. As-of 2026-08-17 | +| `/compact [instructions]` steering matters; one sentence is often enough | Router compact edge requires a steering hint naming what the summary must keep | **COVERED** | Verdict C6 CONFIRMED (docs-only, single-pool label carried); parity on the steering discipline, ours phrased as a requirement rather than a tip. As-of 2026-08-17 | +| You can queue messages during compaction; they run when it finishes | Not taught anywhere in the family | **UNKNOWN** (recorded, not taught) | Verdict C5 UNDOCUMENTED in official docs; adjacent evidence suggests a queue exists but its compaction interaction is unspecified. Q28 decision: record now, do not block the lane on a probe neither cloud session can run; probe sketch retained in the contract. As-of 2026-08-17 | +| The compaction summary preserves a structured set (intent, spec, concepts, file refs, errors, user messages, pending tasks) | Handoff structure doc is the deliberate-selection counterpart | **COVERED** (observation) | Recorded as an observation of harness output, not doctrine; our position stands: a summarizer keeps what it happens to keep, a handoff carries what was chosen deliberately. As-of 2026-08-17 | +| Compact-before-QA on finished work is a "cast-iron great" use | PostCompact evidence-degraded marker: a compacted session's effective zone is dumb regardless of numbers | **REJECT** (track-on-event) | Q25: evidence degradation is trigger-independent, the marker's rationale (evidence already gone from the model-visible context) holds for manual and auto alike; his own phase-boundaries lesson routes AFK QA to a subagent, undercutting the case. The marker already records `trigger: manual\|auto\|unknown` (post-compact-mark.sh), so consumer differentiation is buildable; revisit ONLY on real evidence that steered boundary-timed compactions perform well (the recorded trigger field is the observable). As-of 2026-08-17 | +| Primary source (the session) vs secondary source (the summary); after compaction nothing is retrievable in full | Constraint re-scan reads the lossless on-disk transcript across compaction (handoff structure doc) | **ADOPT terms / REJECT the irrecoverability half** | Q27: the vocabulary (primary/secondary source) goes to lane-6 adoption; the irrecoverability claim is wrong for Claude Code, where the JSONL transcript persists losslessly on disk and only the model-visible context turns secondary. His quiz answer "compaction writes no file" conflates the two. As-of 2026-08-17 | +| Past the window limit requests error; the harness protects via auto-compact; `/config` shows Auto-compact; `autoCompactWindow` accepts 100,000 to 1,000,000 | Nothing in the family documents this today | **CONFIRMED** (informational) | Verdicts C1-C3 (two-pool incl. the shipped binary schema `min(1e5).max(1e6)`); his 250k example is inside the verified range. UI-surface details recorded as observations. Documentation gap filed: [#2995](https://github.com/melodic-software/claude-code-plugins/issues/2995). As-of 2026-08-17 | +| Auto-compaction exists in every single agent harness | Out of our governance scope | **NOT RELEVANT** (overbroad) | We govern Claude Code only; recorded without a verdict on other harnesses. As-of 2026-08-17 | +| Mid-phase compaction loses the thread (style drift, forgotten features); the boundary is the least-damage point | Router restricts `/compact` to phase boundaries only, ordered last, with steering | **COVERED** | Boundary-only compaction is already house doctrine; his mid-phase anecdotes are bucket-ii anchors with named provenance. As-of 2026-08-17 | +| Auto-compact gives no steering hook; if auto-compact fires something went wrong; the human owns the boundary decision | context-guard instruments the window, renders the continuation menu to the operator only (check I23), optional blocking mode | **ADOPT** (convergent) | Q26: same conclusion, one layer further, instrument the environment and route menus to the human rather than only training the human. Zones-below-trigger guidance and config-surface documentation filed: [#2995](https://github.com/melodic-software/claude-code-plugins/issues/2995). As-of 2026-08-17 | + +House decisions recorded alongside the rows (Q24-Q29, 2026-08-17): compact-as-default framing is +rejected and compact stays the router's last-resort fallthrough with mandatory steering +(fork-beats-compaction unchanged); no marker carve-out for steered compactions, with the recorded +trigger field as the track-on-event observable; the auto-compact stance is adopted as convergent +with one filed docs item ([#2995](https://github.com/melodic-software/claude-code-plugins/issues/2995)); +primary/secondary-source vocabulary routes to lane 6 carrying the transcript-lossless refinement; +C5 stays recorded-unknown and C6 keeps its single-pool label until an interactive probe runs; the +vendored Boris doctrine (sections 63-64: compact lossy vs clear-plus-brief, rot reported at +300k-400k with the 400000 env-var practice) is cited as vendored nuance, aligned with house +stance, its figures held as named anchors never adopted numbers. + +## Lanes 4 through 5 + +Rows land here as each lane closes: plan mode (#2902) and interview parity (#2903). ## Coverage index and consolidation From de55210d631225bcf9d40476c7b501edcd4ce286 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Aug 2026 23:55:57 +0000 Subject: [PATCH 15/22] docs(upstream): close aihero lane 4 (plan mode / asset rush) with rows Lane 4 (#2902) decisions, register Q31-Q35 under the user's restated acceptance: asset-rush critique adopted as convergent (embodied twice: interview-first Brief plus the plan skill's own decision gates); lock/ auto-synthesize audited as a licensed exception (auto-guard, STOP-on- gap, user-invocation-as-confirmation, audit-answers as the producer- not-critic control); design concept already embodied by the general- domain shared-understanding terminal; walkthrough graded separately per C7-C9 (stale /plan demo rejected, critique unaffected). Nine rows appended, summary written, roadmap updated. No work items required. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 4 +-- docs/topics/pocock-lane-4/SUMMARY.md | 47 +++++++++++++++++++++++++ docs/upstream/aihero-course.md | 33 +++++++++++++++-- 3 files changed, 80 insertions(+), 4 deletions(-) create mode 100644 docs/topics/pocock-lane-4/SUMMARY.md diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index 1ae159c82..df196e777 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -166,8 +166,8 @@ stand" overclaim to match context-guard's own "declared judgment defaults" langu | 1 handoff | [#2899](https://github.com/melodic-software/claude-code-plugins/issues/2899) | **CLOSED** (`ffb01459`; filed #2955–#2957) | use-case boundaries, purpose argument, expiry, ephemerality | | 2 phase boundaries | [#2900](https://github.com/melodic-software/claude-code-plugins/issues/2900) | **CLOSED** (`64fe359e`; filed #2971–#2973) | tree re-audit + context-driven continuation router (build deliverable) | | 3 compaction doctrine | [#2901](https://github.com/melodic-software/claude-code-plugins/issues/2901) | **CLOSED** (filed #2995; Q24–Q30) | fork-beats-compaction, auto-compact stance, evidence-degraded marker, harness claims | -| 4 plan-mode | [#2902](https://github.com/melodic-software/claude-code-plugins/issues/2902) | **NEXT** | asset-rush critique vs interview-first sequencing, lock-mode audit | -| 5 grilling parity | [#2903](https://github.com/melodic-software/claude-code-plugins/issues/2903) | open | course-lesson deltas vs planning:interview | +| 4 plan-mode | [#2902](https://github.com/melodic-software/claude-code-plugins/issues/2902) | **CLOSED** (no items filed; Q31–Q35) | asset-rush critique vs interview-first sequencing, lock-mode audit | +| 5 grilling parity | [#2903](https://github.com/melodic-software/claude-code-plugins/issues/2903) | **NEXT** | course-lesson deltas vs planning:interview | | 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | open | aihero-course.md consolidation (created by lane 1 per A2), term adoption, SSOT TRACK annotations + row-35 and "private marketplace" corrections, coverage index | This table is the persistent roadmap: each closing lane session updates its row (status + diff --git a/docs/topics/pocock-lane-4/SUMMARY.md b/docs/topics/pocock-lane-4/SUMMARY.md new file mode 100644 index 000000000..79657719b --- /dev/null +++ b/docs/topics/pocock-lane-4/SUMMARY.md @@ -0,0 +1,47 @@ +# Lane 4 summary: plan mode / asset rush (#2902) + +Closed 2026-08-17. Vetted the "Why Plan Mode Sucks" lesson (source committed at +`docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md`) against the planning +pipeline: `planning:interview` (pre-clarity contract, auto-detect, auto-guard, `lock` +STOP-on-gap, general-domain terminal) and `planning:plan` (approval gate, Open Decisions before +the plan body, devils-advocate dispatch, decision confidence gate). Verdicts C7-C9 graded the +walkthrough claims. + +## Decisions (register Q31-Q35, provenance: user's restated acceptance, "Go with your recommendations") + +- **Q31 asset-rush critique: ADOPTED (convergent).** The critique is the design rationale the + pipeline embodies twice over: the Brief locks intent before planning, and the plan skill + itself refuses inline decision-locking (Open Decisions block, confidence gate routing judgment + calls back to interview rounds, user approval before any code). Plan mode is repositioned as a + permission gate, never the alignment mechanism. +- **Q32 lock-mode audit: LICENSED EXCEPTION.** The auto-guard bars synthesizing genuine user + decisions; `lock` is user-invoked (invocation IS the confirmation) with STOP-on-gap; the + default action leans to relentless `me`; `/planning:audit-answers` is the producer-not-critic + compensating control, exercised live in this very effort (it corrected two contract + decisions). No change filed. +- **Q33 design concept: already embodied.** The general-domain interview terminal (shared + understanding, no artifact, no handoff) is the design-concept endpoint; the term maps to our + "shared understanding" and goes to lane 6 with "asset rush" and "sycophancy" as candidates. +- **Q34 walkthrough grading: separated from the critique.** C7/C8 CONFIRMED; C9's "/plan views + the plan" demo is stale (it enters plan mode; no view command exists). A stale demo does not + dent a design argument; graded separately per the claim ladder. +- **Q35 work items: NONE.** Nothing decided requires a plugin change. + +## Outputs + +- Rows: `docs/upstream/aihero-course.md` "Lane 4" section (9 rows + house-decisions paragraph). +- Work items: none. +- Lane-6 parcels: term candidates (design concept -> shared understanding, asset rush, + sycophancy); the strongest coverage-index thesis line: "the fix for plan mode is not a better + plan; it is a contract stage upstream of the plan, plus a plan stage that refuses to lock + decisions inline." + +## Notes for lane 5 + +- Expected mostly confirmation (frontier rounds, facts-vs-decisions, empty-frontier stop are + attributed adoptions already recorded in the SSOT); check course-only additions: the + grill-execute-CLEAR loop framing (the clear leg maps to our workflow spec-first mode and the + handoff chain), and the lesson's decision-checklist examples. +- His grilling/grill-me SKILL.md texts may be wanted for exact-wording comparison; the + `/workspace/mattpocock/skills` clone may be gone (probe: `git -C /workspace/mattpocock/skills + rev-parse HEAD`, expect `068b6e0`; shallow re-clone command in the lane-4 handoff if needed). diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index 768e205bc..2f0fe5976 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -130,9 +130,38 @@ vendored Boris doctrine (sections 63-64: compact lossy vs clear-plus-brief, rot 300k-400k with the 400000 env-var practice) is cited as vendored nuance, aligned with house stance, its figures held as named anchors never adopted numbers. -## Lanes 4 through 5 +## Lane 4: plan mode / asset rush (issue #2902, decided 2026-08-17) -Rows land here as each lane closes: plan mode (#2902) and interview parity (#2903). +Basis: the "Why Plan Mode Sucks" lesson (source: +`docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md`), graded against +`planning:interview` (pre-clarity stance, auto-detect, auto-guard, `lock` STOP-on-gap, the +general-domain shared-understanding terminal) and `planning:plan` (approval gate, Open Decisions +before the plan body, devils-advocate dispatch, decision confidence gate), plus verdicts C7-C9. +Register Q31-Q35 under the user's restated acceptance. + +| Lesson claim | Ours | Verdict | Reasoning, basis, as-of | +|---|---|---|---| +| Agents rush from prompt to implementation with no alignment step (the asset rush) | `planning:interview` is the pipeline's pre-clarity stage: a contract locked before exploration, planning, or execution | **ADOPT** (convergent) | The critique is the design rationale the pipeline already embodies; behavior-change work is interview-first by default, with auto-detect keeping it cheap. As-of 2026-08-17 | +| Plan mode is a buffer between exploration and implementation: a plan document you review, then proceed | Plan mode is treated as a permission/safety gate; alignment is owned upstream by the interview contract | **COVERED** (position) | The harness feature is not rejected, it is repositioned: a permission mode cannot produce shared understanding, and nothing in the family asks it to. As-of 2026-08-17 | +| "Plan mode is still rushing": the plan reads like the implementation; the decisions are already made and written down | Two structural answers: the Brief locks intent BEFORE `/planning:plan`, and the plan skill itself refuses to lock decisions inline (Open Decisions surfaced before the plan body; a confidence gate routes judgment calls back to interview rounds; user approval gate before any code; fresh-context devils-advocate stress-test) | **ADOPT** (convergent, already answered structurally) | His diagnosis names exactly the failure the pipeline's two gates exist to prevent; no change needed. As-of 2026-08-17 | +| Root cause is the sycophantic trait: told to produce, the agent produces | Interview stance: recommendations-first but facts-are-mine/decisions-are-the-user's; the auto-guard forbids resolving a genuine user choice; `/planning:audit-answers` is the producer-not-critic control | **COVERED** | The trait is countered by structure, not exhortation; "sycophancy" and "asset rush" go to lane 6 as term candidates. As-of 2026-08-17 | +| The design concept (Brooks): shared understanding is not an asset; conversation sharpens it | The general-domain interview terminal drives to a shared understanding and STOPS: no Brief, no artifact, no pipeline handoff | **COVERED** (embodied) | Q33: the endpoint already exists; the term maps to our "shared understanding" (lane-6 adoption candidate); no mechanism change earned. As-of 2026-08-17 | +| Walkthrough: cycle `shift+tab` until plan mode is on | Verified harness behavior | **CONFIRMED** | Verdict C7 (two-pool); no fixed press count is taught. As-of 2026-08-17 | +| Walkthrough: "I can view the plan by typing `/plan`" | Verified harness behavior | **REJECT** (stale walkthrough) | Verdict C9 PARTIALLY TRUE: `/plan [description]` ENTERS plan mode; no documented command views the current plan (absence half two-pool; positive half docs-only). The lesson's critique is unaffected by its stale demo. As-of 2026-08-17 | +| Walkthrough: review the generated plan, modify, then proceed (approval flow) | Verified harness behavior | **CONFIRMED** | Verdict C8 (two-pool; flow details docs-only); the newer EnterPlanMode tool postdates the lesson. As-of 2026-08-17 | +| "A different approach" replaces this (the grilling tease) | Lane 5's subject | **NOT RELEVANT** (here) | Graded in the grilling-parity lane (#2903). As-of 2026-08-17 | + +House decisions recorded alongside the rows (Q31-Q35, 2026-08-17): the `lock`/auto-synthesize +audit concludes LICENSED EXCEPTION, not quiet rush: the auto-guard bars synthesizing genuine +user decisions, `lock` is user-invoked (the invocation is the confirmation) with STOP-on-gap, +the default action leans to relentless interviewing, and `/planning:audit-answers` supplies the +producer-not-critic check (exercised live in this effort, where it corrected two decisions). No +work items filed: no plugin change was decided; lane-6 parcels are the three term candidates +(design concept mapped to shared understanding, asset rush, sycophancy) and coverage phrasing. + +## Lane 5 + +Rows land here when the interview-parity lane closes (#2903). ## Coverage index and consolidation From 723e78302e99f49706083bd1463c5f9e643ba4cc Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 03:26:44 +0000 Subject: [PATCH 16/22] docs(upstream): close aihero lane 5 (grilling parity) with rows Lane 5 (#2903) register Q36-Q37 under the user's restated acceptance: fully confirmatory, as the contract predicted. His current grilling/ grill-me texts (live clone, HEAD 068b6e0) match the SSOT baseline; the course lesson adds only the loop framing (covered by workflow stages + continuation router, no term adopted per vocabulary parsimony) and posture lines (covered, ours stronger via the register gate and the wayfind route). Nine rows appended, summary written, roadmap updated. No work items. Lane 6 is the final lane. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 4 ++-- docs/topics/pocock-lane-5/SUMMARY.md | 32 +++++++++++++++++++++++++ docs/upstream/aihero-course.md | 27 +++++++++++++++++++-- 3 files changed, 59 insertions(+), 4 deletions(-) create mode 100644 docs/topics/pocock-lane-5/SUMMARY.md diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index df196e777..9a3447655 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -167,8 +167,8 @@ stand" overclaim to match context-guard's own "declared judgment defaults" langu | 2 phase boundaries | [#2900](https://github.com/melodic-software/claude-code-plugins/issues/2900) | **CLOSED** (`64fe359e`; filed #2971–#2973) | tree re-audit + context-driven continuation router (build deliverable) | | 3 compaction doctrine | [#2901](https://github.com/melodic-software/claude-code-plugins/issues/2901) | **CLOSED** (filed #2995; Q24–Q30) | fork-beats-compaction, auto-compact stance, evidence-degraded marker, harness claims | | 4 plan-mode | [#2902](https://github.com/melodic-software/claude-code-plugins/issues/2902) | **CLOSED** (no items filed; Q31–Q35) | asset-rush critique vs interview-first sequencing, lock-mode audit | -| 5 grilling parity | [#2903](https://github.com/melodic-software/claude-code-plugins/issues/2903) | **NEXT** | course-lesson deltas vs planning:interview | -| 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | open | aihero-course.md consolidation (created by lane 1 per A2), term adoption, SSOT TRACK annotations + row-35 and "private marketplace" corrections, coverage index | +| 5 grilling parity | [#2903](https://github.com/melodic-software/claude-code-plugins/issues/2903) | **CLOSED** (no items; Q36–Q37) | course-lesson deltas vs planning:interview | +| 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | **NEXT** (final lane) | aihero-course.md consolidation (created by lane 1 per A2), term adoption, SSOT TRACK annotations + row-35 and "private marketplace" corrections, coverage index | This table is the persistent roadmap: each closing lane session updates its row (status + closing commit + filed items) in the same commit that closes the lane, so any fresh session diff --git a/docs/topics/pocock-lane-5/SUMMARY.md b/docs/topics/pocock-lane-5/SUMMARY.md new file mode 100644 index 000000000..7d593f6e5 --- /dev/null +++ b/docs/topics/pocock-lane-5/SUMMARY.md @@ -0,0 +1,32 @@ +# Lane 5 summary: grilling-interview parity (#2903) + +Closed 2026-08-17. Vetted "The Grill-Execute-Clear Loop" lesson (source committed at +`docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md`) against +`planning:interview`, with his CURRENT `grilling`/`grill-me` texts read from the live clone at +HEAD `068b6e0` for exact-wording comparison. + +## Outcome: fully confirmatory, as the contract predicted + +- His repo texts match the SSOT-recorded derivation baseline verbatim in substance; the course + lesson restates the skill and adds only framing (the grill-execute-clear loop), posture lines + ("many rounds is the point"), and course machinery. +- Every parity element graded COVERED, several stronger on our side (mechanical register gate, + auto-guard + unattended ladder, wayfind escape route, question-budget scaling). +- **Q36:** the loop framing earns NO term adoption: the workflow stages + continuation router + already own the shape; a mapping row records the equivalence instead. +- **Q37:** no work items filed (second clean lane after lane 4). + +## Outputs + +- Rows: `docs/upstream/aihero-course.md` "Lane 5" section (9 rows + house-decisions paragraph). +- Work items: none. Lane-6 parcels: none new (design-tree = decision-tree equivalence noted). + +## Notes for lane 6 + +- All parcels now assembled across lanes 1-5: term candidates (primary/secondary source with + the transcript-lossless refinement, smart zone, AFK, phase boundary, design concept -> shared + understanding, asset rush, sycophancy); SSOT TRACK-row annotations (invocation-reach landed + unreleased; diagnosing-bugs post-mortem removal); SSOT row-35 "measured bands" correction + (A1); v12-map "Claude-only private marketplace" staleness; teach-comparison branch fold-in + check (`claude/teach-skill-comparison-h3rpag`, per #2904 comments); the coverage index against + all six lessons. diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index 2f0fe5976..8190dc0d0 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -159,9 +159,32 @@ producer-not-critic check (exercised live in this effort, where it corrected two work items filed: no plugin change was decided; lane-6 parcels are the three term candidates (design concept mapped to shared understanding, asset rush, sycophancy) and coverage phrasing. -## Lane 5 +## Lane 5: grilling-interview parity (issue #2903, decided 2026-08-17) -Rows land here when the interview-parity lane closes (#2903). +Basis: "The Grill-Execute-Clear Loop" lesson (source: +`docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md`), graded against +`planning:interview` and against his CURRENT repo texts read from a live clone at HEAD +`068b6e0` (`skills/productivity/grilling/SKILL.md`, `grill-me/SKILL.md`) — which match the +SSOT-recorded baseline verbatim in substance, confirming the 2026-08-17 recheck's +cosmetic-only-drift finding. Register Q36-Q37 under the user's restated acceptance. The +grilling-family provenance itself is settled in `mattpocock-skills.md` rows 3-4 and is +confirmed here, not re-derived. + +| Lesson claim | Ours | Verdict | Reasoning, basis, as-of | +|---|---|---|---| +| The skill interviews you relentlessly until shared understanding; only then do you implement | `me`-mode canonical framing + the confirmation gate ("do not act on the interview's output until they confirm") | **COVERED** (attributed) | The recorded behavioral derivation (SSOT rows 3-4); ours adds the mechanical register gate script on top of the judgment stop. As-of 2026-08-17 | +| Design tree; rounds; the frontier is every decision whose prerequisites are settled, asked all at once; a dependent question waits for a later round | Frontier-rounds loop, identical in substance | **COVERED** (attributed) | Same derivation record; his current repo text matches the audited baseline. "Design tree" and our "decision tree" are equivalent vocabulary, no action. As-of 2026-08-17 | +| Per-question format with a recommended answer (the emoji-anchored shape) | Recommendation-per-question with a single verdict marker; emoji anchors are the `use_emoji_question_markers` opt-in, default off | **COVERED** (recorded v1.2 adoption) | Decoration of the existing marker, adopted opt-in; nothing new in the lesson. As-of 2026-08-17 | +| Finding facts is your job, never the user's; dispatch a sub-agent, don't block the round; decisions are the user's | Facts-vs-decisions split, background fact sub-agents, non-blocking rounds | **COVERED** (attributed) | Same derivation record, near-verbatim overlap by design. As-of 2026-08-17 | +| Done when the frontier is empty, nothing silently assumed; the user confirms shared understanding first | Stop condition + `check-open-questions.sh` register gate + confirmation gate + auto-guard + unattended ladder | **COVERED** (stronger) | Ours makes the empty-frontier judgment mechanically checkable and defines the no-human path his skill leaves open. As-of 2026-08-17 | +| The grill-execute-clear loop: understand, execute, clear your mind, next feature | Workflow stages own the shape; the clear leg is the continuation router's territory (clear/handoff chain; spec-first mode runs stages with `/clear` between) | **COVERED**, no term adoption | Q36: a second name for a loop the house taxonomy already owns violates vocabulary parsimony; recorded as a mapping, not a new term. As-of 2026-08-17 | +| Many rounds is the point; keep going until the frontier is empty | No question cap; the escape is the user's wrap-up | **COVERED** (stronger) | House additions his lesson lacks: the ballooning-frontier route to `planning:wayfind` and the question budget scaling with upstream artifacts. As-of 2026-08-17 | +| `grill-me` is a user-invoked pointer that calls the model-invoked `grilling` | One skill, three actions (`me`/`auto`/`lock`), user- and model-invocable under trigger discipline | **COVERED** (different shape, deliberate) | His two-skill split expresses his invocation-reach invariant; our single-skill shape predates it and the difference is recorded, not a gap. As-of 2026-08-17 | +| Walkthrough machinery (npm run reset, `.agents/skills`, the `/` picker) and the lesson-comments example questions | Course-platform machinery and illustration | **NOT RELEVANT** | No repo counterpart owed. As-of 2026-08-17 | + +House decisions recorded alongside the rows (Q36-Q37, 2026-08-17): no term adoption for the +loop name (mapping recorded instead); no work items filed (pure parity lane, the second lane to +close clean); no new lane-6 parcels beyond the design-tree/decision-tree equivalence note. ## Coverage index and consolidation From 9d50504f17db385854f76eafd64bccf41d2b9570 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 04:19:47 +0000 Subject: [PATCH 17/22] docs(upstream): close aihero lane 6 (consolidation) - all six lanes done Lane 6 (#2904), register Q38-Q40: coverage index written into the contract (pointer index over the 49 verified claim rows plus outside- the-rows accounting); SSOT row-35 A1 correction applied; invocation- reach and diagnosing-bugs TRACK rows annotated with the 2026-08-17 unreleased-drift evidence; v12-map private-marketplace staleness corrected; seven dictionary-term verdicts recorded (central glossary deliberately deferred: none exists, placement is the user's call); teach branch confirmed in-flight pointer-only. Roadmap: ALL LANES CLOSED. Remaining: the single PR with the prune commit, on the user's go-ahead. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 29 ++++++++++++++++- docs/topics/pocock-lane-6/SUMMARY.md | 38 ++++++++++++++++++++++ docs/upstream/aihero-course.md | 30 ++++++++++++++--- docs/upstream/mattpocock-skills-v12-map.md | 8 +++++ docs/upstream/mattpocock-skills.md | 12 +++++-- 5 files changed, 109 insertions(+), 8 deletions(-) create mode 100644 docs/topics/pocock-lane-6/SUMMARY.md diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md index 9a3447655..e45471b24 100644 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ b/docs/topics/pocock-course-lanes/PLAN.md @@ -168,7 +168,7 @@ stand" overclaim to match context-guard's own "declared judgment defaults" langu | 3 compaction doctrine | [#2901](https://github.com/melodic-software/claude-code-plugins/issues/2901) | **CLOSED** (filed #2995; Q24–Q30) | fork-beats-compaction, auto-compact stance, evidence-degraded marker, harness claims | | 4 plan-mode | [#2902](https://github.com/melodic-software/claude-code-plugins/issues/2902) | **CLOSED** (no items filed; Q31–Q35) | asset-rush critique vs interview-first sequencing, lock-mode audit | | 5 grilling parity | [#2903](https://github.com/melodic-software/claude-code-plugins/issues/2903) | **CLOSED** (no items; Q36–Q37) | course-lesson deltas vs planning:interview | -| 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | **NEXT** (final lane) | aihero-course.md consolidation (created by lane 1 per A2), term adoption, SSOT TRACK annotations + row-35 and "private marketplace" corrections, coverage index | +| 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | **CLOSED** (Q38–Q40; glossary deferred to user) | aihero-course.md consolidation (created by lane 1 per A2), term adoption, SSOT TRACK annotations + row-35 and "private marketplace" corrections, coverage index | This table is the persistent roadmap: each closing lane session updates its row (status + closing commit + filed items) in the same commit that closes the lane, so any fresh session @@ -200,6 +200,33 @@ for lanes 3–5 to cite, with corroboration labels: Cures for the single-pool rows when convenient: run `/compact ` and `/plan` in a live interactive session (Tier-0). +## Coverage index (lane 6, 2026-08-18) — the "everything is represented" gate + +Every claim in the six pasted lessons maps to a disposition. The claim-level enumeration IS the +lane sections of [`docs/upstream/aihero-course.md`](../../upstream/aihero-course.md) (49 rows +total; counts verified against the doc); this index points, per the do-not-duplicate rule, and +records what sits outside the rows: + +| Lesson (committed source) | Dispositions | Where | +|---|---|---| +| Handing Off (`lessons/01`) | 9 rows: 3 ADOPT, 4 REJECT, 2 COVERED; items #2955 #2956 #2957 | aihero-course.md Lane 1 | +| Clear/Compact/Handoff/Subagent (`lessons/02`) | 10 rows: 1 ADOPT-modified, 3 REJECT, 6 COVERED; items #2971 #2972 #2973 | aihero-course.md Lane 2 | +| Compaction (`lessons/03`, first half) | rows within Lane 3's 12: compact-as-default REJECT, seeds-fresh-session REJECT (C4), steering COVERED (C6), queueing UNKNOWN (C5), QA carve-out REJECT track-on-event, vocabulary ADOPT-terms | aihero-course.md Lane 3; item #2995 | +| Auto-Compaction (`lessons/03`, second half) | rows within Lane 3's 12: autoCompactWindow CONFIRMED (C1-C3), every-harness NOT RELEVANT, mid-phase COVERED, human-owns-boundary ADOPT | aihero-course.md Lane 3; item #2995 | +| Why Plan Mode Sucks (`lessons/04`) | 9 rows: 2 ADOPT-convergent, 1 REJECT (stale /plan demo, C9), 3 COVERED, 2 CONFIRMED walkthrough, 1 NOT RELEVANT; no items | aihero-course.md Lane 4 | +| Grill-Execute-Clear (`lessons/05`) | 9 rows: 8 COVERED (parity, several stronger), 1 NOT RELEVANT (course machinery); no items | aihero-course.md Lane 5 | + +Outside the rows, also represented: the harness-claims verdict table (C1-C9, this file) grades +every mechanical claim the lessons make about Claude Code; quiz-answer claims are covered where +they restate lesson claims (the two that add error, C4's "seeds a fresh session" and "compaction +writes no file", are named in Lane 3's rows); dictionary-term candidates are the lane-6 +term-adoption set; course-platform machinery (npm run reset, commit maps, skill-picker +walkthroughs, Discord) carries NOT RELEVANT rows or is excluded as non-claims. Known-open cures, +deliberately not blockers: C5 empirical probe, C6/C9-positive second-pool probes (interactive +session required). The parallel teach-skill comparison (local branch +`claude/teach-skill-comparison-h3rpag`) is in-flight with no outcomes yet; its future results +are bound to this provenance home by the guard comment on #2904. + ## Upstream recheck — 2026-08-17 (pre-lane gate) `/discipline:recheck-against-upstream` run against mattpocock/skills HEAD `068b6e0` diff --git a/docs/topics/pocock-lane-6/SUMMARY.md b/docs/topics/pocock-lane-6/SUMMARY.md new file mode 100644 index 000000000..a11948ec0 --- /dev/null +++ b/docs/topics/pocock-lane-6/SUMMARY.md @@ -0,0 +1,38 @@ +# Lane 6 summary: vocabulary + provenance consolidation (#2904) + +Closed 2026-08-18. The final lane: consolidation, corrections, term verdicts, and the coverage +index that is the effort's "everything is represented" gate. + +## Executed (register Q38-Q40) + +- **Coverage index** written into the effort contract (`docs/topics/pocock-course-lanes/PLAN.md`): + per-lesson pointer index over the 49 claim rows (counts verified against the doc), plus the + outside-the-rows accounting (harness verdict table, quiz-claim handling, machinery exclusions, + known-open cures, teach-branch status). Q39: pointer shape per the do-not-duplicate rule. +- **SSOT maintenance** (`docs/upstream/mattpocock-skills.md`): row-35 "measured bands" overclaim + corrected per audit A1; invocation-reach TRACK strand annotated with the landed-unreleased + evidence (his PRs #878/#880, `.agents/invocation.md`); diagnosing-bugs row annotated with the + post-mortem-step removal. `docs/upstream/mattpocock-skills-v12-map.md`: private-marketplace + staleness correction (repo is public; inventory re-verified intact at HEAD `068b6e0`). +- **Term verdicts** recorded in `docs/upstream/aihero-course.md` Lane 6 (seven candidates: + 2 adopt, 1 partial, 1 already-house, 1 rejected-synonym, 1 shorthand-only, 1 no-action). + Q40 routed through `/domain-driven-design:curate-language`: the repo keeps NO central + glossary (vocabulary lives in owning plugins' docs), so glossary creation was DEFERRED per + the lazy-creation rule; the placement question goes to the user, not decided autonomously. +- **Teach-branch check** (Q38): local branch `claude/teach-skill-comparison-h3rpag` holds only + its interview ledger (commit `49bb9614`), no outcomes; in-flight, pointer-only; the #2904 + guard comment binds its future results to the provenance home. +- `docs/upstream/aihero-course.md` consolidation: trigger discipline and SSOT cross-links were + verified already present (lane 1's creation was to spec); the Lane 6 section replaces the + consolidation placeholder. + +## Open by design (not blockers) + +- Central-glossary creation: user placement choice pending. +- Interactive-session probes: C5 (queueing), C6 and C9-positive second pools. +- The final PR (user go-ahead required) with the contract-slice prune commit. + +## Effort totals (lanes 1-6) + +49 claim rows + 7 term verdicts; items filed: #2955 #2956 #2957 (lane 1), #2971 #2972 #2973 +(lane 2), #2995 (lane 3); lanes 4-6 filed none. Six issues closed: #2899-#2904. diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index 8190dc0d0..4c29fdbf1 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -186,8 +186,28 @@ House decisions recorded alongside the rows (Q36-Q37, 2026-08-17): no term adopt loop name (mapping recorded instead); no work items filed (pure parity lane, the second lane to close clean); no new lane-6 parcels beyond the design-tree/decision-tree equivalence note. -## Coverage index and consolidation - -Owned by lane 6 ([#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904)): -the per-lesson coverage index mapping every claim to its disposition, dictionary-term adoption, -and final consolidation of this document. +## Lane 6: vocabulary + consolidation (issue #2904, decided 2026-08-18) + +Consolidation record: the per-lesson coverage index lives in the effort contract +(`docs/topics/pocock-course-lanes/PLAN.md`, "Coverage index" — pruned with the topic slice at +PR time, its substance carried in the PR body; the claim-level enumeration is this document's +lane sections, 49 rows). SSOT maintenance executed by this lane: the row-35 wording correction +(audit A1), the invocation-reach and diagnosing-bugs TRACK annotations (2026-08-17 recheck, +unreleased drift), and the v12-map private-marketplace staleness correction. The parallel +teach-skill comparison is in-flight (local branch, ledger only); its future outcomes are bound +to this provenance home by the guard comment on #2904. + +**Dictionary-term verdicts** (candidates harvested across lanes; the repo keeps NO central +glossary — vocabulary lives in each owning plugin's docs, so these are adoption verdicts, not +glossary entries; central-glossary creation deliberately deferred per the curate-language +lazy-creation rule, pending the user's placement choice): + +| Term (his dictionary) | Verdict | Where the meaning lives | +|---|---|---| +| primary source / secondary source | **ADOPT** as working discussion vocabulary, WITH the house refinement: in Claude Code the on-disk JSONL transcript stays lossless across compaction; only the model-visible context turns secondary | Lane 3 rows; handoff structure doc's transcript re-scan rule | +| smart zone | **PARTIAL**: survives as informal shorthand; the canonical house terms are context-guard's zone words (smart / acceptable / dumb) with declared judgment-default bands; his ~150k number rejected | context-guard reader contract | +| AFK | **ADOPT** (narrow) as the name of the router's adopted AFK edge | lane 2 rows; build item #2971 | +| phase boundary | **ALREADY HOUSE** — the continuation router's trigger vocabulary predates the course | session-flow workflow/continuation docs | +| design concept | **REJECTED SYNONYM** of "shared understanding" (the general-domain interview terminal); carry an Avoid line if a glossary is ever created | lane 4 rows; planning:interview | +| asset rush | **ADOPT** as effort/discussion shorthand for the named failure mode; doubtful admission to any future glossary (methodology vocabulary) | lane 4 rows | +| sycophancy | **NO ACTION** — generic ML vocabulary already in standard use | lane 4 rows | diff --git a/docs/upstream/mattpocock-skills-v12-map.md b/docs/upstream/mattpocock-skills-v12-map.md index 41eed2f41..4183d16c6 100644 --- a/docs/upstream/mattpocock-skills-v12-map.md +++ b/docs/upstream/mattpocock-skills-v12-map.md @@ -1,5 +1,13 @@ # Full map — mattpocock/skills (v1.2.3, HEAD 84fdeff, 2026-08-06) ↔ melodic-software/claude-code-plugins (main a89a4a33) +> **Correction (2026-08-17):** this map's "Claude-only private marketplace" characterization +> (Codex-sidecar row and the marketplace row of the cross-cutting table) is stale — the +> repository is PUBLIC (verified via the repo listing during the pocock-course-lanes effort). +> The Claude-only part stands; the private part does not. The map is otherwise a point-in-time +> record as of its header date. A 2026-08-17 recheck at HEAD `068b6e0` found the 35-skill +> inventory and all relation rows structurally intact (record: `aihero-course.md` effort + +> the pocock-course-lanes contract). + Sources: his-repo full inventory (35 skills, every SKILL.md read), our-repo provenance sweep (git log + grep + docs), v1.2.0 release notes, v1.2 changelog article, video transcript. As-of 2026-08-08. Legend — **Relation**: DERIVED (attributed port), PARTIAL (specific ideas taken, attributed), CONVERGENT (same territory, no provenance), NONE (no counterpart). **v1.2+ delta**: what changed upstream since our port / what's new. diff --git a/docs/upstream/mattpocock-skills.md b/docs/upstream/mattpocock-skills.md index 1c579b63f..b6a00c426 100644 --- a/docs/upstream/mattpocock-skills.md +++ b/docs/upstream/mattpocock-skills.md @@ -32,11 +32,11 @@ divergence-at-re-fetch recheck regime. | `triage` + its `.out-of-scope/` KB (`OUT-OF-SCOPE.md`) | `work-items:triage` | Derived (structured port) | "A PR is an item with attached code" ≈ upstream's "a PR is an issue with attached code"; state-machine framing convergent. Corrected in lane 5 — this row previously claimed "no structured port", which is provably false: the rejected-concept ledger (work-items 0.6.0; triage's ledger check + won't-fix/already-implemented outcomes) is a structured port of upstream's `.out-of-scope/` KB — one-file-per-concept, concept-similarity-not-keyword matching, never-ledger-built-features, and the near-verbatim "so the same request doesn't return as fresh code" (upstream `OUT-OF-SCOPE.md:86`) map one-to-one; ours is a superset. The v1.2 `.out-of-scope/` adoption candidate (M15) is therefore REJECTED as already-adopted; provenance row corrected only — no `work-items` behavior change (the topic plan's out-of-scope bars it) | | `to-tickets` | `work-items:decompose` | Influence (vocabulary) | Vertical-slice / tracer-bullet decomposition vocabulary overlaps upstream; mechanics are house-built on the work-item seam | | `improve-codebase-architecture` YAGNI scoping filter (v1.2 #533) | `architecture:improve` deepening Phase 1 | Partial | ADOPTED scope-before-scanning: user-named direction scopes the scan, else recent-commit hot spots pull attention first (precomputed context widened to 20 commits). REJECTED his `CONTEXT.md` reference (our glossary-discovery ladder) and HTML-report machinery (previously rejected) | -| `diagnosing-bugs` (v1.2.3 Redact + tagged logs) | `debugging:debug`, `testing:diagnose` | Partial | ADOPTED the redaction guard in both skills (secrets `` before any shown command/output/artifact; env-var credentials; signal-lines-only quoting) and the `[DEBUG-a4f2]` tagged-log convention in `testing:diagnose` (already present in `debugging:debug`). TRACKED, not adopted: feedback-loop-first doctrine (10 ranked loop types, 3–5 ranked hypotheses) — our phase structures work; re-evaluate on a release whose changeset names `diagnosing-bugs` | +| `diagnosing-bugs` (v1.2.3 Redact + tagged logs) | `debugging:debug`, `testing:diagnose` | Partial | ADOPTED the redaction guard in both skills (secrets `` before any shown command/output/artifact; env-var credentials; signal-lines-only quoting) and the `[DEBUG-a4f2]` tagged-log convention in `testing:diagnose` (already present in `debugging:debug`). TRACKED, not adopted: feedback-loop-first doctrine (10 ranked loop types, 3–5 ranked hypotheses) — our phase structures work; re-evaluate on a release whose changeset names `diagnosing-bugs`. Annotation (2026-08-17 recheck, unreleased): upstream dropped its Phase 6 post-mortem step ("Cleanup + post-mortem" reduced to "Cleanup"; the what-would-have-prevented-this handoff to improve-codebase-architecture removed) — weigh alongside this row when the release trigger fires | | `wait-what` (Productivity, NEW in v1.2 #751) | `discipline:wait-what` | Derived | Ported near-verbatim (one-sentence re-pitch body: back up, add missing context, ASD-STE100 register + inline gloss, ubiquitous language) as a declared non-corrector species in `discipline` beside `tighten-your-output`/`mind-your-maxims` — home chosen on the blame axis (the drift is the model's output, not the user's comprehension). Name KEPT with an explicit PLUGIN-PHILOSOPHY naming-exception entry (utterance-is-mechanism + upstream muscle-memory parity; a 5-generator/3-judge naming tournament's grammar-clean winner `re-pitch` was declined by the user). REJECTED his fixed `CONTEXT.md` filename (our format-externalized glossary discovery: nearest glossary per consumer convention, silent degradation). Shape evidence: his X thread (status 2084753070437609606 → 2084941367659168064 → 2085681281795232026) — the same instruction failed as passive global CLAUDE.md AND as an output style; only the on-demand skill works, so the register text lives in the body, invoked at the moment of loss | | `wizard` (Engineering; graduated from in-progress in v1.2) | `wizard:generate` | Derived | PORTED (lane 4) as a new single-capability plugin `wizard` 0.1.0, hardened. Kept: the 4-step scope/map/author/verify process, the fixed never-hand-edited library above the `STAGES` marker, model-invoked posture with the explicit non-trigger fence, gh-absence graceful degradation, ephemeral-by-default doctrine, agent-authors-never-runs doctrine. Hardened beyond upstream (deltas enumerated in `plugins/wizard/CHANGELOG.md` 0.1.0): mandatory human read-and-approve of the full STAGES block before `chmod +x`; https-only `open_url` (also closes a Windows UNC/NTLM leak via explorer.exe); `/dev/tty` fail-closed prompts (retires a verified multi-line-paste confirm bypass and `pause`'s fail-open at EOF); quoted `0600` `.env` writes + gitignore assert + trap-cleaned atomic temp; repo-resolved/confirmed `--repo`-explicit gh writes with stderr surfaced and empty values refused; key-name validation; readline on non-secret asks (fixes upstream #741 where safe); names-only live-`.env` scoping with the secrets-and-context property stated honestly. REJECTED: Codex `agents/openai.yaml` sidecar (no Codex target — standing precedent) | | `prototype` `LOGIC.md` shareable-HTML demo (Engineering, v1.2) | `prototype:pressure-test` | Partial | ADOPTED (lane 5) the audience-routed HTML demo shell: TUI stays default; when the driver is a non-developer (designer, PM, domain expert) or no terminal fits, the disposable shell over the same portable pure logic module is one self-contained `file://` page — domain-language labels, labelled state panel re-rendered per click, free-play buttons, guided-walkthrough scenarios resetting to a known initial state — under explore-directions' existing HTML-substrate constraint set reused verbatim-in-spirit (restrictive CSP meta tag, ephemeral `mktemp -d` / `%LOCALAPPDATA%\Temp` placement, synthetic data only, discard after the markdown capture). prototype 0.5.0. REJECTED the other half of upstream's step 5: the throwaway-branch "primary source" capture that keeps the prototype re-runnable on a branch — a two-lane branch-naming posture violation that also contradicts the plugin's delete-when-done discipline (`plugins/prototype/context/discipline.md`, "Delete or absorb when done") | -| ask-matt `PHASE-BOUNDARIES.md` (v1.2) | `session-flow:workflow` continuation router + `context-guard` zones | Convergent / rejected | Tree audited element-by-element at parity or stronger (ordered first-yes-wins router, compact-last-with-steering, boundary-only trigger; ours adds clean-stop, user-gated background, instrumented zones, worker relay). ADOPTED one zone-gated criterion: prefer continue when the next stage consumes this stage's reasoning verbatim. REJECTED "handoff only for what travels" narrowing (contradicts our fork-beats-compaction stance) and the ~150k smart-zone figure (self-declared-debated folklore; no official numeric threshold exists — our measured bands stand, his dictionary entry noted as one more folklore anchor) | +| ask-matt `PHASE-BOUNDARIES.md` (v1.2) | `session-flow:workflow` continuation router + `context-guard` zones | Convergent / rejected | Tree audited element-by-element at parity or stronger (ordered first-yes-wins router, compact-last-with-steering, boundary-only trigger; ours adds clean-stop, user-gated background, instrumented zones, worker relay). ADOPTED one zone-gated criterion: prefer continue when the next stage consumes this stage's reasoning verbatim. REJECTED "handoff only for what travels" narrowing (contradicts our fork-beats-compaction stance) and the ~150k smart-zone figure (self-declared-debated folklore; no official numeric threshold exists — our zone instrumentation stands, his dictionary entry noted as one more folklore anchor; wording corrected 2026-08-17 per pocock-course-lanes audit A1: context-guard's shipped bands are declared judgment defaults with named provenance, not measurements — this row previously overclaimed them as "measured") | ## Not adopted (decided, with reasons) @@ -86,6 +86,14 @@ Two `writing-for-agents` strands from v1.2 (lane 5) — tracked on events, never mattpocock/skills release whose changeset names `writing-for-agents`, OR a repo review/audit surfacing a skill that instructs model invocation of a `disable-model-invocation: true` target. + **Annotation (2026-08-17 recheck, HEAD `068b6e0`, unreleased):** the invariant's substance + landed on main and hardened (his PRs #878/#880 + `.agents/invocation.md`): cross-skill + dependencies standardized as an explicit `Call the Skill tool with "name"` instruction (one + skill per call; his stated reason: higher hit rate than bare `/name` prose, harness-neutral), + and user-invoked skills declared unreachable from any skill — preconditions on them must be + phrased "tell the user to run /x". Changesets exist, so the next release fires this trigger; + the portable authoring question for OUR cross-skill invocation phrasing is recorded in + `aihero-course.md`'s effort record (pocock-course-lanes). ## Harness findings learned from this upstream (recheck-worthy) From eac1af86dee3cd7c567e14929be7f1912eee8ab7 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 12:08:51 +0000 Subject: [PATCH 18/22] chore(topics): prune pocock-course-lanes working slices for the PR Removes the effort's contract, lesson sources, and lane summaries per the contract-slice prune gate: durable outcomes live in docs/upstream/aihero-course.md, the SSOT annotations, the six closed issues (#2899-#2904), and the filed items; the coverage index and lane records are carried in the PR body. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/topics/pocock-course-lanes/PLAN.md | 265 ------------------ .../lessons/01-handing-off.md | 120 -------- .../02-clear-compact-handoff-subagent.md | 123 -------- .../03-compaction-and-auto-compaction.md | 243 ---------------- .../lessons/04-why-plan-mode-sucks.md | 110 -------- .../lessons/05-grill-execute-clear.md | 112 -------- docs/topics/pocock-lane-1/SUMMARY.md | 62 ---- docs/topics/pocock-lane-2/SUMMARY.md | 66 ----- docs/topics/pocock-lane-3/SUMMARY.md | 44 --- docs/topics/pocock-lane-4/SUMMARY.md | 47 ---- docs/topics/pocock-lane-5/SUMMARY.md | 32 --- docs/topics/pocock-lane-6/SUMMARY.md | 38 --- 12 files changed, 1262 deletions(-) delete mode 100644 docs/topics/pocock-course-lanes/PLAN.md delete mode 100644 docs/topics/pocock-course-lanes/lessons/01-handing-off.md delete mode 100644 docs/topics/pocock-course-lanes/lessons/02-clear-compact-handoff-subagent.md delete mode 100644 docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md delete mode 100644 docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md delete mode 100644 docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md delete mode 100644 docs/topics/pocock-lane-1/SUMMARY.md delete mode 100644 docs/topics/pocock-lane-2/SUMMARY.md delete mode 100644 docs/topics/pocock-lane-3/SUMMARY.md delete mode 100644 docs/topics/pocock-lane-4/SUMMARY.md delete mode 100644 docs/topics/pocock-lane-5/SUMMARY.md delete mode 100644 docs/topics/pocock-lane-6/SUMMARY.md diff --git a/docs/topics/pocock-course-lanes/PLAN.md b/docs/topics/pocock-course-lanes/PLAN.md deleted file mode 100644 index e45471b24..000000000 --- a/docs/topics/pocock-course-lanes/PLAN.md +++ /dev/null @@ -1,265 +0,0 @@ -# pocock-course-lanes - -Brief locked via `/planning:interview me` (rounds 1–3, all nine questions decided; register -gated clean; **user confirmed the shared understanding 2026-08-17 — interview closed**). The -working ledger lives in the topic's memory slice (`.work/pocock-course-lanes/`, disposable per -session — this committed file is the durable record). Next action: open lane 1 -([#2899](https://github.com/melodic-software/claude-code-plugins/issues/2899)) in a fresh -session via `/work-items:work 2899`. - -## Brief - -### TLDR - -Vet the AI Hero course lessons (plan mode, grilling, compaction, handoff, phase boundaries, -auto-compaction) against this marketplace's plugins in six independent lanes — each lane -interview-first with our own skills, each ending in recorded adopt/reject/track decisions, filed -work items for any plugin change, and a lane summary. Source material is course content — a -distinct source from the already-audited mattpocock/skills repo (SSOT current at v1.2.3 -`@84fdeff`). - -### Goal - -Every opinionated claim in the six pasted lessons is *represented*: mapped to a decision row, a -filed work item, or an explicit not-relevant note — nothing silently dropped. The lanes, -**numbered in locked run order** (matching the lane index — this is the ONLY lane numbering this -contract uses; audit fix 2026-08-17): - -1. **handoff** — his 15-line skill vs our save-point engine; the purpose-argument adoption - candidate; handoff-file expiry/accumulation; ephemerality philosophy (OS temp vs memory - tier). **Use-case boundary evaluation** (user, round 3): our dominant real use is a hard - session-chain handoff — dumb-zone escape → session-ID chain → whole-picture reconstruction - for retrospectives; functionally a compact-replacement that regathers — while his taxonomy - centers on crossing boundaries (other agent, other repo, colleague, forked side task). - Decide which use cases our handoff officially owns, which route elsewhere, and whether the - session-chain/retrospective use deserves first-class support. **Also creates the - `docs/upstream/aihero-course.md` skeleton** (audit amendment A2 — see below). -2. **phase-boundaries decision tree** — element-by-element re-audit of the - `session-flow:workflow` continuation router against the *course* version of his tree (the - SSOT audited repo `PHASE-BOUNDARIES.md`, not this lesson); includes subagent-not-a-terminal - and the AFK criterion. Carries the effort's build deliverable (the context-driven router — - Q9). -3. **compaction doctrine** (merges the Compaction + Auto-Compaction lessons) — - fork-beats-compaction vs his compact-as-default; the `context-guard` evidence-degraded marker - vs his steered-compact-for-QA case; auto-compact stance; `autoCompactWindow` and - compaction-mechanics claims verified against official docs. -4. **plan-mode/asset-rush** — his plan-mode critique vs our interview→plan sequencing; audit - whether `lock` / auto-synthesize is a licensed exception or a quiet re-introduction of the - asset rush. -5. **grilling↔interview parity** — course-lesson deltas against `planning:interview` (expected - mostly confirmation; small tree). -6. **shared vocabulary + provenance** — which dictionary terms (smart zone, primary/secondary - source, AFK, design concept, phase boundary) we adopt as ubiquitous language; owns the - coverage index, term adoption, and final consolidation of `docs/upstream/aihero-course.md` - (skeleton created by lane 1 per A2). Runs last; harvests from all other lanes. - -### Constraints - -- **Interview-first per lane**: each lane opens with `/planning:interview me `, using - marketplace skills throughout (`discovery:explore` / `discovery:research`, - `planning:brainstorm`, discipline skills as fits). -- **Claim ladder** (vetting standard): (i) harness-behavior claims → verified live against - current official docs before being repeated or acted on; (ii) empirical quality claims → - classified against **instrumented zone readings plus `context-guard`'s declared - judgment-default bands (named provenance)** — his figures recorded as anchors never adopted - as numbers *(amended 2026-08-17 per audit A1: the prior "measured bands as baseline" wording - was refuted by both validators — context-guard's own reader contract states the shipped band - thresholds are "declared judgment defaults", not measurements; only the zone readings are - measured. The honest distinction vs his figures is provenance-and-tunability, not - measurement)*; (iii) design opinions → decided adopt/reject/track against our plugin - philosophy, never "verified" by research. -- **Lanes discuss and decide; they do not implement.** Plugin changes leave the lane as filed - work items and execute via the normal implementation pipeline. -- **Cloud durability**: decisions are promoted into committed-and-pushed artifacts (this file, - the provenance doc, tracker items) the moment they lock; `.work/` is a per-session cache and - is never load-bearing. -- **Lesson-source handling (amended 2026-08-17, user decision):** this repository is PUBLIC - (the v1.2 map's "Claude-only private marketplace" line is stale — a lane-6 bookkeeping - correction). The user reviewed the flag and authorized committing the lesson texts — they are - framing around his MIT-licensed public skills — so the sources live TRACKED at - `docs/topics/pocock-course-lanes/lessons/01`–`05` (numbered by lane run order; lane 6 - harvests and has no single lesson), attributed to aihero.dev in each header, durable across - containers for the life of the effort, and PRUNED with the topic slice in the final PR (the - contract-slice-prune-gate enforces this), so they never merge to the default branch. - Provenance rows in `aihero-course.md` still paraphrase and cite rather than reproduce — - that doc is durable-tier and permanent. - -### Acceptance criteria - -- Six lanes each closed with the three fixed outputs: adopt/reject-with-reason/track-on-event - rows in `docs/upstream/aihero-course.md`, work items filed for every decided plugin change, - and a lane summary in the lane's topic slice. -- A coverage index in this topic maps every lesson claim to its disposition (decision row / - filed item / not-relevant note). -- `docs/upstream/aihero-course.md` exists with its own recheck-trigger discipline — triggers - phrased as **divergence-at-re-fetch** (a read-time re-fetch finds a lesson no longer matching - the record; the form `docs/conventions/upstream-drift/README.md` sanctions), never bare - "when the lesson updates" — and is cross-linked from `docs/upstream/mattpocock-skills.md`. - Skeleton (row schema + trigger form, inherited from the upstream-drift four-part record and - the SSOT attribution-table shape) is created by lane 1; lane 6 owns the coverage index, term - adoption, and final consolidation (audit amendment A2). - -### Captured assumptions - -- Discussions are user+Claude working sessions; no external participants — hence topic dirs + - tracker items rather than GitHub Discussions. (Round 1 probe drew no contrary constraint; - flip to Discussions if that changes.) - -### Out-of-scope - -- Executing plugin changes inside a lane session. -- Re-auditing the mattpocock/skills repo itself (SSOT current; recheck trigger unchanged). - -### Decided in rounds 2–3 (previously deferred) - -- Q6 — lane order: handoff → phase-boundaries → compaction → plan-mode → grilling → - vocabulary/provenance. -- Q7 — dispatch: one background `/discovery:research` for the harness-claims bundle - (`autoCompactWindow`, compaction mechanics, plan-mode behavior — verified against current - official docs); `/discovery:explore` and `/planning:brainstorm` fire per lane at open; - nothing else speculative. (The pre-lane inventory recheck already ran — see below.) -- Q8 — durability: git + GitHub are the only durable spine; `.work/` never load-bearing; - every session ends with clean-stop semantics (commit + push + issue updates); one GitHub - issue per lane. - **Amended 2026-08-17 (user, post-lock):** execution model is a single session CHAIN on THIS - branch, not per-lane branches/PRs. Each lane transition is `/session-flow:handoff` → - `/clear` → paste the resume prompt (dedicated context per lane, chain continuity via - `previous_handoff` + session ids — the same generic process this contract was built with: - interview-first, skills, explore/research, decisions committed as they land). All six lanes - commit to `claude/plan-mode-discussion-55kszx`; ONE PR at the very end when all lanes are - closed. The handoff files are a convenience layer inside the container; the committed - contract remains the durable record (clean-stop discipline unchanged). - **Audit-discovered obligations (2026-08-17, both validators):** (a) the CI - `contract-slice-prune-gate` red-lines any PR whose net diff adds or edits under - `docs/topics/**` — the ONE final PR must therefore carry a prune commit removing the parent - topic dir and every opened lane slice, their substance preserved via PR-body paste + - pointers per the topic-docs contract-slice lifecycle (durable outcomes live on in - `aihero-course.md`, the issues, and the PR body — the git+GitHub spine claim still holds); - (b) the paste-resume directive references a `.work/` handoff file a recycled container - loses — expected degradation: resume from this committed contract + the lane issue instead. -- Q9 — decision-matrix skill: evolve `session-flow:workflow`'s `continue` router (no new - skill) to consume session history, the overarching plan, work-item state, and the - context-guard zone; **suggest-by-default, autonomous only as an explicit opt-in**, designed - around instruction-audit check I23 (no exit menus injected into model context). This is - lane 2's build deliverable (phase-boundaries — run-order numbering per the lane index). - -### Deferred questions - -*(none — all nine questions decided)* - -### Audit record (2026-08-17, `/planning:audit-answers` — user approved) - -Two fresh-context validators independently re-examined all nine decisions with the -recommendation rationale withheld. Merged outcome: Q1, Q2, Q4, Q5, Q7, Q8, Q9 CONFIRMED with -evidence; Q3 CHALLENGED by **both** validators (the "measured bands" premise — amended per A1, -in Constraints); Q6 CHALLENGED by one (the `aihero-course.md` creation contradiction — amended -per A2: lane 1 creates the skeleton with fixed row schema, lane 6 consolidates). Editorial -fixes applied in the same pass: six-lesson count, run-order-only lane numbering, Q9's lane -label, divergence-at-re-fetch trigger phrasing, and the Q8 prune-gate + resume-degradation -obligations. Lane-6 bookkeeping gained one item: correct the SSOT row-35 "our measured bands -stand" overclaim to match context-guard's own "declared judgment defaults" language. - -## Lane index (filed 2026-08-17, in locked run order) - -| Lane | Issue | Status (as-of 2026-08-17) | Scope | -|------|-------|--------|-------| -| 1 handoff | [#2899](https://github.com/melodic-software/claude-code-plugins/issues/2899) | **CLOSED** (`ffb01459`; filed #2955–#2957) | use-case boundaries, purpose argument, expiry, ephemerality | -| 2 phase boundaries | [#2900](https://github.com/melodic-software/claude-code-plugins/issues/2900) | **CLOSED** (`64fe359e`; filed #2971–#2973) | tree re-audit + context-driven continuation router (build deliverable) | -| 3 compaction doctrine | [#2901](https://github.com/melodic-software/claude-code-plugins/issues/2901) | **CLOSED** (filed #2995; Q24–Q30) | fork-beats-compaction, auto-compact stance, evidence-degraded marker, harness claims | -| 4 plan-mode | [#2902](https://github.com/melodic-software/claude-code-plugins/issues/2902) | **CLOSED** (no items filed; Q31–Q35) | asset-rush critique vs interview-first sequencing, lock-mode audit | -| 5 grilling parity | [#2903](https://github.com/melodic-software/claude-code-plugins/issues/2903) | **CLOSED** (no items; Q36–Q37) | course-lesson deltas vs planning:interview | -| 6 vocabulary + provenance | [#2904](https://github.com/melodic-software/claude-code-plugins/issues/2904) | **CLOSED** (Q38–Q40; glossary deferred to user) | aihero-course.md consolidation (created by lane 1 per A2), term adoption, SSOT TRACK annotations + row-35 and "private marketplace" corrections, coverage index | - -This table is the persistent roadmap: each closing lane session updates its row (status + -closing commit + filed items) in the same commit that closes the lane, so any fresh session -reads current progress from this file alone. Lesson sources: `lessons/01`–`05` beside this -file. The handoff chain (`.work/handoffs/*-handoff-pocock-lane-N.md`, `previous_handoff` -links) carries per-session state; this file carries the journey. - -Background research dispatched pre-lane: harness-claims bundle → -`.work/pocock-course-lanes/harness-claims/` (memory tier; full evidence + fetch logs live there; -re-dispatch `/discovery:research` if the slice is gone and a lane needs the evidence detail). - -## Harness-claims verdicts (verified 2026-08-17 — durable summary) - -Research run gated clean (artifact + coverage gates exit 0); fresh-context verifier graded -corroboration; parent cured C3 with a binary-schema probe and applied project fit. Verdicts safe -for lanes 3–5 to cite, with corroboration labels: - -| # | Course claim | Verdict | Corroboration | -|---|---|---|---| -| C1–C2 | `autoCompactWindow` exists; controls when auto-compact fires | CONFIRMED | two-pool (docs + binary) | -| C3 | range 100,000–1,000,000 tokens | CONFIRMED | two-pool (docs + binary schema `min(1e5).max(1e6)`) | -| C4 | compaction "seeds a fresh session" | **REFUTED** — same session continues over a structured summary; only fork/`--fork-session` makes a new session ID | two-pool | -| C5 | messages queue during compaction | UNDOCUMENTED — verify empirically before teaching | n/a | -| C6 | `/compact [instructions]` accepts focus instructions | CONFIRMED | single-pool (docs only) | -| C7 | Shift+Tab cycling / `--permission-mode plan` entry | CONFIRMED (no fixed press count) | two-pool | -| C8 | ExitPlanMode approval flow (+ newer EnterPlanMode tool) | CONFIRMED (flow details docs-only) | two-pool | -| C9 | `/plan` views the current plan | PARTIALLY TRUE — `/plan [description]` exists but ENTERS plan mode; no documented command views the plan | absence half two-pool; positive half docs-only | - -Cures for the single-pool rows when convenient: run `/compact ` and `/plan` in a -live interactive session (Tier-0). - -## Coverage index (lane 6, 2026-08-18) — the "everything is represented" gate - -Every claim in the six pasted lessons maps to a disposition. The claim-level enumeration IS the -lane sections of [`docs/upstream/aihero-course.md`](../../upstream/aihero-course.md) (49 rows -total; counts verified against the doc); this index points, per the do-not-duplicate rule, and -records what sits outside the rows: - -| Lesson (committed source) | Dispositions | Where | -|---|---|---| -| Handing Off (`lessons/01`) | 9 rows: 3 ADOPT, 4 REJECT, 2 COVERED; items #2955 #2956 #2957 | aihero-course.md Lane 1 | -| Clear/Compact/Handoff/Subagent (`lessons/02`) | 10 rows: 1 ADOPT-modified, 3 REJECT, 6 COVERED; items #2971 #2972 #2973 | aihero-course.md Lane 2 | -| Compaction (`lessons/03`, first half) | rows within Lane 3's 12: compact-as-default REJECT, seeds-fresh-session REJECT (C4), steering COVERED (C6), queueing UNKNOWN (C5), QA carve-out REJECT track-on-event, vocabulary ADOPT-terms | aihero-course.md Lane 3; item #2995 | -| Auto-Compaction (`lessons/03`, second half) | rows within Lane 3's 12: autoCompactWindow CONFIRMED (C1-C3), every-harness NOT RELEVANT, mid-phase COVERED, human-owns-boundary ADOPT | aihero-course.md Lane 3; item #2995 | -| Why Plan Mode Sucks (`lessons/04`) | 9 rows: 2 ADOPT-convergent, 1 REJECT (stale /plan demo, C9), 3 COVERED, 2 CONFIRMED walkthrough, 1 NOT RELEVANT; no items | aihero-course.md Lane 4 | -| Grill-Execute-Clear (`lessons/05`) | 9 rows: 8 COVERED (parity, several stronger), 1 NOT RELEVANT (course machinery); no items | aihero-course.md Lane 5 | - -Outside the rows, also represented: the harness-claims verdict table (C1-C9, this file) grades -every mechanical claim the lessons make about Claude Code; quiz-answer claims are covered where -they restate lesson claims (the two that add error, C4's "seeds a fresh session" and "compaction -writes no file", are named in Lane 3's rows); dictionary-term candidates are the lane-6 -term-adoption set; course-platform machinery (npm run reset, commit maps, skill-picker -walkthroughs, Discord) carries NOT RELEVANT rows or is excluded as non-claims. Known-open cures, -deliberately not blockers: C5 empirical probe, C6/C9-positive second-pool probes (interactive -session required). The parallel teach-skill comparison (local branch -`claude/teach-skill-comparison-h3rpag`) is in-flight with no outcomes yet; its future results -are bound to this provenance home by the guard comment on #2904. - -## Upstream recheck — 2026-08-17 (pre-lane gate) - -`/discipline:recheck-against-upstream` run against mattpocock/skills HEAD `068b6e0` -(2026-08-15) from the audited baseline v1.2.3 `@84fdeff`; shallow clone at -`/workspace/mattpocock/skills` (session-local, disposable). Findings: - -- **Inventory intact**: 35 skills, zero additions/removals/renames — the v1.2 map's - his↔ours rows are structurally accurate; grilling→`planning:interview`, - handoff→`session-flow:handoff`, phase-boundaries→`session-flow:workflow continue` - mappings all confirmed. -- **No new release**: latest tag is still v1.2.3, so the SSOT's release-based recheck - triggers have NOT fired; all drift below is unreleased main. -- **Invocation-reach invariant hardened** (PRs #878/#880, `.agents/invocation.md`): - cross-skill dependencies standardized on "Call the Skill tool with \"name\"" (one skill - per call; his stated reason: higher hit rate than bare `/name` prose, harness-neutral); - user-invoked skills declared unreachable from any skill — preconditions on them must be - phrased "tell the user to run /x". This is the SSOT's *tracked* writing-for-agents - strand: substance has landed on main with changesets, release pending — the tracked - row's trigger will fire on the next release. Portable authoring question for OUR skills - (cross-skill invocation phrasing) → lane 6 candidate. -- **`diagnosing-bugs` dropped its post-mortem step** (Phase 6 "Cleanup + post-mortem" → - "Cleanup"; the "what would have prevented this bug → improve-codebase-architecture" - handoff removed). Relevant to the SSOT's diagnosing-bugs TRACK row when its release - trigger fires. -- **Rest of the diff**: em-dash/phrasing cosmetics (grilling #879, others) — no delta to - our derived skills. -- **Skipped**: nothing — every changed file since baseline was inspected (15 skill files + - `.agents/invocation.md`). - -Verdict: our map and SSOT audit clean at their recorded baseline; no doc corrections -required now. Annotating the two TRACK rows with the landed-but-unreleased evidence is -lane-6 bookkeeping. - -## Plan - -*(empty — `/planning:plan` fills this after the Brief locks)* diff --git a/docs/topics/pocock-course-lanes/lessons/01-handing-off.md b/docs/topics/pocock-course-lanes/lessons/01-handing-off.md deleted file mode 100644 index 79ef9fa91..000000000 --- a/docs/topics/pocock-course-lanes/lessons/01-handing-off.md +++ /dev/null @@ -1,120 +0,0 @@ - - -# Handing Off - - - Start the lesson: the `/handoff` skill added to `.agents/skills/` - - -In the previous exercise, I showed you how [compaction](https://www.aihero.dev/ai-coding-dictionary/compaction) works: you take one [session](https://www.aihero.dev/ai-coding-dictionary/session)'s [primary source](https://www.aihero.dev/ai-coding-dictionary/primary-source), summarize it into a [secondary source](https://www.aihero.dev/ai-coding-dictionary/secondary-source), and seed a new session with it. - -Compaction, though, has some constraints. It can only compact within the same directory, and it can only compact within the same [agent](https://www.aihero.dev/ai-coding-dictionary/agent). - -For instance, if we did some implementation with Claude and wanted to [hand off](https://www.aihero.dev/ai-coding-dictionary/handoff) to another AI agent like Codex to review it, how would we do that with compaction? We can't. - -## The /handoff skill - -There is one way to do it though, and I encounter this situation so often that I made a [skill](https://www.aihero.dev/ai-coding-dictionary/skill) for it. - -The theory is straightforward: instead of compacting inside the agent (in memory), you create a `handoff.md` file, a markdown file. That markdown file is totally portable. You can do anything you like with it. - -- Feed it into Codex -- Pass it to an agent in another directory -- Send it to a colleague -- Use it to hand off a side task you discovered mid-feature - -One really great situation is when you're working on a feature, you notice a random bug that's unrelated to what you're building, and you want to fix it later in a separate session. You can just create a [handoff artifact](https://www.aihero.dev/ai-coding-dictionary/handoff-artifact) and come back to it. - -### Looking at the skill - -First, run `npm run reset` and choose the handoff skill lesson from the list. - -If we look inside the skill directory, we have a `/handoff` skill. Like most of my skills, it's pretty short. - -```markdown -Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace. -``` - -One useful feature here is that it saves to the temporary directory of the user's OS. This means these handoff documents are designed to be ephemeral. They're not going to be saved locally in your project, and they won't be stored in any memory. They will be deleted when your computer resets, or whenever the OS decides to clear the temporary directory. - -(OS stands for operating system: Windows, Mac, Linux, whatever.) - -## Using handoff in practice - -Let me show you how this works. I'm going to resume a previous session and work with the star rating review system. - -We're at around 89k [tokens](https://www.aihero.dev/ai-coding-dictionary/token), which might be a good moment to hand off. To use the `/handoff` skill, I'm going to run the command and pass it a reason: - -``` -/handoff pass to Codex to review -``` - -Just like with compact, we give the `/handoff` skill a reason for the handoff. This tells it the purpose of the next session. - -It comes back and [requests permission](https://www.aihero.dev/ai-coding-dictionary/permission-request) to write to the temporary directory. Perfect. - -Now we can see the handoff file. It's a really nice, detailed secondary source of all the things we might need to review. It looks fairly similar to the compacted documents we saw before: nice and detailed, with lots of file references and everything else. - -The handoff document includes: - -- What the feature is -- Files to review (with git status / git diff instructions) -- Key decisions or bugs fixed mid-session -- Known pre-existing issues (not part of this change) -- Verification already done -- Project conventions the diff should conform to -- Review angles worth probing -- Suggested skills for the next session - -The way I would seed this into a new session is to open it in a separate window. I've just run `/clear`, so I've got a totally empty session. Now I can use the `@` symbol to reference the file: - -``` -@/tmp/handoff-course-star-ratings-review.md -``` - -Once this gets seeded, it gets immediately read into the [context window](https://www.aihero.dev/ai-coding-dictionary/context-window) and it's ready for review. - -I'll just cancel out of that because I don't actually want it to do the review right now. - -## /handoff vs. Compact - -That's how the `/handoff` skill works. It's really nice for: - -- Passing work to separate agents -- Saving a document you can send to a colleague -- Handing off to another agent in a different repo to fix a bug you encountered - -It's just like compaction, except a little bit more flexible and a little bit more involved. - -I wouldn't say that handoff is a total replacement for compaction. Here's when to use each: - -| When | Use | -| ------------------------------------------------ | ------------------------------------------------------------------ | -| Staying in the same directory | Compaction | -| Retaining context of the previous conversation | Compaction | -| Don't care about retaining previous conversation | Compaction (especially because you can queue up messages after it) | -| Passing to a different agent | `/handoff` | -| Handing off to another repo | `/handoff` | -| Sending to a colleague | `/handoff` | - -Compaction is still really good. `/handoff` is nice too, but the linking to the next conversation is a little bit more involved, and it's only really useful if you're getting something out of it. - -We're going to do a full comparison in the next lesson. Nice work, and I'll see you there. - - - - - diff --git a/docs/topics/pocock-course-lanes/lessons/02-clear-compact-handoff-subagent.md b/docs/topics/pocock-course-lanes/lessons/02-clear-compact-handoff-subagent.md deleted file mode 100644 index 78ef2b10c..000000000 --- a/docs/topics/pocock-course-lanes/lessons/02-clear-compact-handoff-subagent.md +++ /dev/null @@ -1,123 +0,0 @@ - - -# Clear, Compact, Handoff, Or Subagent - -In the coding [sessions](https://www.aihero.dev/ai-coding-dictionary/session) we've done so far with [agents](https://www.aihero.dev/ai-coding-dictionary/agent), you might have noticed that they break down into pretty discrete chunks. We've had a [grilling](https://www.aihero.dev/ai-coding-dictionary/grilling) phase, then an implementation phase, and then a QA phase at the end. We [compacted](https://www.aihero.dev/ai-coding-dictionary/compaction) before we started QA-ing. - -These phases are loosely defined. They're really just chunks of work within a coding session. Each phase is composed of two parts: the actual phase itself (the running of the grilling, implementation, or QA), and the boundaries between them. - -The boundaries are really important. They represent a decision point where you're deciding what to do with the session at each phase boundary. - -## Understanding Phase Boundaries - -By the time we finished grilling, we were only at about 30k [tokens](https://www.aihero.dev/ai-coding-dictionary/token). It made sense to continue directly on with the implementation. That meant the implementation could rely on the [primary source](https://www.aihero.dev/ai-coding-dictionary/primary-source) of the grilling without any kind of [secondary source](https://www.aihero.dev/ai-coding-dictionary/secondary-source) lossiness there. - -But by the time we finished implementation and we wanted to QA it, we decided to compact it. We'd used up our [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) really, and we wanted to get rid of all the cruft and just use the good stuff for the QA. - -The way to come to those decisions isn't particularly obvious. You actually have **five choices** for things you can do at these phase boundaries. - -## Your Five Options - -| Option | What It Does | -| ------------ | --------------------------------------------------------------- | -| **Continue** | Stay in the current session, no context switch needed | -| **Clear** | Totally clear your context window and start fresh | -| **Compact** | Compress your context and seed a new session with it | -| **Handoff** | Create a markdown file summarizing the session to pass anywhere | -| **Subagent** | Spawn a subagent to handle the task and report back | - -Wielding these five options is not trivial. I've created a decision tree to help you navigate them. - -## The Decision Tree: Start At The Top - -When you've reached the end of a phase and you're not quite sure what to do, you start here. - -### Question 1: Can You Continue? - -**Does it make sense to continue in the current session?** - -This is a fairly rich decision in itself. Between grilling and implementation, it obviously makes sense to continue because we've got that rich primary source that we need. We don't want to discard it for when we get to the implementation. - -You may also want to continue if you just have enough smart zone budget left. If you're at 80k tokens maybe and you know the task is pretty small and is going to fit inside the smart zone, then yes, you can just continue. - -If you decide that you **do need to do something**, then we need to go down this little decision tree. - -### Question 2: Is Your Context Irrelevant To The Next Task? - -If you need to do something, ask yourself: **is all the information in this session totally disposable?** - -In other words, all the explorations, the decisions that were made in that session - is it totally irrelevant to what comes next? - -**If yes, clear your context window.** Clearing is the most efficient path if you can take it because it takes zero time. You're just deleting information. Then you have the most smart zone available to you. You're going back to a blank slate. - -However, if you clear the context with relevant information inside, you're losing information that might have been useful later. Imagine if I cleared rather than compacted when I went to QA. This means that the QA would know absolutely nothing about the implementation, which maybe is okay - it could figure it out from the git commits. But it would also lose all the information from the grilling as well. - -It would lose the reasoning behind the decisions that I had made. Both phases were important for the QA that then followed. So clearing just wasn't an option. - -**If no, your context is relevant.** Move to the next question. - -### Question 3: Do You Need To Hand Off? - -This is specifically about the handoff [skill](https://www.aihero.dev/ai-coding-dictionary/skill). The handoff skill is relatively narrow compared to the other options. - -You'll only need to do the handoff when you need to: - -- Pass work to another agent -- Pass work to another directory or another colleague -- Fork off a side task you discovered mid-phase without derailing the current session - -For instance, you might find something during grilling that also needs to be tackled. You can just hand off to another session while you're doing that. - -**If yes, use handoff** (`/handoff`). **If no, move to the next question.** - -### Question 4: Can The Task Be Done AFK? - -**[AFK](https://www.aihero.dev/ai-coding-dictionary/afk) means away from keyboard.** You're not touching the keyboard. You're just watching the agent go and you cannot intervene. - -This means the task is well-scoped. The agent can do it without needing your intervention at all. - -Let's imagine we wanted to do an [automated review](https://www.aihero.dev/ai-coding-dictionary/automated-review) on the implementation before [human review](https://www.aihero.dev/ai-coding-dictionary/human-review) got there. Automated review is where you send the agent into the codebase and you get it to look at the changes and check if it's broken anything or done anything weird. - -We could have compacted at this point (we're at 150k tokens from the implementation), then run the review in the main session. But since the human isn't needed for automated review, we might as well run it in a subagent. That means we just get it to run in its own context window. We don't affect the main session. - -This is a really common pattern for automated review, and it's one that we'll touch on in this course. - -**If yes, spawn a subagent.** **If no, move to the final option.** - -## The Default: Compact - -This is the bottom of the decision tree. When your context is relevant, when you want to do something with the context, and you can't continue, when you don't need to use a handoff, and when the task needs to be done with you there - then compact is the solution. - -Compact compresses your context window and seeds a new session with the good stuff. You keep what matters and discard what doesn't. - -## These Are Subjective Decisions - -These questions are not objective. There's a little bit of subjectivity, a little bit of taste in there too. You will find your own answers to these questions as you continue your work and continue working with agents. - -But I hope this concept of phases, of what you do at phase boundaries, really sinks in. This is one of the fuzziest decisions, the most interesting decisions you're going to make when you're AI coding. It's one that demands a lot of discussion and a lot of wisdom. - -[Join the Discord](https://aihero.dev/discord) and talk about these situations. Use this shared language when you discuss different scenarios. - - - - - - diff --git a/docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md b/docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md deleted file mode 100644 index 7a90dbf45..000000000 --- a/docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md +++ /dev/null @@ -1,243 +0,0 @@ - - -# Compaction - -When building features with an [agent](https://www.aihero.dev/ai-coding-dictionary/agent), you eventually reach the end of the "[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)" - the part of the [context window](https://www.aihero.dev/ai-coding-dictionary/context-window) where your [model](https://www.aihero.dev/ai-coding-dictionary/model) works best. What happens next? - -If you continue in that same [session](https://www.aihero.dev/ai-coding-dictionary/session), results [degrade](https://www.aihero.dev/ai-coding-dictionary/attention-degradation) slowly. The agent sends all previous [tokens](https://www.aihero.dev/ai-coding-dictionary/token) with every request. Those tokens are cheaper because they've been [cached](https://www.aihero.dev/ai-coding-dictionary/cache-tokens), but you're still operating in a higher latency, less capable environment. - -More importantly: how many of those tokens are actually useful? A lot of them are just noise from the work itself - file reads, file writes, files in different states as you move through the project. - -## The Naive Solution: Starting Fresh - -One option is to totally [clear](https://www.aihero.dev/ai-coding-dictionary/clearing) the [context](https://www.aihero.dev/ai-coding-dictionary/context) and start a new session. But this comes with a hidden cost. - -When you clear the context, the agent loses crucial understanding from the initial conversation. It has to re-explore and re-establish everything it knew before. You might prompt it like this: - -``` -we are going to do QA on the stuff that's literally just been worked on. -Can you go and explore it so you understand the reasons behind its existence? -``` - -The agent will do that exploration, but it's also lost some of the crucial reasoning from your initial conversation. - -It can re-explore the code and re-read what you built, but that re-exploration is lossy - you've lost a lot of the actual _why_ behind what you constructed. - -## Introducing Compaction - -This is where [**compaction**](https://www.aihero.dev/ai-coding-dictionary/compaction) comes in. Instead of clearing the context entirely, compaction takes the context from your current session, squeezes it down, and seeds a fresh session with it. - -Think of it like a [hand-off](https://www.aihero.dev/ai-coding-dictionary/handoff) between sessions that you control - similar to using a [sub-agent](https://www.aihero.dev/ai-coding-dictionary/subagent), but in reverse. The session history is summarized, then it seeds a fresh session you can continue working from. - -| Approach | Tokens | Quality | Downsides | -| ------------------------ | ------ | --------------------------- | ----------------------------------------------- | -| Continue current session | 156k+ | Full context, lots of noise | High latency, dumb zone results | -| Clear and start fresh | ~5k | Clean slate | Must re-explore everything, lossy understanding | -| Compaction | ~28k | Summarized context | Lossy compression, secondary source | - -Compaction saves re-exploration. Without it, you'd spend a ton of tokens just re-discovering context you'd already established. - -## How Compaction Works in Practice - -In your agent, you run the `/compact` command with a summarization instruction: - -``` -/compact Yeah, we're going to do some QA in this area. -``` - -This instruction matters. The thing doing the summarization is a language model, so it needs context to highlight relevant information. Your instruction doesn't need to be detailed - one sentence is often enough. - -When you launch the compaction, the agent shows a UI where it's compacting the conversation. - -Here's a useful tip: you can queue messages inside the compaction UI. Once compaction finishes, your queued message runs automatically - no need to sit around waiting. - -### What Gets Preserved - -When compaction finishes, it outputs a summary with several key elements: - -- **Primary request and intent** - what you originally asked for -- **Full agreed [spec](https://www.aihero.dev/ai-coding-dictionary/spec)** - all the decisions you confirmed -- **Key technical concepts** - important domain knowledge -- **File references** - pointers to critical files, plus some files retained verbatim -- **Errors and fixes** - what went wrong and how you solved it -- **Problem solving** - your approach and reasoning -- **All user messages** - everything you said -- **Pending tasks** - work still to do - -Here's what the token compression looks like: - -From the original session with ~156,000 tokens, the compaction summary reduced it to around 28,300 tokens. That 150k becomes 30k - giving you plenty of room back in the smart zone. - -``` -Model: claude-opus-4 -Tokens: 28.3k / 1m (3%) - -| Category | Tokens | Percentage | -|-------------------------|--------|------------| -| System prompt | 2.9k | 0.3% | -| System tools | 4.5k | 0.5% | -| Messages | 20.7k | 2.1% | -| Free space | 971.7k | 97.2% | -``` - -For example, a line from the summary might read: - -``` -- app/lib/comments.ts (new): MIN_COMMENT_LENGTH = 1, - MAX_COMMENT_LENGTH = 5000 (client-safe, mirrors ratings.ts) -``` - -This is extremely dense compression of everything you did in that previous session. - -## The Trade-off: Information Loss - -Compaction isn't without downsides. Think of it using historical terms: - -- The [**primary source**](https://www.aihero.dev/ai-coding-dictionary/primary-source) is your initial session - the record from people there at the time -- The **secondary source** is the summary - a historical summary, which is lossy compression of the primary source - -Compaction is the first hand-off mechanism you've seen that preserves context between sessions. But all hand-off mechanisms suffer from the same issue: whenever you create a secondary source, you lose information. - -However, you're gaining efficiency. Here's the trade-off: - -| Approach | Information | Noise | Maneuverability | -| ----------------------------- | ----------- | ----- | --------------- | -| Primary source (continue) | Full | Lots | Limited | -| Secondary source (compaction) | Lossy | Less | More room | - -If you continue with the primary source, you have all the information but probably along with a lot of noise. If you use the secondary source, you have more room to maneuver and less space being used up, but you might lose some of the nuances from the primary source. - -## When Compaction Shines - -However, in the exact situation where you want to do QA on a finished piece of work, compaction is a cast-iron great place to use it. You're not re-implementing. You're not making architectural decisions. You're validating something that's already complete. - -This is an introduction to compaction. You'll see how it compares to clearing and other mechanisms in upcoming lessons. - - - - - - -# Auto-Compaction - -You might be wondering: what happens if you try to push past the [context window](https://www.aihero.dev/ai-coding-dictionary/context-window) limit? Opus 4.8, which is what we're using, has 1 million [tokens](https://www.aihero.dev/ai-coding-dictionary/token) of context. What happens if you go for 1 million and 1? - -If you send a [request](https://www.aihero.dev/ai-coding-dictionary/model-provider-request) to Anthropic that has 1,000,001 tokens in it, you will get an error. The [model](https://www.aihero.dev/ai-coding-dictionary/model) simply cannot process that many tokens. - -Your [agent](https://www.aihero.dev/ai-coding-dictionary/agent) has built-in protections against hitting this hard limit. When you get to a certain point, it will [automatically compact](https://www.aihero.dev/ai-coding-dictionary/autocompact) your [session](https://www.aihero.dev/ai-coding-dictionary/session). - -## Finding Auto-Compact in Your Agent - -You can see this setting in your agent by typing the `/config` command and then searching for `auto-compact`. The matching settings appear at the top. - -The relevant configuration shows: - -``` -Auto-compact: true -``` - -with a description: "Automatically compact conversation when context fills" - -Auto-compaction exists in every single agent [harness](https://www.aihero.dev/ai-coding-dictionary/harness), because every harness has this problem. Every harness has a window in which, if you hit it, the system will pause your session and automatically compact what's in there. - -You used to be able to see this by typing `/context` to view the autocompact buffer inside the context breakdown. But it appears that teams have made it slightly more obscure. - -## Customizing the Auto-Compact Window - -One interesting thing you can do is customize the auto-compact window itself. Inside your `~/.claude/settings.json` file, you can adjust when auto-compaction fires: - -```json -{ - "autoCompactWindow": 250000 -} -``` - -If you want it to automatically compact after 250,000 tokens, you can totally do that. The setting accepts values from 100,000 to 1,000,000 tokens. - -## The Promise: Context Management Goes Away - -The promise of auto-compaction is really quite nice. Imagine a world where you didn't have to think about phase boundaries at all, didn't have to think about the [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone), didn't have to think about [context](https://www.aihero.dev/ai-coding-dictionary/context) at all. - -This decision tree would simply not be needed: - -- Continue the session -- Clear the session -- Hand it off -- Spawn a subagent -- Compact - -You would just auto-compact at the right moments. In fact, you will see a lot of people online saying that auto-compaction just handles all of their problems for them. - -## Why Auto-Compaction Is Actually Really Difficult - -However, it turns out that auto-compaction is an incredibly difficult problem to solve. And it's really, really painful to get wrong. - -### Compacting in the Middle of a Phase Is Dangerous - -Think back to a typical session with a [grilling](https://www.aihero.dev/ai-coding-dictionary/grilling) phase and an implementation phase, separated by a phase boundary. - -If someone forced you to put in a compact somewhere in this session, you would probably say that the safest place to do it would be at the phase boundary, between grilling and implementation. - -But what would happen if you compacted in the middle of a grilling session? You'd be working with only a summary of what had been done before. What I've found when this has occasionally happened is that the agent really does lose its way quite often and just forgets stuff you were talking about just before. - -The same is true in implementation, and it's often worse: - -- The agent will often lose its way completely -- The second half of the implementation phase will use a totally different coding style from the first part -- It will lose its train of thought and forget features it was supposed to implement - -### You Lose Control of the Handoff - -There's another problem: when you automatically compact, there's no opportunity for you to say what you should compact and what the intention of the next session is going to be. - -The little summarization notes that you pass to the [handoff document](https://www.aihero.dev/ai-coding-dictionary/handoff-artifact) or you pass to `/compact` are really key for getting it to compact the correct things. Auto-compaction gives you no equivalent hook. - -## The Better Approach: Human Control - -So will mid-phase compacting always be bad? Probably not, although it feels like it's going to be a hard problem no matter what the model is. It's a very tricky, difficult problem to solve. - -My attitude in general is to increase the skill of the human instead of increasing the demand on the harness and the model. I tend to prefer the human having control of this decision tree, rather than just passing it off to the agent. - -It's a one-time learning curve that the human has to go through, and it will just get you better and better results the better you get at it. More of your sessions are going to be in the smart zone and you're going to have better control. - -## The Real Rule - -In my opinion, if you're hitting the auto-compact buffer, if you're automatically compacting, then something is probably going wrong. - -Instead, you should be in control. You should be the one deciding whether you continue the session, clear the session, hand it off, spawn a subagent, or compact. - -When you own that decision, you get better code. - - - - - - diff --git a/docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md b/docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md deleted file mode 100644 index 3a3520d24..000000000 --- a/docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md +++ /dev/null @@ -1,110 +0,0 @@ - - -# Why Plan Mode Sucks - -In our previous lesson, we saw how an [agent](https://www.aihero.dev/ai-coding-dictionary/agent) behaves under normal conditions. The results were not great. What really troubled me was the pattern: the agent prompted, explored the codebase, then immediately began implementing. - -There was no verification with us about whether it was building the right thing. There was no attempt at alignment between the AI and us. - -In that run, we were actually lucky. The agent built the thing we wanted pretty well. There were some issues and a critical bug, but it worked. However, this rush to create an asset is really dangerous in AI and something I always try to slow down. - -## Plan mode: a buffer between exploration and implementation - -Most agents ship with something called [**plan mode**](https://www.aihero.dev/ai-coding-dictionary/agent-mode). The intention of plan mode is to have a planning [session](https://www.aihero.dev/ai-coding-dictionary/session) before any work is done. This planning session creates a plan document that you read, review, and then decide whether to continue (maybe with modifications). Only when you're happy with the plan do you proceed. - -Let me show you how this works in practice. - -```bash -npm run reset -``` - -This resets the codebase to the main branch, clearing out the existing course rating implementation from the previous lesson. - -Next, I'll open up the agent and enable plan mode by cycling through the [permission modes](https://www.aihero.dev/ai-coding-dictionary/permission-mode) using `shift+tab` until the input footer reads "plan mode on". - -Now I'll paste in the original prompt: - -``` -I would like to create a course review system where students can review courses by leaving a star rating. We don't want to add written reviews, just star rating. These reviews will then be visible everywhere that courses are visible. We want to show the average rating on the courses in the list page and on the course page itself. -``` - -After submitting, the agent should explore the codebase to understand the structure, then come back with a plan. This plan mode acts like a little buffer between exploration and implementation. A moment where we can align before continuing. - -## The plan it generates - -Now the agent has finished exploration and is writing the plan. This is roughly how most agents handle plan mode. The behavior is similar across different tools. - -I can view the plan by typing `/plan`: - -This gives me a quite detailed output of everything the agent is going to do, along with some key decisions: - -- **One user per rating per course** - makes sense -- **Averages are computed on read** - looks fine -- **Empty state:** courses with zero ratings show "No ratings yet" rather than zero stars - makes sense -- **Who can rate:** enrolled users only - makes sense - -## The critical issue: plan mode is still rushing - -Here's the problem: instead of rushing to create an implementation, the agent rushed to create a plan which reads exactly like the implementation would. - -It's given me the exact implementation it's going to do: - -- Database table structure -- Service names and functions -- Component names -- Route modifications -- Testing strategy - -It's still rushing to create an asset. The plan is the asset now, not the code. - -## The root cause: sycophantic trait of agents - -This feeling of premature completion, of rushing to get to the end, is a [sycophantic](https://www.aihero.dev/ai-coding-dictionary/sycophancy) trait of agents. When you tell it you want to produce something, it will go produce that thing. - -It won't necessarily stop to make sure it's done the legwork to ensure you're aligned on how it should look. - -This is really bad because it leads to a failure mode that happens constantly: the agent builds the wrong thing. - -On a relatively simple feature like course ratings, it doesn't matter too much. But on a more complicated feature, it really matters. - -## What this means in practice - -Imagine if a human developer behaved this way. They just said, "Yes, I know how to build that," and they went ahead and did it. There would be no alignment whatsoever. There would be no sense of a shared understanding being developed. - -In the book ["The Design of Design"](https://www.amazon.co.uk/Design-Essays-Computer-Scientist/dp/0201362988) by Frederick P. Brooks Jr. (the author of "The Mythical Man-Month"), there's a concept called the [**design concept**](https://www.aihero.dev/ai-coding-dictionary/design-concept). - -A design concept is not an asset. It's the concept floating around in the room when humans are designing something. Everyone has a slightly different idea of it, but as conversations develop and you work towards understanding what you're building, everything starts to sharpen. - -In both plan mode and the version we saw before, there's no design concept here. There's no moment to check in with each other to make sure we're actually aligned on what we're building. - -We got an okay result the first time we ran it, but I guarantee on more complex features, this would quickly go wrong. - -## A different approach - -The approach I've designed tries to sidestep this issue. It takes away the sycophantic asset rush. What you end up with, I hope, is a feeling of greater alignment with the agent - like you're both on the same page. - -I'm going to explain that in the next lesson. - - - - - - diff --git a/docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md b/docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md deleted file mode 100644 index bb489b526..000000000 --- a/docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md +++ /dev/null @@ -1,112 +0,0 @@ - - -# The Grill-Execute-Clear Loop - - - Start the lesson: the `/grill-me` skill added to `.agents/skills/` - See my solution: lesson comments built from the grilled spec - - -Before you start building features, you need to understand what you're building. Most developers skip this step and rush straight into coding, which leads to wasted time and solutions that don't quite fit the problem. - -The `/grill-me` [skill](https://www.aihero.dev/ai-coding-dictionary/skill) forces you to pause. It interviews you relentlessly until you reach a shared understanding of what you're trying to build. Only then do you implement. - -This is the grill-execute-clear loop. You [grill](https://www.aihero.dev/ai-coding-dictionary/grilling) until you understand. You execute the solution. You [clear](https://www.aihero.dev/ai-coding-dictionary/clearing) your mind and move to the next feature. - -## The Grilling Skill - -The grilling skill works by building a design tree. Every decision branches into the decisions that hang off it. - -It asks questions in rounds. The frontier is every decision whose prerequisites are already settled. The skill asks the whole frontier at once, then waits for your answers. - -As you answer, the frontier expands. New questions unlock. Previously blocked decisions become answerable. - -The [session](https://www.aihero.dev/ai-coding-dictionary/session) ends when the frontier is empty: every branch visited, nothing left silently assumed. Only then should you implement. - -## Your Task - -Build lesson comments for the course platform. Students and instructors should be able to comment on individual lesson pages. - -Imagine browsing to a lesson like "Connecting to a Database" or "CRUD Operations". On that page, students should be able to ask questions, share insights, and discuss the lesson content with other students and instructors. - -This is deliberately open-ended, just like the previous exercise with course star ratings. But this time, instead of rushing to implement, you're going to use `/grill-me` to explore the feature space first. - -The skill will ask you questions like: - -- Who can comment? Only enrolled students? Instructors too? -- Can users edit or delete their own comments? -- Should comments be threaded, or flat? -- Do comments need moderation? -- Should users get notifications when someone replies? - -You might not have thought about all of these. That's the point. The grilling process surfaces the decisions you need to make before you write any code. - -## Steps To Complete - -### Get the Skill - -- [ ] Run `npm run reset` to pull in the `/grill-me` skill - -This brings the repository up to the current lesson's commit, which includes the grilling skill in your `.agents/skills/` directory. - -### Invoke the Skill - -- [ ] Clear your terminal and run your [agent](https://www.aihero.dev/ai-coding-dictionary/agent) - -In your agent [harness](https://www.aihero.dev/ai-coding-dictionary/harness), you'll invoke the skill differently depending on your setup. In agent code, it's typically `/` followed by the skill name. - -- [ ] Type `/` to open the skill picker, then select `grill-me` - -This invokes the grilling skill and puts you into interview mode. - -### Start the Discussion - -- [ ] Write a loose, non-comprehensive prompt about lesson comments - -You don't need to be thorough here. The agent will ask clarifying questions. - -``` -/grill-me -I want to add comments to lessons so students can ask questions and discuss. -``` - -This kicks off a discussion. The agent will start building the design tree and asking about the decisions that hang off this feature. - -### Work Through the Grilling - -- [ ] Answer each round of questions as the agent asks them - -The agent will ask multiple questions per round. Answer them all before the next round begins. Your answers reshape the design tree and unlock new questions. - -- [ ] Keep going until the frontier is empty - -When the agent says the session is done and you've reached a shared understanding, you're ready to implement. - -This might take many rounds. That's the point. You're thinking through the problem before you code it. - -### Implement the Feature - -- [ ] Once you have a shared understanding, implement lesson comments - -Now that you know what you're building, write the code. - -- [ ] Test your implementation in the browser - -Students and instructors should be able to comment on lesson pages. The comments should persist and be visible to other users. - -### Verify Your Work - -- [ ] Run the app and navigate to a lesson page - -Pick a course you're enrolled in. Find a lesson like "Connecting to a Database" or "CRUD Operations". - -- [ ] Add a comment as a student - -Your comment should appear on the page. - -- [ ] Switch users and verify the comment is visible - -The comment you added should be visible when you switch to a different user and return to the same lesson. diff --git a/docs/topics/pocock-lane-1/SUMMARY.md b/docs/topics/pocock-lane-1/SUMMARY.md deleted file mode 100644 index 33be3a05e..000000000 --- a/docs/topics/pocock-lane-1/SUMMARY.md +++ /dev/null @@ -1,62 +0,0 @@ -# Lane 1 summary: handoff (issue #2899) - -First of six vetting lanes under the `pocock-course-lanes` contract -(`docs/topics/pocock-course-lanes/PLAN.md`). Closed 2026-08-17. Scope: the course handoff lesson -and upstream `skills/productivity/handoff/SKILL.md` (read at `068b6e0`) against our -`session-flow` save-point engine. - -## Decisions (register Q10 through Q19; rows in `docs/upstream/aihero-course.md`) - -- **Use-case boundary (Q10):** UNION. Our session-chain use (dumb-zone escape, session-ID chain, - retrospective reconstruction) becomes a named first-class use case alongside his - crossing-boundaries taxonomy (other agent, other repo, colleague, forked side task). - Deliverable is routing signals for which form to use when, filed as #2956. -- **Purpose argument (Q11/Q16):** ADOPT as optional trailing free text, - `[file|prompt] [topic] [purpose...]`. Emphasis-only tailoring; never drops sections; the - resume-prompt shape (find-handoff detection contract) is untouched; Original-goal immutability - wins over a contradicting purpose. Filed as #2955. -- **Placement and expiry (Q12/Q13):** keep `/handoffs/` (memory tier), REJECT OS - temp, accumulation by design, cleanup is user-controlled removal and never silent expiry. - Confirms the #1477 finding-4 rejection rather than reversing it (retention is load-bearing for - retro chain-walk and find-handoff recovery). -- **Worktree caveat (Q17):** a handoff written inside a worktree dies with - `git worktree remove`; acceptable only when the worktree completes as a merged PR unit; - otherwise write from the main checkout or rely on clean-stop's preserve-before-remove step. - Wording lands via #2956. -- **Promote-on-value (Q18):** default no uplift; promote the content, never the file. Durable - value moves into committed artifacts (topic contract, issue, PR body); no handoff file is ever - committed. Via #2956. -- **Do-not-duplicate rule (Q14):** ADOPT explicitly in the skill body, mirroring upstream - wording. Via #2956. -- **Model invocation (Q15):** REJECT his `disable-model-invocation: true`. Keep model-invocable - under strict trigger discipline; proactive handoff prompting and instrument-triggered forks - depend on it, and user-only skills lose skill-to-skill reach. -- **Minimalism and parity rows:** 15-line minimalism REJECTED (the engine is accumulated - incident response; prompt-only mode is our minimal tier); suggested-skills section and - redaction COVERED at parity or stronger. - -## Work items filed (changes execute outside the lane) - -- #2955: purpose argument across the save-point engine (behavior change). -- #2956: routing-signals table, do-not-duplicate rule, worktree caveat, promote-content rule - (skill-body and reference wording). -- #2957: context-guard zone capture is statusline-teed and silent in cloud/headless sessions - (surfaced while deciding Q15; verified live in this container). - -## Parked to other lanes - -- Lane 2 (#2900): the non-interactive continuation pattern the user described (worker emits the - handoff at a fork point; an orchestrator, standing in for the human, kills the worker and - seeds a fresh agent with the resume prompt). This is the continuation-router build's - territory. -- Lane 3 (#2901): zone-signal availability in cloud (see #2957) affects the compaction-doctrine - discussion. - -## Process notes - -- Grounding: fresh-context explore of the session-flow handoff engine - (verified PASS, 14/14 sampled claims confirmed) plus the prior inline explore; #1477 - finding-4 rationale fetched verbatim before deciding the expiry axis. -- This lane also created the `docs/upstream/aihero-course.md` skeleton per audit amendment A2 - (row schema and divergence-at-re-fetch trigger form fixed at creation); lane 6 (#2904) owns - the coverage index and consolidation. diff --git a/docs/topics/pocock-lane-2/SUMMARY.md b/docs/topics/pocock-lane-2/SUMMARY.md deleted file mode 100644 index 0f5b4752d..000000000 --- a/docs/topics/pocock-lane-2/SUMMARY.md +++ /dev/null @@ -1,66 +0,0 @@ -# Lane 2 summary: phase boundaries (issue #2900) - -Second of six vetting lanes under the `pocock-course-lanes` contract -(`docs/topics/pocock-course-lanes/PLAN.md`). Closed 2026-08-17. Scope: the course lesson -"Clear, Compact, Handoff, Or Subagent" against the `session-flow:workflow` continuation router -(`context/continuation.md`), plus the effort's build deliverable: the Q9 context-driven router -evolution. The lane ran across two sessions (a stale resume prompt caused one hop through the -lane-1 handoff; state was reconstructed from the ledger and the verified explore slice with no -loss). - -## Decisions (register Q20 through Q23; rows in `docs/upstream/aihero-course.md`) - -- **Subagent terminal / AFK criterion (Q20, user-delegated):** ADOPT modified. The AFK question - becomes a router edge pointing to `session-flow:orchestrate` for the spawn-brief decision; - delegation stays non-terminal so orchestrate keeps spawn ownership and - continue-in-background's explicit-intent launch gate is untouched (the router suggests, never - launches). Filed in #2971. -- **Router inputs (Q21):** via existing informants. Plan, work-item state, and session history - arrive through presence-gated pointers to orient's read patterns, reconcile's liveness answer, - the workflow checklist, and the work-item seam, exactly as the zone seam consumes - context-guard's reader contract. No duplicated reads; zone stays word-only. -- **Autonomy meaning (Q22):** both tiers. Top level: per-invocation explicit opt-in - (`continue auto` or explicit user words; never a standing config) executes the routed - mechanism. Worker level: the orchestrator relay parked from lane 1 (worker emits its handoff - at a fork point; the orchestrator retires the worker and seeds a fresh agent with the resume - prompt) is codified as the autonomous tier for delegated work. I23-clean: initiative comes - from the user's opt-in or the orchestrator, never injected context. -- **Eval and hygiene debt (Q23):** file both. Router eval coverage (zero evals, one - already-regressed ordering invariant) as #2972; the context-guard - `reference/reader-contract.md:185-207` pre-0.5.0 advisory-injection drift (verifier finding) - as #2973. - -## Fact-graded dispositions (claim ladder, no user decision owed) - -- His "compact seeds a new session" wording: REJECT as a harness claim (verdict C4, two-pool - REFUTED; same session continues over a structured summary). -- Numeric anchors 30k/80k/150k and the ~150k smart zone: recorded as folklore anchors with named - provenance, never adopted as numbers (claim-ladder bucket ii, amendment A1). -- Handoff-narrowing: REJECT, confirming the lane-1 UNION decision and the prior repo-tree - rejection. -- Boundary-only discipline, ordered first-yes-wins, clear-when-disposable, compact-last with - steering, reasoning-verbatim continue criterion, primary-to-secondary trade: COVERED at parity - or stronger. - -## Work items filed (changes execute outside the lane) - -- #2971: the Q9 router evolution (informant-seam inputs, AFK edge, suggest-by-default, - two-tier autonomy, I23 reconciliation). -- #2972: router eval coverage, to land with or before #2971. -- #2973: context-guard reader-contract advisory-injection section update to the 0.5.0 - audience split. - -## Parked to other lanes - -- Lane 6 (#2904): dictionary-term adoption surfaced here (primary/secondary source, smart zone, - AFK, phase boundary) and the SSOT "measured bands" wording correction (already on lane 6's - list per amendment A1). - -## Process notes - -- Grounding: fresh-context explore of the router and its siblings - (`.work/pocock-lane-2/`, gate exit 0, verifier PASS 23/23 with parent write-back); course - lesson cached verbatim in the same slice; harness claims cited from the durable verdict table - in the lane contract rather than re-researched. -- The verifier's new find (reader-contract drift) became #2973, demonstrating the - write-back loop paying for itself. diff --git a/docs/topics/pocock-lane-3/SUMMARY.md b/docs/topics/pocock-lane-3/SUMMARY.md deleted file mode 100644 index 64b0b0b49..000000000 --- a/docs/topics/pocock-lane-3/SUMMARY.md +++ /dev/null @@ -1,44 +0,0 @@ -# Lane 3 summary: compaction doctrine (#2901) - -Closed 2026-08-17. Vetted the merged Compaction + Auto-Compaction lessons (source committed at -`docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md`) against the -house doctrine: the handoff skill's fork-beats-compaction section, the continuation router's -compact-last-with-steering edge, and context-guard's evidence-degraded marker and zone contract. - -## Decisions (register Q24-Q29, provenance: user's standing acceptance of this session's recommendations) - -- **Q24 compact-as-default: REJECTED.** His compaction lesson's "saves re-exploration" default - framing loses to fork-beats-compaction; his own phase-boundaries lesson places compact at the - tree's bottom, converging with our last-resort-with-steering edge. No change to house doctrine. -- **Q25 steered-compact-for-QA carve-out: REJECTED, track-on-event.** Evidence degradation is - trigger-independent; his own AFK criterion routes finished-work QA to a subagent. Key fact: - `post-compact-mark.sh` already records `trigger: manual|auto|unknown`, so differentiation is - buildable the day real evidence justifies it; that recorded field is the reopen observable. -- **Q26 auto-compact stance: ADOPTED (convergent).** "Auto-compact firing means the boundary - decision was left too late; the human owns it" matches the instrumented design (operator-only - menus per check I23). Filed #2995: context-guard documents the verified config surfaces - (autoCompactWindow 100k-1M, env-var precedence, C1-C3 two-pool) and the zones-below-trigger - guidance. -- **Q27 primary/secondary-source vocabulary: ADOPT terms, REJECT the irrecoverability half.** - In Claude Code the on-disk JSONL transcript persists losslessly across compaction; only the - model-visible context turns secondary. Term adoption executes in lane 6. -- **Q28 C5/C6: recorded, not blocked.** C5 (queueing during compaction) stays UNDOCUMENTED and - untaught; C6 keeps its docs-only single-pool label; the interactive probe remains an open cure. -- **Q29 Boris sections 63-64: cited as vendored nuance.** Aligned with house stance; 300k-400k - rot reports and the 400000 env-var practice held as named anchors, never adopted numbers; - vendored content stays unedited. - -## Outputs - -- Rows: `docs/upstream/aihero-course.md` "Lane 3" section (12 rows + house-decisions paragraph). -- Work item filed: #2995 (context-guard auto-compact-window documentation). No other plugin - change decided; Q24/Q25/Q27 dispositions require none. -- Lane-6 parcels: primary/secondary-source term adoption (with the transcript refinement); - C4-refutation phrasing available for the coverage index. - -## Notes for later lanes - -- Lane 4 consumes C7-C9 verdicts (plan-mode mechanics; C9-positive single-pool label). -- The #2957 cloud zone-signal gap was weighed here: it does not change Q26's disposition (the - stance is about who owns the decision, not the instrument's availability in one environment), - but #2995's docs should acknowledge headless/cloud sessions lack the statusline tee. diff --git a/docs/topics/pocock-lane-4/SUMMARY.md b/docs/topics/pocock-lane-4/SUMMARY.md deleted file mode 100644 index 79657719b..000000000 --- a/docs/topics/pocock-lane-4/SUMMARY.md +++ /dev/null @@ -1,47 +0,0 @@ -# Lane 4 summary: plan mode / asset rush (#2902) - -Closed 2026-08-17. Vetted the "Why Plan Mode Sucks" lesson (source committed at -`docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md`) against the planning -pipeline: `planning:interview` (pre-clarity contract, auto-detect, auto-guard, `lock` -STOP-on-gap, general-domain terminal) and `planning:plan` (approval gate, Open Decisions before -the plan body, devils-advocate dispatch, decision confidence gate). Verdicts C7-C9 graded the -walkthrough claims. - -## Decisions (register Q31-Q35, provenance: user's restated acceptance, "Go with your recommendations") - -- **Q31 asset-rush critique: ADOPTED (convergent).** The critique is the design rationale the - pipeline embodies twice over: the Brief locks intent before planning, and the plan skill - itself refuses inline decision-locking (Open Decisions block, confidence gate routing judgment - calls back to interview rounds, user approval before any code). Plan mode is repositioned as a - permission gate, never the alignment mechanism. -- **Q32 lock-mode audit: LICENSED EXCEPTION.** The auto-guard bars synthesizing genuine user - decisions; `lock` is user-invoked (invocation IS the confirmation) with STOP-on-gap; the - default action leans to relentless `me`; `/planning:audit-answers` is the producer-not-critic - compensating control, exercised live in this very effort (it corrected two contract - decisions). No change filed. -- **Q33 design concept: already embodied.** The general-domain interview terminal (shared - understanding, no artifact, no handoff) is the design-concept endpoint; the term maps to our - "shared understanding" and goes to lane 6 with "asset rush" and "sycophancy" as candidates. -- **Q34 walkthrough grading: separated from the critique.** C7/C8 CONFIRMED; C9's "/plan views - the plan" demo is stale (it enters plan mode; no view command exists). A stale demo does not - dent a design argument; graded separately per the claim ladder. -- **Q35 work items: NONE.** Nothing decided requires a plugin change. - -## Outputs - -- Rows: `docs/upstream/aihero-course.md` "Lane 4" section (9 rows + house-decisions paragraph). -- Work items: none. -- Lane-6 parcels: term candidates (design concept -> shared understanding, asset rush, - sycophancy); the strongest coverage-index thesis line: "the fix for plan mode is not a better - plan; it is a contract stage upstream of the plan, plus a plan stage that refuses to lock - decisions inline." - -## Notes for lane 5 - -- Expected mostly confirmation (frontier rounds, facts-vs-decisions, empty-frontier stop are - attributed adoptions already recorded in the SSOT); check course-only additions: the - grill-execute-CLEAR loop framing (the clear leg maps to our workflow spec-first mode and the - handoff chain), and the lesson's decision-checklist examples. -- His grilling/grill-me SKILL.md texts may be wanted for exact-wording comparison; the - `/workspace/mattpocock/skills` clone may be gone (probe: `git -C /workspace/mattpocock/skills - rev-parse HEAD`, expect `068b6e0`; shallow re-clone command in the lane-4 handoff if needed). diff --git a/docs/topics/pocock-lane-5/SUMMARY.md b/docs/topics/pocock-lane-5/SUMMARY.md deleted file mode 100644 index 7d593f6e5..000000000 --- a/docs/topics/pocock-lane-5/SUMMARY.md +++ /dev/null @@ -1,32 +0,0 @@ -# Lane 5 summary: grilling-interview parity (#2903) - -Closed 2026-08-17. Vetted "The Grill-Execute-Clear Loop" lesson (source committed at -`docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md`) against -`planning:interview`, with his CURRENT `grilling`/`grill-me` texts read from the live clone at -HEAD `068b6e0` for exact-wording comparison. - -## Outcome: fully confirmatory, as the contract predicted - -- His repo texts match the SSOT-recorded derivation baseline verbatim in substance; the course - lesson restates the skill and adds only framing (the grill-execute-clear loop), posture lines - ("many rounds is the point"), and course machinery. -- Every parity element graded COVERED, several stronger on our side (mechanical register gate, - auto-guard + unattended ladder, wayfind escape route, question-budget scaling). -- **Q36:** the loop framing earns NO term adoption: the workflow stages + continuation router - already own the shape; a mapping row records the equivalence instead. -- **Q37:** no work items filed (second clean lane after lane 4). - -## Outputs - -- Rows: `docs/upstream/aihero-course.md` "Lane 5" section (9 rows + house-decisions paragraph). -- Work items: none. Lane-6 parcels: none new (design-tree = decision-tree equivalence noted). - -## Notes for lane 6 - -- All parcels now assembled across lanes 1-5: term candidates (primary/secondary source with - the transcript-lossless refinement, smart zone, AFK, phase boundary, design concept -> shared - understanding, asset rush, sycophancy); SSOT TRACK-row annotations (invocation-reach landed - unreleased; diagnosing-bugs post-mortem removal); SSOT row-35 "measured bands" correction - (A1); v12-map "Claude-only private marketplace" staleness; teach-comparison branch fold-in - check (`claude/teach-skill-comparison-h3rpag`, per #2904 comments); the coverage index against - all six lessons. diff --git a/docs/topics/pocock-lane-6/SUMMARY.md b/docs/topics/pocock-lane-6/SUMMARY.md deleted file mode 100644 index a11948ec0..000000000 --- a/docs/topics/pocock-lane-6/SUMMARY.md +++ /dev/null @@ -1,38 +0,0 @@ -# Lane 6 summary: vocabulary + provenance consolidation (#2904) - -Closed 2026-08-18. The final lane: consolidation, corrections, term verdicts, and the coverage -index that is the effort's "everything is represented" gate. - -## Executed (register Q38-Q40) - -- **Coverage index** written into the effort contract (`docs/topics/pocock-course-lanes/PLAN.md`): - per-lesson pointer index over the 49 claim rows (counts verified against the doc), plus the - outside-the-rows accounting (harness verdict table, quiz-claim handling, machinery exclusions, - known-open cures, teach-branch status). Q39: pointer shape per the do-not-duplicate rule. -- **SSOT maintenance** (`docs/upstream/mattpocock-skills.md`): row-35 "measured bands" overclaim - corrected per audit A1; invocation-reach TRACK strand annotated with the landed-unreleased - evidence (his PRs #878/#880, `.agents/invocation.md`); diagnosing-bugs row annotated with the - post-mortem-step removal. `docs/upstream/mattpocock-skills-v12-map.md`: private-marketplace - staleness correction (repo is public; inventory re-verified intact at HEAD `068b6e0`). -- **Term verdicts** recorded in `docs/upstream/aihero-course.md` Lane 6 (seven candidates: - 2 adopt, 1 partial, 1 already-house, 1 rejected-synonym, 1 shorthand-only, 1 no-action). - Q40 routed through `/domain-driven-design:curate-language`: the repo keeps NO central - glossary (vocabulary lives in owning plugins' docs), so glossary creation was DEFERRED per - the lazy-creation rule; the placement question goes to the user, not decided autonomously. -- **Teach-branch check** (Q38): local branch `claude/teach-skill-comparison-h3rpag` holds only - its interview ledger (commit `49bb9614`), no outcomes; in-flight, pointer-only; the #2904 - guard comment binds its future results to the provenance home. -- `docs/upstream/aihero-course.md` consolidation: trigger discipline and SSOT cross-links were - verified already present (lane 1's creation was to spec); the Lane 6 section replaces the - consolidation placeholder. - -## Open by design (not blockers) - -- Central-glossary creation: user placement choice pending. -- Interactive-session probes: C5 (queueing), C6 and C9-positive second pools. -- The final PR (user go-ahead required) with the contract-slice prune commit. - -## Effort totals (lanes 1-6) - -49 claim rows + 7 term verdicts; items filed: #2955 #2956 #2957 (lane 1), #2971 #2972 #2973 -(lane 2), #2995 (lane 3); lanes 4-6 filed none. Six issues closed: #2899-#2904. From fa2c65f106a3867649492f9f4137f7b802e5bad8 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 12:17:14 +0000 Subject: [PATCH 19/22] docs(upstream): address PR review - re-fetchable basis, schema-clean verdicts Codex review on #3008, both findings valid: (1) row bases cited pruned docs/topics paths; a new "Basis and re-fetch" section names the stable course source (AI Hero, aihero.dev) and the deliberate no-snapshot decision, and every lane basis now cites the lesson by title; (2) lane 4's two convergent no-change rows carried ADOPT without filed items, violating the fixed schema; reclassified to COVERED (convergent) and an ADOPT-terms sub-form note added for lane 3's vocabulary row. Also normalizes em dashes introduced by this branch. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/upstream/aihero-course.md | 52 ++++++++++++++-------- docs/upstream/mattpocock-skills-v12-map.md | 2 +- docs/upstream/mattpocock-skills.md | 8 ++-- 3 files changed, 38 insertions(+), 24 deletions(-) diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index 4c29fdbf1..f7065b52a 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -22,7 +22,9 @@ the basis it was derived against, the as-of date, and a recheck trigger. Columns | Lesson claim | Ours | Verdict | Reasoning, basis, as-of | Verdicts: **ADOPT** (with the filed work item), **REJECT** (with reason), **TRACK** (on a named -event), **COVERED** (already present at parity or stronger, with evidence). +event), **COVERED** (already present at parity or stronger, with evidence). One sub-form: +**ADOPT terms** marks a vocabulary adoption whose execution path is the lane 6 term-verdict +table rather than a filed work item. **Recheck trigger, all rows (fixed at creation):** divergence at re-fetch. A read-time re-fetch of the row's basis (the lesson text, or the upstream artifact the row cites) finds the source no @@ -31,10 +33,22 @@ the upstream-drift maintenance procedure. A row may state a stronger trigger inl the lesson updates" is not a valid trigger form here because the course publishes no observable update signal. +## Basis and re-fetch + +The lesson side of every row is one of six lessons from Matt Pocock's AI Hero course on working +with coding agents (aihero.dev; lesson titles are named per lane section), read as verbatim +pastes into the vetting sessions on 2026-08-17. No lesson snapshot is retained in this +repository, by design: durable-tier docs paraphrase and cite rather than reproduce lesson text +(amendment A2), and the contract-slice prune gate bars committed working slices. Re-fetching a +row's lesson basis therefore means re-reading the named lesson at the course itself. The +effort's working records (contract, coverage index, lane summaries) are carried in PR +[#3008](https://github.com/melodic-software/claude-code-plugins/pull/3008)'s body and the six +lane issues. + ## Lane 1: handoff (issue #2899, decided 2026-08-17) -Basis for all lane 1 rows: the course handoff lesson as captured in the lane contract -(`docs/topics/pocock-course-lanes/PLAN.md`, 2026-08-17) plus upstream +Basis for all lane 1 rows: the course lesson "Handing Off" (verbatim paste, 2026-08-17; no +snapshot retained; see Basis and re-fetch) plus upstream `skills/productivity/handoff/SKILL.md` read live at `068b6e0` (2026-08-17). Our side read live the same day: `plugins/session-flow/skills/handoff/SKILL.md`, `plugins/session-flow/reference/save-point.md`, `plugins/session-flow/reference/structure.md` @@ -97,8 +111,8 @@ context-guard reader-contract drift are filed as their own items. Filed: ## Lane 3: compaction doctrine (issue #2901, decided 2026-08-17) -Basis: the merged Compaction and Auto-Compaction lessons (source: -`docs/topics/pocock-course-lanes/lessons/03-compaction-and-auto-compaction.md`), graded against +Basis: the merged "Compaction" and "Auto-Compaction" lessons (verbatim paste, 2026-08-17; no +snapshot retained; see Basis and re-fetch), graded against the verified harness verdicts C1-C6 in the contract's table, the context-guard evidence-degraded marker and reader contract, and the handoff skill's fork-beats-compaction doctrine. Register Q24-Q29; answers locked under the user's standing acceptance of this session's recommendations @@ -132,8 +146,8 @@ stance, its figures held as named anchors never adopted numbers. ## Lane 4: plan mode / asset rush (issue #2902, decided 2026-08-17) -Basis: the "Why Plan Mode Sucks" lesson (source: -`docs/topics/pocock-course-lanes/lessons/04-why-plan-mode-sucks.md`), graded against +Basis: the "Why Plan Mode Sucks" lesson (verbatim paste, 2026-08-17; no snapshot retained; +see Basis and re-fetch), graded against `planning:interview` (pre-clarity stance, auto-detect, auto-guard, `lock` STOP-on-gap, the general-domain shared-understanding terminal) and `planning:plan` (approval gate, Open Decisions before the plan body, devils-advocate dispatch, decision confidence gate), plus verdicts C7-C9. @@ -141,9 +155,9 @@ Register Q31-Q35 under the user's restated acceptance. | Lesson claim | Ours | Verdict | Reasoning, basis, as-of | |---|---|---|---| -| Agents rush from prompt to implementation with no alignment step (the asset rush) | `planning:interview` is the pipeline's pre-clarity stage: a contract locked before exploration, planning, or execution | **ADOPT** (convergent) | The critique is the design rationale the pipeline already embodies; behavior-change work is interview-first by default, with auto-detect keeping it cheap. As-of 2026-08-17 | +| Agents rush from prompt to implementation with no alignment step (the asset rush) | `planning:interview` is the pipeline's pre-clarity stage: a contract locked before exploration, planning, or execution | **COVERED** (convergent) | The critique is the design rationale the pipeline already embodies; behavior-change work is interview-first by default, with auto-detect keeping it cheap. No change needed, so no work item (verdict reclassified from ADOPT per schema during PR review). As-of 2026-08-17 | | Plan mode is a buffer between exploration and implementation: a plan document you review, then proceed | Plan mode is treated as a permission/safety gate; alignment is owned upstream by the interview contract | **COVERED** (position) | The harness feature is not rejected, it is repositioned: a permission mode cannot produce shared understanding, and nothing in the family asks it to. As-of 2026-08-17 | -| "Plan mode is still rushing": the plan reads like the implementation; the decisions are already made and written down | Two structural answers: the Brief locks intent BEFORE `/planning:plan`, and the plan skill itself refuses to lock decisions inline (Open Decisions surfaced before the plan body; a confidence gate routes judgment calls back to interview rounds; user approval gate before any code; fresh-context devils-advocate stress-test) | **ADOPT** (convergent, already answered structurally) | His diagnosis names exactly the failure the pipeline's two gates exist to prevent; no change needed. As-of 2026-08-17 | +| "Plan mode is still rushing": the plan reads like the implementation; the decisions are already made and written down | Two structural answers: the Brief locks intent BEFORE `/planning:plan`, and the plan skill itself refuses to lock decisions inline (Open Decisions surfaced before the plan body; a confidence gate routes judgment calls back to interview rounds; user approval gate before any code; fresh-context devils-advocate stress-test) | **COVERED** (convergent, already answered structurally) | His diagnosis names exactly the failure the pipeline's two gates exist to prevent; no change needed, so no work item (verdict reclassified from ADOPT per schema during PR review). As-of 2026-08-17 | | Root cause is the sycophantic trait: told to produce, the agent produces | Interview stance: recommendations-first but facts-are-mine/decisions-are-the-user's; the auto-guard forbids resolving a genuine user choice; `/planning:audit-answers` is the producer-not-critic control | **COVERED** | The trait is countered by structure, not exhortation; "sycophancy" and "asset rush" go to lane 6 as term candidates. As-of 2026-08-17 | | The design concept (Brooks): shared understanding is not an asset; conversation sharpens it | The general-domain interview terminal drives to a shared understanding and STOPS: no Brief, no artifact, no pipeline handoff | **COVERED** (embodied) | Q33: the endpoint already exists; the term maps to our "shared understanding" (lane-6 adoption candidate); no mechanism change earned. As-of 2026-08-17 | | Walkthrough: cycle `shift+tab` until plan mode is on | Verified harness behavior | **CONFIRMED** | Verdict C7 (two-pool); no fixed press count is taught. As-of 2026-08-17 | @@ -161,10 +175,10 @@ work items filed: no plugin change was decided; lane-6 parcels are the three ter ## Lane 5: grilling-interview parity (issue #2903, decided 2026-08-17) -Basis: "The Grill-Execute-Clear Loop" lesson (source: -`docs/topics/pocock-course-lanes/lessons/05-grill-execute-clear.md`), graded against +Basis: "The Grill-Execute-Clear Loop" lesson (verbatim paste, 2026-08-17; no snapshot +retained; see Basis and re-fetch), graded against `planning:interview` and against his CURRENT repo texts read from a live clone at HEAD -`068b6e0` (`skills/productivity/grilling/SKILL.md`, `grill-me/SKILL.md`) — which match the +`068b6e0` (`skills/productivity/grilling/SKILL.md`, `grill-me/SKILL.md`), which match the SSOT-recorded baseline verbatim in substance, confirming the 2026-08-17 recheck's cosmetic-only-drift finding. Register Q36-Q37 under the user's restated acceptance. The grilling-family provenance itself is settled in `mattpocock-skills.md` rows 3-4 and is @@ -188,17 +202,17 @@ close clean); no new lane-6 parcels beyond the design-tree/decision-tree equival ## Lane 6: vocabulary + consolidation (issue #2904, decided 2026-08-18) -Consolidation record: the per-lesson coverage index lives in the effort contract -(`docs/topics/pocock-course-lanes/PLAN.md`, "Coverage index" — pruned with the topic slice at -PR time, its substance carried in the PR body; the claim-level enumeration is this document's -lane sections, 49 rows). SSOT maintenance executed by this lane: the row-35 wording correction +Consolidation record: the per-lesson coverage index is carried in the body of PR +[#3008](https://github.com/melodic-software/claude-code-plugins/pull/3008) (the effort's +contract and topic slices were pruned per the contract-slice prune gate; the claim-level +enumeration is this document's lane sections, 49 rows). SSOT maintenance executed by this lane: the row-35 wording correction (audit A1), the invocation-reach and diagnosing-bugs TRACK annotations (2026-08-17 recheck, unreleased drift), and the v12-map private-marketplace staleness correction. The parallel teach-skill comparison is in-flight (local branch, ledger only); its future outcomes are bound to this provenance home by the guard comment on #2904. **Dictionary-term verdicts** (candidates harvested across lanes; the repo keeps NO central -glossary — vocabulary lives in each owning plugin's docs, so these are adoption verdicts, not +glossary; vocabulary lives in each owning plugin's docs, so these are adoption verdicts, not glossary entries; central-glossary creation deliberately deferred per the curate-language lazy-creation rule, pending the user's placement choice): @@ -207,7 +221,7 @@ lazy-creation rule, pending the user's placement choice): | primary source / secondary source | **ADOPT** as working discussion vocabulary, WITH the house refinement: in Claude Code the on-disk JSONL transcript stays lossless across compaction; only the model-visible context turns secondary | Lane 3 rows; handoff structure doc's transcript re-scan rule | | smart zone | **PARTIAL**: survives as informal shorthand; the canonical house terms are context-guard's zone words (smart / acceptable / dumb) with declared judgment-default bands; his ~150k number rejected | context-guard reader contract | | AFK | **ADOPT** (narrow) as the name of the router's adopted AFK edge | lane 2 rows; build item #2971 | -| phase boundary | **ALREADY HOUSE** — the continuation router's trigger vocabulary predates the course | session-flow workflow/continuation docs | +| phase boundary | **ALREADY HOUSE**; the continuation router's trigger vocabulary predates the course | session-flow workflow/continuation docs | | design concept | **REJECTED SYNONYM** of "shared understanding" (the general-domain interview terminal); carry an Avoid line if a glossary is ever created | lane 4 rows; planning:interview | | asset rush | **ADOPT** as effort/discussion shorthand for the named failure mode; doubtful admission to any future glossary (methodology vocabulary) | lane 4 rows | -| sycophancy | **NO ACTION** — generic ML vocabulary already in standard use | lane 4 rows | +| sycophancy | **NO ACTION**; generic ML vocabulary already in standard use | lane 4 rows | diff --git a/docs/upstream/mattpocock-skills-v12-map.md b/docs/upstream/mattpocock-skills-v12-map.md index 4183d16c6..4f3c168ca 100644 --- a/docs/upstream/mattpocock-skills-v12-map.md +++ b/docs/upstream/mattpocock-skills-v12-map.md @@ -1,7 +1,7 @@ # Full map — mattpocock/skills (v1.2.3, HEAD 84fdeff, 2026-08-06) ↔ melodic-software/claude-code-plugins (main a89a4a33) > **Correction (2026-08-17):** this map's "Claude-only private marketplace" characterization -> (Codex-sidecar row and the marketplace row of the cross-cutting table) is stale — the +> (Codex-sidecar row and the marketplace row of the cross-cutting table) is stale; the > repository is PUBLIC (verified via the repo listing during the pocock-course-lanes effort). > The Claude-only part stands; the private part does not. The map is otherwise a point-in-time > record as of its header date. A 2026-08-17 recheck at HEAD `068b6e0` found the 35-skill diff --git a/docs/upstream/mattpocock-skills.md b/docs/upstream/mattpocock-skills.md index b6a00c426..4512f644c 100644 --- a/docs/upstream/mattpocock-skills.md +++ b/docs/upstream/mattpocock-skills.md @@ -32,11 +32,11 @@ divergence-at-re-fetch recheck regime. | `triage` + its `.out-of-scope/` KB (`OUT-OF-SCOPE.md`) | `work-items:triage` | Derived (structured port) | "A PR is an item with attached code" ≈ upstream's "a PR is an issue with attached code"; state-machine framing convergent. Corrected in lane 5 — this row previously claimed "no structured port", which is provably false: the rejected-concept ledger (work-items 0.6.0; triage's ledger check + won't-fix/already-implemented outcomes) is a structured port of upstream's `.out-of-scope/` KB — one-file-per-concept, concept-similarity-not-keyword matching, never-ledger-built-features, and the near-verbatim "so the same request doesn't return as fresh code" (upstream `OUT-OF-SCOPE.md:86`) map one-to-one; ours is a superset. The v1.2 `.out-of-scope/` adoption candidate (M15) is therefore REJECTED as already-adopted; provenance row corrected only — no `work-items` behavior change (the topic plan's out-of-scope bars it) | | `to-tickets` | `work-items:decompose` | Influence (vocabulary) | Vertical-slice / tracer-bullet decomposition vocabulary overlaps upstream; mechanics are house-built on the work-item seam | | `improve-codebase-architecture` YAGNI scoping filter (v1.2 #533) | `architecture:improve` deepening Phase 1 | Partial | ADOPTED scope-before-scanning: user-named direction scopes the scan, else recent-commit hot spots pull attention first (precomputed context widened to 20 commits). REJECTED his `CONTEXT.md` reference (our glossary-discovery ladder) and HTML-report machinery (previously rejected) | -| `diagnosing-bugs` (v1.2.3 Redact + tagged logs) | `debugging:debug`, `testing:diagnose` | Partial | ADOPTED the redaction guard in both skills (secrets `` before any shown command/output/artifact; env-var credentials; signal-lines-only quoting) and the `[DEBUG-a4f2]` tagged-log convention in `testing:diagnose` (already present in `debugging:debug`). TRACKED, not adopted: feedback-loop-first doctrine (10 ranked loop types, 3–5 ranked hypotheses) — our phase structures work; re-evaluate on a release whose changeset names `diagnosing-bugs`. Annotation (2026-08-17 recheck, unreleased): upstream dropped its Phase 6 post-mortem step ("Cleanup + post-mortem" reduced to "Cleanup"; the what-would-have-prevented-this handoff to improve-codebase-architecture removed) — weigh alongside this row when the release trigger fires | +| `diagnosing-bugs` (v1.2.3 Redact + tagged logs) | `debugging:debug`, `testing:diagnose` | Partial | ADOPTED the redaction guard in both skills (secrets `` before any shown command/output/artifact; env-var credentials; signal-lines-only quoting) and the `[DEBUG-a4f2]` tagged-log convention in `testing:diagnose` (already present in `debugging:debug`). TRACKED, not adopted: feedback-loop-first doctrine (10 ranked loop types, 3–5 ranked hypotheses) — our phase structures work; re-evaluate on a release whose changeset names `diagnosing-bugs`. Annotation (2026-08-17 recheck, unreleased): upstream dropped its Phase 6 post-mortem step ("Cleanup + post-mortem" reduced to "Cleanup"; the what-would-have-prevented-this handoff to improve-codebase-architecture removed); weigh alongside this row when the release trigger fires | | `wait-what` (Productivity, NEW in v1.2 #751) | `discipline:wait-what` | Derived | Ported near-verbatim (one-sentence re-pitch body: back up, add missing context, ASD-STE100 register + inline gloss, ubiquitous language) as a declared non-corrector species in `discipline` beside `tighten-your-output`/`mind-your-maxims` — home chosen on the blame axis (the drift is the model's output, not the user's comprehension). Name KEPT with an explicit PLUGIN-PHILOSOPHY naming-exception entry (utterance-is-mechanism + upstream muscle-memory parity; a 5-generator/3-judge naming tournament's grammar-clean winner `re-pitch` was declined by the user). REJECTED his fixed `CONTEXT.md` filename (our format-externalized glossary discovery: nearest glossary per consumer convention, silent degradation). Shape evidence: his X thread (status 2084753070437609606 → 2084941367659168064 → 2085681281795232026) — the same instruction failed as passive global CLAUDE.md AND as an output style; only the on-demand skill works, so the register text lives in the body, invoked at the moment of loss | | `wizard` (Engineering; graduated from in-progress in v1.2) | `wizard:generate` | Derived | PORTED (lane 4) as a new single-capability plugin `wizard` 0.1.0, hardened. Kept: the 4-step scope/map/author/verify process, the fixed never-hand-edited library above the `STAGES` marker, model-invoked posture with the explicit non-trigger fence, gh-absence graceful degradation, ephemeral-by-default doctrine, agent-authors-never-runs doctrine. Hardened beyond upstream (deltas enumerated in `plugins/wizard/CHANGELOG.md` 0.1.0): mandatory human read-and-approve of the full STAGES block before `chmod +x`; https-only `open_url` (also closes a Windows UNC/NTLM leak via explorer.exe); `/dev/tty` fail-closed prompts (retires a verified multi-line-paste confirm bypass and `pause`'s fail-open at EOF); quoted `0600` `.env` writes + gitignore assert + trap-cleaned atomic temp; repo-resolved/confirmed `--repo`-explicit gh writes with stderr surfaced and empty values refused; key-name validation; readline on non-secret asks (fixes upstream #741 where safe); names-only live-`.env` scoping with the secrets-and-context property stated honestly. REJECTED: Codex `agents/openai.yaml` sidecar (no Codex target — standing precedent) | | `prototype` `LOGIC.md` shareable-HTML demo (Engineering, v1.2) | `prototype:pressure-test` | Partial | ADOPTED (lane 5) the audience-routed HTML demo shell: TUI stays default; when the driver is a non-developer (designer, PM, domain expert) or no terminal fits, the disposable shell over the same portable pure logic module is one self-contained `file://` page — domain-language labels, labelled state panel re-rendered per click, free-play buttons, guided-walkthrough scenarios resetting to a known initial state — under explore-directions' existing HTML-substrate constraint set reused verbatim-in-spirit (restrictive CSP meta tag, ephemeral `mktemp -d` / `%LOCALAPPDATA%\Temp` placement, synthetic data only, discard after the markdown capture). prototype 0.5.0. REJECTED the other half of upstream's step 5: the throwaway-branch "primary source" capture that keeps the prototype re-runnable on a branch — a two-lane branch-naming posture violation that also contradicts the plugin's delete-when-done discipline (`plugins/prototype/context/discipline.md`, "Delete or absorb when done") | -| ask-matt `PHASE-BOUNDARIES.md` (v1.2) | `session-flow:workflow` continuation router + `context-guard` zones | Convergent / rejected | Tree audited element-by-element at parity or stronger (ordered first-yes-wins router, compact-last-with-steering, boundary-only trigger; ours adds clean-stop, user-gated background, instrumented zones, worker relay). ADOPTED one zone-gated criterion: prefer continue when the next stage consumes this stage's reasoning verbatim. REJECTED "handoff only for what travels" narrowing (contradicts our fork-beats-compaction stance) and the ~150k smart-zone figure (self-declared-debated folklore; no official numeric threshold exists — our zone instrumentation stands, his dictionary entry noted as one more folklore anchor; wording corrected 2026-08-17 per pocock-course-lanes audit A1: context-guard's shipped bands are declared judgment defaults with named provenance, not measurements — this row previously overclaimed them as "measured") | +| ask-matt `PHASE-BOUNDARIES.md` (v1.2) | `session-flow:workflow` continuation router + `context-guard` zones | Convergent / rejected | Tree audited element-by-element at parity or stronger (ordered first-yes-wins router, compact-last-with-steering, boundary-only trigger; ours adds clean-stop, user-gated background, instrumented zones, worker relay). ADOPTED one zone-gated criterion: prefer continue when the next stage consumes this stage's reasoning verbatim. REJECTED "handoff only for what travels" narrowing (contradicts our fork-beats-compaction stance) and the ~150k smart-zone figure (self-declared-debated folklore; no official numeric threshold exists — our zone instrumentation stands, his dictionary entry noted as one more folklore anchor; wording corrected 2026-08-17 per pocock-course-lanes audit A1: context-guard's shipped bands are declared judgment defaults with named provenance, not measurements; this row previously overclaimed them as "measured") | ## Not adopted (decided, with reasons) @@ -90,8 +90,8 @@ Two `writing-for-agents` strands from v1.2 (lane 5) — tracked on events, never landed on main and hardened (his PRs #878/#880 + `.agents/invocation.md`): cross-skill dependencies standardized as an explicit `Call the Skill tool with "name"` instruction (one skill per call; his stated reason: higher hit rate than bare `/name` prose, harness-neutral), - and user-invoked skills declared unreachable from any skill — preconditions on them must be - phrased "tell the user to run /x". Changesets exist, so the next release fires this trigger; + and user-invoked skills declared unreachable from any skill (preconditions on them must be + phrased "tell the user to run /x"). Changesets exist, so the next release fires this trigger; the portable authoring question for OUR cross-skill invocation phrasing is recorded in `aihero-course.md`'s effort record (pocock-course-lanes). From 8c2523258c14e59768688817be5c308db0adc3d7 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 12:22:29 +0000 Subject: [PATCH 20/22] docs(upstream): re-apply schema-conformance review fix on consolidated record Carries Codex finding 2 from PR #3008 onto the authoritative mainline copy taken in the merge: lane 4's two convergent no-change rows reclassified ADOPT to COVERED (the fixed schema ties ADOPT to a filed work item), and the ADOPT-terms sub-form named in the schema section. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/upstream/aihero-course.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index fa9fa2c4e..f167b39ac 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -45,7 +45,9 @@ the basis it was derived against, the as-of date, and a recheck trigger. Columns | Lesson claim | Ours | Verdict | Reasoning, basis, as-of | Verdicts: **ADOPT** (with the filed work item), **REJECT** (with reason), **TRACK** (on a named -event), **COVERED** (already present at parity or stronger, with evidence). +event), **COVERED** (already present at parity or stronger, with evidence). One sub-form: +**ADOPT terms** marks a vocabulary adoption whose execution path is the term-verdict table +(lane 6) rather than a filed work item. **Recheck trigger, all rows (fixed at creation):** divergence at re-fetch. A read-time re-fetch of the row's basis (the lesson text, or the upstream artifact the row cites) finds the source no @@ -189,9 +191,9 @@ regression-gating the lock/auto-guard defenses — which stands. | Lesson claim | Ours | Verdict | Reasoning, basis, as-of | |---|---|---|---| -| Agents rush from prompt to implementation with no alignment step (the asset rush) | `planning:interview` is the pipeline's pre-clarity stage: a contract locked before exploration, planning, or execution | **ADOPT** (convergent) | The critique is the design rationale the pipeline already embodies; behavior-change work is interview-first by default, with auto-detect keeping it cheap. As-of 2026-08-17 | +| Agents rush from prompt to implementation with no alignment step (the asset rush) | `planning:interview` is the pipeline's pre-clarity stage: a contract locked before exploration, planning, or execution | **COVERED** (convergent) | The critique is the design rationale the pipeline already embodies; behavior-change work is interview-first by default, with auto-detect keeping it cheap. No change needed, so no work item (reclassified from ADOPT per schema, PR #3008 review). As-of 2026-08-17 | | Plan mode is a buffer between exploration and implementation: a plan document you review, then proceed | Plan mode is treated as a permission/safety gate; alignment is owned upstream by the interview contract | **COVERED** (position) | The harness feature is not rejected, it is repositioned: a permission mode cannot produce shared understanding, and nothing in the family asks it to. As-of 2026-08-17 | -| "Plan mode is still rushing": the plan reads like the implementation; the decisions are already made and written down | Two structural answers: the Brief locks intent BEFORE `/planning:plan`, and the plan skill itself refuses to lock decisions inline (Open Decisions surfaced before the plan body; a confidence gate routes judgment calls back to interview rounds; user approval gate before any code; fresh-context devils-advocate stress-test) | **ADOPT** (convergent, already answered structurally) | His diagnosis names exactly the failure the pipeline's two gates exist to prevent; no change needed. As-of 2026-08-17 | +| "Plan mode is still rushing": the plan reads like the implementation; the decisions are already made and written down | Two structural answers: the Brief locks intent BEFORE `/planning:plan`, and the plan skill itself refuses to lock decisions inline (Open Decisions surfaced before the plan body; a confidence gate routes judgment calls back to interview rounds; user approval gate before any code; fresh-context devils-advocate stress-test) | **COVERED** (convergent, already answered structurally) | His diagnosis names exactly the failure the pipeline's two gates exist to prevent; no change needed, so no work item (reclassified from ADOPT per schema, PR #3008 review). As-of 2026-08-17 | | Root cause is the sycophantic trait: told to produce, the agent produces | Interview stance: recommendations-first but facts-are-mine/decisions-are-the-user's; the auto-guard forbids resolving a genuine user choice; `/planning:audit-answers` is the producer-not-critic control | **COVERED** | The trait is countered by structure, not exhortation; "sycophancy" and "asset rush" go to lane 6 as term candidates. As-of 2026-08-17 | | The design concept (Brooks): shared understanding is not an asset; conversation sharpens it | The general-domain interview terminal drives to a shared understanding and STOPS: no Brief, no artifact, no pipeline handoff | **COVERED** (embodied) | Q33: the endpoint already exists; the term maps to our "shared understanding" (lane-6 adoption candidate); no mechanism change earned. As-of 2026-08-17 | | Walkthrough: cycle `shift+tab` until plan mode is on | Verified harness behavior | **CONFIRMED** | Verdict C7 (two-pool); no fixed press count is taught. As-of 2026-08-17 | From b91b769d93c8bd399076be549999f6dfdff2390f Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 12:26:52 +0000 Subject: [PATCH 21/22] docs(upstream): reconcile v12-map correction date (review finding) The correction blockquote is a 2026-08-18 lane-6 event, matching the inline row notes; 2026-08-17 was the repo-public verification and the separate inventory recheck, now each dated explicitly. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/upstream/mattpocock-skills-v12-map.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/upstream/mattpocock-skills-v12-map.md b/docs/upstream/mattpocock-skills-v12-map.md index 5887dd135..4173c218d 100644 --- a/docs/upstream/mattpocock-skills-v12-map.md +++ b/docs/upstream/mattpocock-skills-v12-map.md @@ -1,12 +1,13 @@ # Full map — mattpocock/skills (v1.2.3, HEAD 84fdeff, 2026-08-06) ↔ melodic-software/claude-code-plugins (main a89a4a33) -> **Correction (2026-08-17):** this map's "Claude-only private marketplace" characterization -> (Codex-sidecar row and the marketplace row of the cross-cutting table) is stale; the -> repository is PUBLIC (verified via the repo listing during the pocock-course-lanes effort). -> The Claude-only part stands; the private part does not. The map is otherwise a point-in-time -> record as of its header date. A 2026-08-17 recheck at HEAD `068b6e0` found the 35-skill -> inventory and all relation rows structurally intact (record: `aihero-course.md` effort + -> the pocock-course-lanes contract). +> **Correction (2026-08-18, lane 6):** this map's "Claude-only private marketplace" +> characterization (Codex-sidecar row and the marketplace row of the cross-cutting table) was +> stale; the repository is PUBLIC (verified via the repo listing on 2026-08-17 during the +> pocock-course-lanes effort; the row-level notes below carry the same 2026-08-18 correction +> date). The Claude-only part stands; the private part does not. The map is otherwise a +> point-in-time record as of its header date. A separate 2026-08-17 recheck at HEAD `068b6e0` +> found the 35-skill inventory and all relation rows structurally intact (record: +> `aihero-course.md` effort + the pocock-course-lanes contract). Sources: his-repo full inventory (35 skills, every SKILL.md read), our-repo provenance sweep (git log + grep + docs), v1.2.0 release notes, v1.2 changelog article, video transcript. As-of 2026-08-08. From 84bea05a3f42d430350214da34756a54f38d0859 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 12:31:08 +0000 Subject: [PATCH 22/22] docs(upstream): scope the ADOPT invariant to plain ADOPT rows Review finding on #3008: the intro's unconditional "every ADOPT row points at a filed work item" contradicted the ADOPT-terms sub-form added below it; the intro now scopes the invariant and points at the sub-form's execution path. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01LiiQ2eJ6mHqTPsNfTGJzCG --- docs/upstream/aihero-course.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/upstream/aihero-course.md b/docs/upstream/aihero-course.md index f167b39ac..ad34080bc 100644 --- a/docs/upstream/aihero-course.md +++ b/docs/upstream/aihero-course.md @@ -17,8 +17,9 @@ Vetting ran as six lanes on the `pocock-course-lanes` contract steering lanes ([#2909](https://github.com/melodic-software/claude-code-plugins/issues/2909), [#2910](https://github.com/melodic-software/claude-code-plugins/issues/2910), [#2911](https://github.com/melodic-software/claude-code-plugins/issues/2911)). Lanes decide but -never implement: every ADOPT row points at a filed work item; changes execute through the normal -pipeline. +never implement: every plain ADOPT row points at a filed work item (the ADOPT terms sub-form, +defined with the row schema below, executes via the lane 6 term-verdict table instead); changes +execute through the normal pipeline. **Record provenance and supersession.** Lanes 3–5 were each closed by two parallel session chains — one writing rows into this document's copy on the contract branch