From 38dc4582d717059c630a8bd27e220d7ddaa71a40 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:31:29 -0500 Subject: [PATCH 1/2] docs(upstream): record the feedback-loops workshop and correct two stale claims Add docs/upstream/aihero-feedback-loops.md, the record for the Cohort 005 Feedback Loops workshop: per idea, what it does, the problem behind it, our disposition and the merged pull request that carries it. Rewrite the diagnosing-bugs row in mattpocock-skills.md: the minimize step, the Phase 1 exit check and the clean-copy diff it called open gaps had all landed (#7009, #8828), and #16617 added the glossary read, the diagnose action and the Phase 1 surface pass. Re-checked at upstream HEAD 5863806; nothing under the skill changed since the pin. Drop the unsourced clause in the explainer-video README that GitHub's video player shows no soft captions; GitHub's Attaching files page says nothing about caption tracks. Co-Authored-By: Claude Opus 5.5 --- docs/upstream/aihero-feedback-loops.md | 154 +++++++++++++++++++++++++ docs/upstream/mattpocock-skills.md | 2 +- plugins/explainer-video/README.md | 2 +- 3 files changed, 156 insertions(+), 2 deletions(-) create mode 100644 docs/upstream/aihero-feedback-loops.md diff --git a/docs/upstream/aihero-feedback-loops.md b/docs/upstream/aihero-feedback-loops.md new file mode 100644 index 00000000000..1890ad184f3 --- /dev/null +++ b/docs/upstream/aihero-feedback-loops.md @@ -0,0 +1,154 @@ +# Upstream source: AI Hero Cohort 005, Workshop 6 "Feedback Loops" (Matt Pocock) + +This page records what this repository takes from, adapts, already has, or rejects in the +**Feedback Loops** workshop of Matt Pocock's AI Hero cohort (Cohort 005): nine lessons on giving an +agent ways to find out it is wrong. The workshop splits that feedback in two: deterministic checks +that fail on bad code, and data sources that tell the agent what its environment is doing. It +prunes a written standards file into checks, places and speeds up those checks, writes a custom +lint rule, grades tests with mutation testing, and gives a diagnosis skill and a browser the data +it needs. Our counterparts are [`/corrections:codify`](../../plugins/corrections/skills/codify/SKILL.md), +[`/debugging:debug`](../../plugins/debugging/skills/debug/SKILL.md), +[`/mutation-testing:audit`](../../plugins/mutation-testing/skills/audit/SKILL.md), +[`/testing:test-value`](../../plugins/testing/skills/test-value/SKILL.md), +[`/implementation:implement`](../../plugins/implementation/skills/implement/SKILL.md), +[`/app-control:drive`](../../plugins/app-control/skills/drive/SKILL.md) and the check-placement +rules in [ADR 0072](../adr/0072-place-each-check-by-coverage-cost-and-model-facing-output.md). +Rows hold our decisions and our own descriptions of each idea, under the upstream-drift +convention's [What a row may describe](../contracts/upstream-drift/README.md#what-a-row-may-describe). +The course is paid and account-gated, so no lesson text is recorded or linked here; the skills it +teaches are public and versioned in [mattpocock/skills](https://github.com/mattpocock/skills), +whose record is [mattpocock-skills.md](mattpocock-skills.md). Earlier course units have their own +records: [aihero-course.md](aihero-course.md), [aihero-shipping-course.md](aihero-shipping-course.md), +[aihero-domain-language.md](aihero-domain-language.md), [aihero-wayfinder.md](aihero-wayfinder.md), +[aihero-review.md](aihero-review.md) and [aihero-codebase-design.md](aihero-codebase-design.md). + +- **Pointer**: when a row needs the upstream mechanism, fetch the public skill it rests on live: + [`diagnosing-bugs`](https://github.com/mattpocock/skills/tree/4ae2317ddb22b046e26455e4f9c9b3aaaf62212d/skills/engineering/diagnosing-bugs). +- **As of**: 2026-11-16 +- **Recheck trigger**: a mattpocock/skills changeset naming that unit, checked as + [mattpocock-skills.md](mattpocock-skills.md) describes. Course page updates are not observable + events; the skills-repo changeset stream is the proxy, as in + [aihero-shipping-course.md](aihero-shipping-course.md). + +**Landed** names the merged pull request that carries the row. + +## Attribution table + +Disposition is `take`, `adapt`, `already have`, `reject` or `no change`, with the reason. The +upstream-problem cells are **Inference** throughout: the lesson pages that state them are paid and +not linked. + +### Making bad code nearly impossible + +| Idea | What it does | Upstream problem | Our problem | Disposition | Landed | +|---|---|---|---|---|---| +| Two kinds of feedback: checks that fail, data sources that inform | Splits the agent's feedback loop into deterministic checks and runtime information | Inference: an agent that sees only files and tests cannot confirm its own work | Our enforcement ladder covered checks; no skill named data sources | **adapt**: checks stay with codify's [enforcement ladder](../../plugins/corrections/skills/codify/reference/enforcement-ladder.md); the data-source half lands in the debugging and control-skill rows under "Data sources" below | see those rows | +| Checks sit under agent and human review | Places checks as the first layer of review | Inference: a person should not catch what a machine can | Same | **already have**: the three layers in [aihero-review.md](aihero-review.md) | none | + +### Pruning a coding-standards file + +| Idea | What it does | Upstream problem | Our problem | Disposition | Landed | +|---|---|---|---|---|---| +| Each written rule is deleted, kept for judgment, or turned into a check | Moves mechanical rules out of prose | Inference: a reviewer agent may miss a written rule that a check never misses | Our instruction auditors could keep, as prose, a rule a check already enforces | **adapt**: `/harness-config:audit-instructions` flags instruction prose that a deterministic check already enforces | [#16615](https://github.com/melodic-software/claude-code-plugins/pull/16615) | +| Run the pruning pass over one standards file | Sorts a file's rules one by one | Inference: a standards file collects rules no one revisits | The pass needs an owner, and a retrospective reads sessions, not files | **adapt**: a `rules ...` action on `/corrections:codify` takes any instruction file (agent instructions, rules, review criteria), since choosing a rung per rule is codify's job | [#16633](https://github.com/melodic-software/claude-code-plugins/pull/16633) | +| Confirm the pruning dropped nothing | Checks the result against the input by hand | Inference: a rewrite can lose a rule silently | Same | **take**: the `rules` action keeps a ledger with one row per input rule, and its reconciler fails when a rule is missing | [#16633](https://github.com/melodic-software/claude-code-plugins/pull/16633) | +| Count today's violations for each proposed check | Shows what turning a check on costs | Inference: a check that fails everywhere at once is ignored | Same | **already have**: a codify proposal states the existing violations and offers a cleanup or a ratchet ([aihero-review.md](aihero-review.md), "Learning from review") | none | +| Many checks from one audit | Proposes a batch of checks from one file | Inference: a standards file is a backlog of checks | Our rule was one check per observed failure, never in bulk | **adapt**: a file of rules is a record of past corrections, so a batch from one file is allowed; each rule still gets its own check and its own fail-old, pass-new proof | [#16633](https://github.com/melodic-software/claude-code-plugins/pull/16633) | +| A skill used for its reference material, not its steps | Borrows a skill's checklist without running its procedure | Inference: useful guidance sits behind a procedure that does not fit | Reference files that assume the skill's steps cannot be reused | **take**: a skill's reference files must be usable without its steps; recorded in `/playbooks:skill-authoring` | [#16612](https://github.com/melodic-software/claude-code-plugins/pull/16612) | +| Hand session output to a later session through a secret gist | Stores a hand-off outside the repository | Inference: a session's findings need a home the next session can read | A gist is tied to one user account, and GitHub documents that anyone with a secret gist's URL can see it ([Creating gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists)) | **reject**: hand-offs stay in the gitignored `.work/` folder or the tracker | none | + +### First automated checks + +| Idea | What it does | Upstream problem | Our problem | Disposition | Landed | +|---|---|---|---|---|---| +| Run checks at commit time, not on every agent edit | Keeps per-edit hooks out of the loop | Inference: a check per edit is slow and noisy and fires on half-written files | Same | **already have**: ADR 0072 places each check by cost and keeps report-only findings away from the model per edit; an audit of every shipped hook against it found none to move | none | +| A pre-commit hook on staged files only | Checks only what the commit holds | Inference: old violations should not block an unrelated commit | We could not see what each git hook stage runs, or how long it takes | **adapt**: the shared git-hooks installer gains a read-only `inspect` that lists every hook per stage, from plugins and elsewhere, with its measured duration | [#16627](https://github.com/melodic-software/claude-code-plugins/pull/16627) | +| A time budget for the commit hook | Keeps the hook fast enough not to annoy | Inference: a slow hook gets skipped | ADR 0072 named a commit budget but had not measured one | **adapt**: the pre-commit budget is measured and set, and a per-check timing table is published; no figure is borrowed from the course | [#16645](https://github.com/melodic-software/claude-code-plugins/pull/16645) | +| The check's failure text tells the agent what to do | Puts guidance in the error, not up front | Inference: guidance read at failure time is read when it matters | Same | **already have**: a codify proposal requires the check's message to name the fix | [#16603](https://github.com/melodic-software/claude-code-plugins/pull/16603) | +| A file-size cap counted in estimated tokens | Fails a file that grows past a size | Inference: agents build files too large to navigate | No study found ties file size to agent outcomes, and a byte-based token estimate is not a token count | **no change**: no size check now, so no token calibration either | none | +| Keep the prose rule beside the new check | Leaves the rule in the standards file too | Inference: the agent should know the rule before tripping it | A rule a check enforces, also written in prose, drifts from the check | **reject**: prose is for what no check can enforce | none | +| Skip the hook once for a mass reformat | Bypasses the hook with the owner's consent | Inference: a first reformat touches every file | Every git hook can be bypassed, so CI is the hard stop | **already have**: `guardrails` blocks hook-skipping flags and hook-manager skips on commit and push | none | + +### Speeding up checks + +| Idea | What it does | Upstream problem | Our problem | Disposition | Landed | +|---|---|---|---|---|---| +| Check speed matters more than people expect | Treats slow checks as slow agent feedback | Inference: every wait on a check is a wait for the agent | We had no ranking of which checks cost the most per lane | **adapt**: `performance` ranks slow checks per lane and `toolchain:ratchet` holds their growth; one shell-lint check was made faster on the same evidence | [#16648](https://github.com/melodic-software/claude-code-plugins/pull/16648), [#16659](https://github.com/melodic-software/claude-code-plugins/pull/16659) | +| Swap slow tools for faster native ones | Replaces a formatter and a type checker with faster builds | Inference: the tool, not the check, is slow | Naming a tool in a shipped skill ties every consumer to it | **no change**: skills ship no per-stack tool advice; stack specifics are researched at run time against the consumer's own setup, a rule recorded in the plugin philosophy and held by a ratchet on stack-specific code fences | [#16634](https://github.com/melodic-software/claude-code-plugins/pull/16634), [#16649](https://github.com/melodic-software/claude-code-plugins/pull/16649) | +| A green check that inspected nothing | Reads what a check did, not its color | Inference: a check over zero inputs passes and means nothing | Three of our passes exited 0 with nothing to inspect | **adapt**: those three passes now fail when they check nothing | [#16645](https://github.com/melodic-software/claude-code-plugins/pull/16645) | +| Run hook jobs in parallel | Runs several checks at once and reports each failure | Inference: serial checks waste the budget | Same | **already have**: the affected-checks runner takes a job count | none | +| Tests out of git hooks and into CI; no pre-push hook | Keeps local hooks to fast checks | Inference: a growing suite slows every push | ADR 0072 allows pre-push work within its own budget, and every hook can be skipped | **adapt**: we keep a pre-push stage and add change-scoped tests and architecture tests to it within ADR 0072's pre-push budget; CI stays the hard stop | [#16645](https://github.com/melodic-software/claude-code-plugins/pull/16645) | + +### A custom lint rule + +| Idea | What it does | Upstream problem | Our problem | Disposition | Landed | +|---|---|---|---|---|---| +| A narrow rule beats banning an API | Forbids the unsafe use of a call, not the call | Inference: a ban blocks legitimate uses | Same | **already have**: codify's pattern-rule and custom-analyzer rungs | none | +| An agent writes the rule | Has the agent author the lint rule | Inference: rules are cheap to write now | An untested rule may match too little; nothing says what it misses | **adapt**: a rule codify proposes ships with valid and invalid rule tests and states what it does not catch | [#16633](https://github.com/melodic-software/claude-code-plugins/pull/16633) | +| Rules a team can live with | Surveys legitimate uses before scoping a rule | Inference: an over-strict rule gets its author blamed | Exclusions can hide a problem | **adapt**: a safe-team-rules reference in codify (survey the uses, scope the rule, justify every exclusion) | [#16633](https://github.com/melodic-software/claude-code-plugins/pull/16633) | +| Format and lint plugins fixed to one tool | n/a (raised while absorbing) | n/a | Our format and lint plugins pick the tool, which may not fit a consumer and goes stale | **adapt**, in progress: format and lint plugins become tool-agnostic, with formatting and linting kept apart; no pull request is open yet | pending | + +### Mutation testing + +| Idea | What it does | Upstream problem | Our problem | Disposition | Landed | +|---|---|---|---|---|---| +| Mutation testing grades the tests, not the code | Reads a surviving mutant as a weak test | Inference: coverage says a line ran, not that a test checks it | Same | **already have**: [`/mutation-testing:principles`](../../plugins/mutation-testing/skills/principles/SKILL.md) | none | +| Mutate only the changed lines | Keeps a mutation run fast | Inference: a whole-repository run takes hours | Same | **already have**: `/mutation-testing:audit` runs on the diff by default | none | +| Run it before the change is reported done, and fix survivors | Puts mutation in the agent's own verification | Inference: survivors found after merge are rarely fixed | Ours ran only after merge | **adapt**: `/implementation:implement` ends with a diff-scoped mutation run, advisory, survivors persisted for a fix pass | [#16614](https://github.com/melodic-software/claude-code-plugins/pull/16614) | +| A survivor as a test-quality signal | Uses mutation results to inform the agent, without failing a build | Inference: a score threshold invites gaming | `/testing:test-value` did not name mutation | **adapt**: test-value names a surviving mutant as one weak-test signal and points to `mutation-testing` | [#16610](https://github.com/melodic-software/claude-code-plugins/pull/16610) | +| Plant specific defects to see if the tests catch them | n/a (carried over from the codebase-design workshop) | n/a | No skill planted realistic defects on purpose | **take**: a `seed-faults` action plants defects in a throwaway worktree and reports caught over planted, with each survivor's location; nothing it plants is committed | [#16632](https://github.com/melodic-software/claude-code-plugins/pull/16632) | +| A mutation skill tied to one tool and one repository's scripts | Hard-codes the tool and report format | Inference: a skill written for one project | A shipped skill must fit any consumer | **reject** the hard-coding: `mutation-testing` takes the tool from repository config. The pattern behind it is recorded: a shipped skill generates a repository-specific skill only where config cannot express the difference | [#16612](https://github.com/melodic-software/claude-code-plugins/pull/16612) | + +### Data sources + +| Idea | What it does | Upstream problem | Our problem | Disposition | Landed | +|---|---|---|---|---|---| +| Open runtime data to the agent: logs, the front end, databases, the tracker, an error reporter | Lets the agent check its work against what the app does | Inference: without runtime data the agent verifies against the code it just wrote | `/debugging:debug` named no concrete sources and asked for access only when no loop could be built | **adapt**: Phase 1 of `/debugging:debug` opens with a surface pass, and each source it cannot reach becomes a request for scoped access, never for a secret | [#16617](https://github.com/melodic-software/claude-code-plugins/pull/16617) | +| A record of which sources each environment exposes | n/a (raised while absorbing) | n/a | A control skill listed surfaces but not the data sources each environment offers | **adapt**, pending: a control skill's environments may name their data sources with a read level, and `drive ready` reports the missing ones; this waits on the open map-refresh change [#16481](https://github.com/melodic-software/claude-code-plugins/pull/16481) | pending | +| Read-only access to a production database | Gives the agent production data it cannot change | Inference: production holds the failing data | Same | **already have**: the `sql-server` plugin's read-only guarantee rests on a read-only database principal, not on the tool ([ADR 0086](../adr/0086-bound-the-sql-server-read-tier-by-a-read-only-principal-and-fixed-registrations.md)) | none | + +### Diagnosing bugs + +| Idea | What it does | Upstream problem | Our problem | Disposition | Landed | +|---|---|---|---|---|---| +| Build a feedback loop before any hypothesis | Gates diagnosis on a fast pass-fail signal | Inference: theories formed without a signal are guesses | Same | **already have**: `/debugging:debug`, compared section by section in [mattpocock-skills.md](mattpocock-skills.md) (row `diagnosing-bugs`), which this change corrects | this record | +| Read the domain glossary first | Grounds names before ranking causes | Inference: a hypothesis in the wrong terms points at the wrong module | Ours read decision records and instructions, not the glossary | **take**: Phase 3 reads the domain glossary where one exists | [#16617](https://github.com/melodic-software/claude-code-plugins/pull/16617) | +| The person names the port and the console | The prompt names the places to read | Inference: the agent does not know the app's surfaces | A person should only describe the problem | **adapt**: the surface pass runs `/app-control:drive ready` when a control skill exists, reads the surfaces each app type has, and never assumes a port | [#16617](https://github.com/melodic-software/claude-code-plugins/pull/16617) | +| Diagnosis as its own step | Finds the cause | Inference: some reports need the cause, not a fix | Ours always went on to fix | **adapt**: a `diagnose` action stops at the confirmed cause at file:line and changes no code | [#16617](https://github.com/melodic-software/claude-code-plugins/pull/16617) | +| Correlate the failure with what shipped | n/a (raised while absorbing) | n/a | Phase 3 read recent commits but not what each environment runs | **adapt**: Phase 3 checks each environment's recent deployments, CI runs and tickets, as a lead to test, never as proof | [#16617](https://github.com/melodic-software/claude-code-plugins/pull/16617) | +| Observability by default | n/a (raised while absorbing) | n/a | No reference told a builder how to leave an app diagnosable | **adapt**: an observability-by-default reference in `implementation` (structured, scoped logging; telemetry configured from the environment; local log levels kept out of version control), pointed to from `debugging` | [#16614](https://github.com/melodic-software/claude-code-plugins/pull/16614) | +| Lock the fix with a check shown red on the old code | Guards against the bug's return | Inference: a fixed bug comes back | Same | **already have**: Phase 5's regression test at a correct seam, or the seam gap as the finding | none | + +### Verifying frontend apps + +| Idea | What it does | Upstream problem | Our problem | Disposition | Landed | +|---|---|---|---|---|---| +| Give the agent a browser it drives from the terminal | Lets the agent see what types and tests cannot | Inference: visual faults are invisible in code | Same | **already have**: [`/playwright:playwright`](../../plugins/playwright/skills/playwright/SKILL.md) and `/testing:run-e2e`; no switch of browser tool without a measured reason | none | +| A repository doc for the browser tool where the agent records what it learns | Keeps project-specific driving knowledge in the repository | Inference: each session relearns the same gotchas | Lessons reached a control skill only when `map` ran | **adapt**: a `/debugging:debug` report lists its lessons about driving the app as `/app-control:map refresh` lines, `map` staying the one writer; refresh accepting them waits on [#16481](https://github.com/melodic-software/claude-code-plugins/pull/16481) | [#16617](https://github.com/melodic-software/claude-code-plugins/pull/16617) | +| Before and after screenshots in the pull request | Shows the change working | Inference: proof in the body saves a checkout | One evidence layout fit neither a small change nor a large one | **adapt**: small changes show evidence inline before and after; large ones get one collapsed section per acceptance criterion; text and logs first, media as support, with an optional record block | [#16616](https://github.com/melodic-software/claude-code-plugins/pull/16616) | +| Verification is worth a higher effort level | Spends more reasoning where evidence is made | Inference: evidence is the product of verification | Same | **already have**: the verifier role defaults to a higher effort; the role defaults were rechecked after two recheck triggers fired | [#16621](https://github.com/melodic-software/claude-code-plugins/pull/16621) | +| A required verification section in the pull request template | Makes the agent state what it checked | Inference: unstated checks did not happen | Same | **no change**: our body contract's `Verification` section stays advisory | none | + +### Found while absorbing + +| Item | Disposition | Landed | +|---|---|---| +| The `diagnosing-bugs` row in [mattpocock-skills.md](mattpocock-skills.md) called the clean-copy diff, the minimize step and the Phase 1 exit check open gaps, though all three had landed | **take**: the row is rewritten against upstream HEAD and our current skill | this record | +| `plugins/explainer-video/README.md` said GitHub's video player shows no soft captions; GitHub's [Attaching files](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/attaching-files) page is silent on caption tracks | **take**: the unsourced clause is removed; captions stay burned in and kept as a soft track | this change | +| Parallel test runs sharing a database, ports or temp directories | **adapt**: `/testing:write` adds parallel-run isolation beside its order rule | [#16610](https://github.com/melodic-software/claude-code-plugins/pull/16610) | + +### Handed elsewhere + +- Reviewing sensitive data sources before agents read them: outside this repository. +- Tool-agnostic format and lint plugins: in progress, as the row under "A custom lint rule" says. + +## License notice + +The course is paid content under its provider's terms; no lesson text, caption, image or code is +copied here. The public skills repository reads MIT on the host and in +[mattpocock-skills.md](mattpocock-skills.md); no text or code from it is copied either. + +- **Pointer**: when a license question arises, read the skills repository's + [LICENSE](https://github.com/mattpocock/skills/blob/4ae2317ddb22b046e26455e4f9c9b3aaaf62212d/LICENSE). +- **As of**: 2026-11-16 +- **Recheck trigger**: the skills repository's license file changes. diff --git a/docs/upstream/mattpocock-skills.md b/docs/upstream/mattpocock-skills.md index b36dbc1a48a..ee3de2aa89e 100644 --- a/docs/upstream/mattpocock-skills.md +++ b/docs/upstream/mattpocock-skills.md @@ -49,7 +49,7 @@ Re-auditing moves the pin and records the outcome per row. | [`tdd`](https://github.com/mattpocock/skills/tree/4ae2317ddb22b046e26455e4f9c9b3aaaf62212d/skills/engineering/tdd) (with its `tests.md` and `mocking.md`) | `planning:plan` Test strategy, `tdd:principles`, `testing:write`, `review` code-reviewer | Partial | Course lane C (#2936): C9 partial, relocated (agreeing test boundaries before writing tests lands in `plan`'s Test strategy element, deliberately not called "seam" and not hosted by `implementation:phase-verifier`; upstream's hard consent gate softened to a `DEVIATIONS.md` record an unattended run can satisfy); C10 already present (the tautological-test anti-pattern in `anti-patterns-khorikov.md` and `testing/write`; the executable half landed as a `code-reviewer.md` criterion, `review` 0.24.0, which defers to `cant-fail-scan.sh` when that scan's output is in context); C11 already present plus one clause (`test-doubles.md` has preferred typed client interfaces to a generic fetch wrapper since `85aa8066`; added only that the shape rule never widens what gets mocked). A zero-assembly chain document rejected, with reasons: the draft chain was wrong. Re-checked at `4ae2317`: holds; the one change is the seam note on the Map line, not taken | | [`improve-codebase-architecture`](https://github.com/mattpocock/skills/tree/4ae2317ddb22b046e26455e4f9c9b3aaaf62212d/skills/engineering/improve-codebase-architecture) scoping filter (v1.2, [#533](https://github.com/mattpocock/skills/pull/533)) | `architecture:improve` deepening Phase 1 | Partial | Adopted scoping before scanning: a direction the user names limits the scan; with none, recent-commit hot spots come first (precomputed context widened to 20 commits). Rejected upstream's fixed context file (we use our glossary-discovery ladder). The HTML report's CDN scripts and Mermaid, rejected earlier, were taken on 2026-11-16 with exact versions, a fallback and strict diagram settings ([aihero-codebase-design.md](aihero-codebase-design.md)); its card and diagram layout was taken before and is restated in our own words, see the map line. Corrected 2026-10-04: no grilling integration was ever taken; the deepening interview runs its own loop and calls only `domain-driven-design:ubiquitous-language`. Upstream's glossary file is `GLOSSARY.md` from v1.3 (was `CONTEXT.md`); the rejection stands. v1.3 removed the inbound hand-off from `diagnosing-bugs` (`1dab982`); nothing to change here. Re-checked at `4ae2317`: holds; the one change asks for a fresh context on the walking sub-agent (`7739eae`), and nothing recorded here depends on it | | [`codebase-design`](https://github.com/mattpocock/skills/tree/4ae2317ddb22b046e26455e4f9c9b3aaaf62212d/skills/engineering/codebase-design) (with its `DEEPENING.md` and `DESIGN-IT-TWICE.md`) | `architecture:improve` deepening | Derived | Corrected 2026-10-04 from convergent: the vocabulary was ported close to verbatim when the plugin was added (`30cf0343f`, 2026-07-10). Taken: the module-design vocabulary and its rejected framings, the four dependency categories, the two-adapter and internal-seam rules, replacing shallow-module tests rather than layering new ones, and the Design-It-Twice fan-out (framing first, orthogonal design constraints, a structured return per design, comparison on depth, locality and seam placement, an opinionated pick). From another source: the sixth return part for rejected shapes, reading the spread of returns as evidence, and the graft record for a hybrid come from pstack `arena` (see [`cursor-pstack.md`](cursor-pstack.md)). Ours: grounding a consequential winner outside the repository, and the scan briefing's badge-acceptance heuristics. Not taken: the fixed context file (we use our glossary-discovery ladder) and the testability code examples. Copy check 2026-10-04: restated in our own words, `vocabulary.md`, `interface-design.md` and `scan-briefing.md` around a tax-calculation example and `dependencies.md` around mail and shipping-rate examples; the only shared five-word runs left are labels other files cite (a return-part name and the category values). Upstream issues [#449](https://github.com/mattpocock/skills/issues/449) and [#458](https://github.com/mattpocock/skills/issues/458), open on 2026-10-04, ask how to apply it; none acted on. Re-checked at `4ae2317`: holds; the one change asks for a fresh context per design (`7739eae`); ours launches each design as its own subagent and does not state the fresh context (`plugins/architecture/skills/improve/research/deepening/interface-design.md`, "The briefs the subagents read"; corrected 2026-11-16, the line cited before concerns a reviewer dispatch) | -| [`diagnosing-bugs`](https://github.com/mattpocock/skills/tree/4ae2317ddb22b046e26455e4f9c9b3aaaf62212d/skills/engineering/diagnosing-bugs) (v1.2.3 redaction and tagged logs) | `debugging:debug`, `testing:diagnose` | Partial | Adopted the redaction guard in both skills (secrets replaced with `` in any shown command, output or artifact; credentials in environment variables covered; only signal lines quoted) and the `[DEBUG-a4f2]` tagged-log convention in `testing:diagnose` (already in `debugging:debug`). `debugging:debug` also carries the feedback-loop-first doctrine: a loop gate before any hypothesis, ten loop kinds ranked by preference, 3-5 ranked falsifiable hypotheses, the correct-seam rule for the regression test, and a human-run loop template. On 2026-10-04 these were restated in our own structure (one running example through every phase, the loop kinds and the seam rule as tables, a grouped cleanup checklist) and the template was rewritten. Upstream's separate minimize step and its Phase 1 completion checklist were first judged covered by our phase gates; the re-evaluation at `d81f3a1` (2026-10-04) reopened both as gaps under evaluation, since our regression-test step refers to a minimized repro that no phase produces. Upstream removed its post-mortem hand-off in `1dab982` (upstream PR #880): kept ours, because our post-mortem phase files the finding and calls no skill. Upstream PR #1121 (v1.3.1) routes the post-bug reflection to `retro`; recorded, nothing taken. Follow-on: [#6945](https://github.com/melodic-software/claude-code-plugins/issues/6945), where post-mortem answers that name a check get routed. Re-checked at `4ae2317`: changed by `f3fc563`: when a test was made to fail by editing source or test data, Phase 5 compares the edited file with a clean copy, to confirm the edit actually took effect. New candidate, not taken: `debugging:debug` has no such step (a search of its `SKILL.md` for `mutat` finds nothing); owner to decide in `debugging` | +| [`diagnosing-bugs`](https://github.com/mattpocock/skills/tree/4ae2317ddb22b046e26455e4f9c9b3aaaf62212d/skills/engineering/diagnosing-bugs) (v1.2.3 redaction and tagged logs) | `debugging:debug`, `testing:diagnose` | Partial | Adopted the redaction guard in both skills (secrets replaced with `` in any shown command, output or artifact; credentials in environment variables covered; only signal lines quoted) and the `[DEBUG-a4f2]` tagged-log convention in `testing:diagnose` (already in `debugging:debug`). `debugging:debug` also carries the feedback-loop-first doctrine: a loop gate before any hypothesis, ten loop kinds ranked by preference, 3-5 ranked falsifiable hypotheses, the correct-seam rule for the regression test, and a human-run loop template. On 2026-10-04 these were restated in our own structure (one running example through every phase, the loop kinds and the seam rule as tables, a grouped cleanup checklist) and the template was rewritten. The two gaps the `d81f3a1` re-evaluation reopened are closed: a Phase 1 exit check holds the loop to speed, one verdict per run and precision on the reported symptom ([#7009](https://github.com/melodic-software/claude-code-plugins/pull/7009)), and a Minimize step in Phase 2 cuts the red reproduction one element at a time before Phase 3 ranks causes ([#8828](https://github.com/melodic-software/claude-code-plugins/pull/8828)). Also taken in #8828, from `f3fc563`: when Phase 5 forces a red by editing code or a fixture, the edited file is diffed against the committed or saved copy before the red is trusted. Taken in [#16617](https://github.com/melodic-software/claude-code-plugins/pull/16617) (`7316ed62e0`): Phase 3 reads the project's domain glossary, where one exists, before ranking. Ours adds, with no upstream counterpart: a `diagnose` action that stops at the confirmed cause at file:line and changes no code, and a Phase 1 surface pass that reads the app's logs, console and ports (through `/app-control:drive ready` when a control skill exists), never assumes a port, and turns each source it cannot reach into a request for scoped access (#16617). Upstream removed its post-mortem hand-off in `1dab982` (upstream PR #880): kept ours, because our post-mortem phase files the finding and calls no skill. Upstream PR #1121 (v1.3.1) routes the post-bug reflection to `retro`; recorded, nothing taken. Not taken: the `agents/openai.yaml` Codex sidecar, rejected throughout ([Not adopted](#not-adopted)). Follow-on: [#6945](https://github.com/melodic-software/claude-code-plugins/issues/6945), where post-mortem answers that name a check get routed. Re-checked 2026-11-16 at upstream HEAD `5863806` against `plugins/debugging/skills/debug/SKILL.md` at `7316ed62e0`: nothing under the skill changed since the pin, its last upstream change being `f3fc563` | | [`wait-what`](https://github.com/mattpocock/skills/tree/4ae2317ddb22b046e26455e4f9c9b3aaaf62212d/skills/productivity/wait-what) (new in v1.2, [#751](https://github.com/mattpocock/skills/pull/751)) | `discipline:wait-what` | Derived | Ported as a declared non-corrector in `discipline`, beside `tighten-your-output` and `mind-your-maxims`; the home follows who is at fault (the model's output drifted, not the reader's comprehension). The name is kept under a PLUGIN-PHILOSOPHY naming exception (the utterance is the mechanism, and users know the upstream name); a naming tournament's winner, `re-pitch`, was declined by the user. Rejected upstream's fixed glossary file names (`CONTEXT.md` at v1.2.3, `GLOSSARY.md` and `GLOSSARY-MAP.md` from v1.3, `006a52b`, with no fallback for the old names; open upstream issue [#1153](https://github.com/mattpocock/skills/issues/1153)): we find the nearest glossary or context map by the consumer's convention and use plain technical English without one. Upstream's v1.3 map-following now matches ours, so the rejection covers only the fixed names. Kept user-invoked, on the evidence of the author's X thread (statuses 2084753070437609606, 2084941367659168064 and 2085681281795232026), which compares a standing instruction, an output style and an on-demand skill for this job. Copy check 2026-10-04 (`/attribution:audit`): the description and opening instruction were rewritten; the panel splits on whether the three-part instruction still follows upstream, so the question is open for a person | | [`wizard`](https://github.com/mattpocock/skills/tree/4ae2317ddb22b046e26455e4f9c9b3aaaf62212d/skills/engineering/wizard) (graduated in v1.2) | `wizard:generate` | Derived | Ported in lane 4 as the single-capability plugin `wizard` 0.1.0, hardened. Kept: the process (scope from the repo, a concrete path per stage, authoring onto the template, static verification), regrouped as three phases around one stage-plan table, a fixed, never hand-edited library section ahead of the `STAGES` marker, model invocation with an explicit non-trigger fence, degrading when `gh` is absent, ephemeral output by default, and the agent writing but never running the script. Hardened (deltas in `plugins/wizard/CHANGELOG.md` 0.1.0): a human reads and approves the whole STAGES block before `chmod +x`; `open_url` accepts https only (also closing a Windows UNC/NTLM leak through explorer.exe); prompts read `/dev/tty` and fail closed; `.env` writes are quoted, mode `0600`, gitignore-asserted and atomic; `gh` writes name a confirmed `--repo` and refuse empty values; key names are validated; readline on non-secret prompts (upstream [#741](https://github.com/mattpocock/skills/issues/741) where safe); live `.env` scoping reads names only. Rejected: the Codex `agents/openai.yaml` sidecar (see the Codex finding under Harness findings). Upstream status 2026-10-04: the template dropped its time-remaining display in v1.2.3 while its docs page still shows it; a later sync keeps it out. Open upstream bugs [#1041](https://github.com/mattpocock/skills/issues/1041) (`write_env` leaves the shell variable unset) and [#811](https://github.com/mattpocock/skills/issues/811) (a symlinked `.env` is replaced) reproduced in our `template.sh` and were fixed here by #6275 in wizard 0.6.4 (a symlinked `.env` is written through, not atomically). [#1142](https://github.com/mattpocock/skills/issues/1142) (editing the script mid-run can re-run steps or kill it) was fixed upstream at `main@49dd158` by wrapping the stages in a `run_wizard` function; ported, with `exit` inside the function so a formatter that splits `run_wizard "$@"; exit` onto two lines cannot undo the fix. Re-checked at `4ae2317`: of the `868c4cf` and `49dd158` template fixes, two reproduced here and are fixed in this change: #1220 (`_existing` offers no double-quoted value holding a backslash, `$`, `"` or a backtick, so the prompt asks again) and #774 (`open_url` no longer swallows its warning when no opener exists). #741, #770, #811, #852, #1041 and #1142 were already handled here. Not ported: #1081's ANSI fallback (ours survives a failing `tput clear` and skips the clear, `plugins/wizard/skills/generate/template.sh:111`) and #1003 (our `fatal` uses `RED`) | | [`prototype`](https://github.com/mattpocock/skills/tree/4ae2317ddb22b046e26455e4f9c9b3aaaf62212d/skills/engineering/prototype) HTML demo shell (v1.2) and evidence branch | `prototype:pressure-test` | Partial | Adopted in lane 5 (prototype 0.5.0): the terminal app stays the default; when the person driving it is not a developer, or no terminal fits, the throwaway shell over the same pure logic module is one self-contained `file://` page with domain labels, a state panel redrawn on each click, free-play buttons and guided scenarios that reset to a known start, under explore-directions' HTML constraints (restrictive CSP meta tag, a `mktemp -d` or `%LOCALAPPDATA%\Temp` location, synthetic data only, deleted after the markdown capture). Adopted after the repository's check (Q168): the evidence branch. After the durable note is written and before deletion, the prototype files go to a throwaway branch named by the consumer's own branch-naming convention, pushed only when the repository's own secrets and machine-data check passes, with the branch and commit SHA written into the note; with no check, a failed one or no declared branch-naming convention, nothing is pushed and the note records the local path and `not pushed: `. The note stays the primary record, and the push is a named exception to the delete-when-done rule (`plugins/prototype/context/discipline.md`, "Evidence step") | diff --git a/plugins/explainer-video/README.md b/plugins/explainer-video/README.md index 09118fdba30..c977c355f95 100644 --- a/plugins/explainer-video/README.md +++ b/plugins/explainer-video/README.md @@ -57,7 +57,7 @@ to set these keys, checked against `scripts/stills.py` turns a `storyboard.json` into one video of held 3840x2160 frames: each moment's frame comes from an escaping HTML template captured with Playwright for Python's Chromium (installed on the first stills render), narration is rebuilt in video time and loudness-normalized, -captions are burned in (GitHub's player shows no soft captions) and kept as a soft track and +captions are burned in and kept as a soft track and `captions.srt`, and the video is encoded once at CRF 18. Every hold's frame must reach luma SSIM 0.999 against its source above the caption band. The narration, frame text and screenshot sidecars pass a secret and machine-data scan before anything renders From 2bddc9cdb4e1d76a696aca8e1b9a582c3b3e3930 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:34:16 -0500 Subject: [PATCH 2/2] chore(explainer-video): add a no-release changelog fragment for the README edit Co-Authored-By: Claude Opus 5.5 --- .../explainer-video/docs-upstream-feedback-loops-f6042387.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changes/explainer-video/docs-upstream-feedback-loops-f6042387.md diff --git a/.changes/explainer-video/docs-upstream-feedback-loops-f6042387.md b/.changes/explainer-video/docs-upstream-feedback-loops-f6042387.md new file mode 100644 index 00000000000..3e5a50db78b --- /dev/null +++ b/.changes/explainer-video/docs-upstream-feedback-loops-f6042387.md @@ -0,0 +1,5 @@ +--- +bump: none +--- + +README only: drops an unsourced clause about GitHub's video player; nothing that ships changes.