diff --git a/docs/FINDING-YOUR-UNKNOWNS.md b/docs/FINDING-YOUR-UNKNOWNS.md new file mode 100644 index 000000000..846e94ba7 --- /dev/null +++ b/docs/FINDING-YOUR-UNKNOWNS.md @@ -0,0 +1,288 @@ +# Finding your unknowns + +Graduated reference for the "Finding Your Unknowns" methodology: an artifact-first way of +working where, before and during an implementation, the agent produces small purpose-built +artifacts (explainers, brainstorms, interviews, mockups, plans) whose job is to surface +what you don't yet know while it is still cheap to find out. This doc owns the house +conventions the methodology graduated into this marketplace — the reply-affordance +convention, the export-button rule, and the opt-in deviation-log convention — plus the +pattern catalog and the boundaries (when HTML, when not; what deliberately stays +un-codified). Sibling docs: `PLUGIN-PHILOSOPHY.md` (governance), +`GLOSSARY.md` (vocabulary), `MIGRATION-PLAYBOOK.md` (delivery). + +**Sources and permission basis.** The material derives from public posts by their named +author (see [Sources](#sources-and-citation-shape)). This doc quotes short attributed +verbatim excerpts under fair-quotation practice; no license is claimed and bulk +reproduction is avoided. Quotes are reproduced exactly as published — punctuation +included — and are never edited to fit this repo's style rules. + +## Contents + +- [Why this exists](#why-this-exists) +- [The unknowns taxonomy](#the-unknowns-taxonomy) +- [The five-pass pre-implementation workflow](#the-five-pass-pre-implementation-workflow) +- [Prompt-pattern catalog](#prompt-pattern-catalog) +- [Reply-affordance convention](#reply-affordance-convention) +- [Export-button rule](#export-button-rule) +- [Deviation-log convention (opt-in)](#deviation-log-convention-opt-in) +- [When HTML, and when not](#when-html-and-when-not) +- [The buy-in pattern](#the-buy-in-pattern) +- [Cautions from the source author](#cautions-from-the-source-author) +- [Heuristics awaiting evidence](#heuristics-awaiting-evidence) +- [Sources and citation shape](#sources-and-citation-shape) + +## Why this exists + +The methodology's economic argument, in the author's words: "Every explainer, brainstorm, +interview, prototype, and reference is a cheap way to find out what you didn't know before +it gets expensive to fix." (Field guide, [Sources](#sources-and-citation-shape) S1.) Each +pass below trades a few minutes of artifact review for a class of rework. + +Caution on the framing: the author's stronger thesis — that output quality is now +bottlenecked by the human's ability to clarify the model's unknowns — is a single +practitioner's vendor-published claim and is treated here as direction, not doctrine. + +## The unknowns taxonomy + +Four quadrants, asked as "what are your unknowns?" before prompting: + +- **Known knowns** — what the prompt already states. +- **Known unknowns** — questions you know to ask but haven't answered yet. +- **Unknown knowns** — things you assume without realizing you're assuming them; the + agent can't see them until you disclose them. +- **Unknown unknowns** — the pothole you didn't know the road could have; only an + artifact that shows you the terrain surfaces these. + +The draft article's quadrant taglines ("questions you know to ask", "the pothole you +didn't know the road could have") appear only in the X draft (S4), which is the citable +source for draft-only content. + +Findings that surface during an unknowns pass fall into four types (adopted as +`discovery:blindspot`'s output taxonomy): **Landmine** (a change that will break +something non-obvious), **History** (a constraint that exists for a reason the code no +longer shows), **Convention** (an unwritten team rule the work must follow), and +**Missing concept** (a domain idea the prompt never named). + +Two diagnostics ride the taxonomy: + +- Over-specifying and under-specifying are the same failure seen from two sides: both + mean the split between what you locked and what you left open didn't match your actual + unknowns. +- When a long-horizon task comes back wrong, check the unknowns and the plan's + adaptability before blaming the model: the usual root cause is an unknown that was + never surfaced, not a capability gap. + +The lifecycle is a loop: what an artifact teaches you becomes the starting map for the +next round. The author frames this as matching the map to the territory (S1, "Matching +map and territory") — cited here as his metaphor, not adopted as house vocabulary (see +`GLOSSARY.md` rejected terms). + +## The five-pass pre-implementation workflow + +The corpus composes its pre-implementation demos into one ordered flow. This repo ships a +skill per pass; the composition itself is judgment, not a gate — run the passes whose +unknowns you actually have, in this order when you run several: + +1. **Blindspot pass** — `/discovery:blindspot`: surface unknown unknowns in the task's + blast radius. +2. **Brainstorm / prototype** — `/planning:brainstorm` for direction candidates; + `/prototype:explore-directions` or `/prototype:pressure-test` when the unknown is + visual or interactive. +3. **Interview** — `/planning:interview`: convert known unknowns into decisions on the + record. +4. **Reference port** — `/discipline:point-dont-copy` when the work leans on an external + reference whose semantics must survive the port. +5. **Plan** — `/planning:plan`: lock the approach with the unknowns now known. + +Notes: the sequencing is chat-portable — every pass works as plain conversation, the +artifact form is optional. Running later passes in a fresh session with the earlier +artifacts carried forward matches this repo's existing session-flow doctrine (the corpus +independently corroborates it; see `session-flow` plugin). + +## Prompt-pattern catalog + +Patterns the corpus demonstrated that have no owning skill; each entry is one canonical +prompt-line to adapt. Patterns with an owning skill are listed in the +[workflow](#the-five-pass-pre-implementation-workflow) above — invoke the skill instead. + +- **Disclose your starting point** (primer for any pass): "Before we start: my starting + point is X, my current thinking is Y, my experience level with this area is Z." +- **Teach me my unknowns** (explainer with a vocabulary ladder): served by + `/education:explain`; ask it to end with the terms you should now be using. +- **Design-system HTML file**: "Generate a single HTML page from this codebase's real + tokens and components — one section per component family — so future design + conversations can cite it as the reference." +- **PR explainer page**: "Make a single-file HTML explainer of this PR for reviewers: + annotated diff hunks, a module map of what talks to what, and the three questions a + reviewer should ask." +- **Report/audit HTML view**: for recurring documents (status, incident timeline), + ask the producing skill for an HTML rendering as an opt-in output, never the default. +- **Quiz me before I merge**: served by `/education:quiz-me`; the merge gate itself stays + with `/verification:confirm` (one mechanism per concern). + +Reconciliation note: the corpus's "tweakable plan" ordering (high-tweak decisions first, +mechanical work collapsed) is already `planning:plan`'s documented presentation default; +it needed no new mode here. + +## Reply-affordance convention + +**The rule.** A generated review artifact ends with a structured reply affordance: a +machine-legible way for the human's reaction to become the next prompt — steal/skip +choices, a chip-filled reply template, a decisions table, a confirmation token. Default +with judgment: apply it to artifacts that exist to collect a decision; skip it for purely +informational output. In session contexts that render artifacts (the `artifact-design` +built-in skill's territory), the affordance rides the artifact; in plain chat it is a +reply template in the closing message. + +**Who is bound.** Skills that generate decision-collecting artifacts cite this section +instead of restating it. + +**Conformance** = the template blocks in `prototype:explore-directions` (structured +steal/graft capture and the assembled-reply template) and `prototype:pressure-test` (the +validation answer set). Fleet audits check those surfaces against this section. + +## Export-button rule + +**The rule.** An interactive HTML artifact always ends with an export affordance that +turns UI state back into something the user can paste or commit. In the author's words: +"The trick is always to end with an export: a "copy as JSON" or "copy as prompt" button +that turns whatever I did in the UI back into something I can paste into Claude Code." +(S2, "Custom editing interfaces".) The doctrine recurs three times independently in the +corpus; it is what keeps a throwaway editor inside the agent loop instead of becoming a +dead end. + +**Who is bound.** Skills that emit interactive HTML artifacts cite this section. + +**Conformance** = the same template blocks named in the +[reply-affordance convention](#reply-affordance-convention); the export button is the +HTML-artifact form of the reply affordance. + +## Deviation-log convention (opt-in) + +**The rule (opt-in).** An implementation session MAY keep an append-only `DEVIATIONS.md` +beside `PLAN.md` recording, per entry: what the plan said, what was found, what was chosen, +and whether a human needs to revisit. Entry types: plan-confirmed / discovery / deviation / +human-decision. Default conservative: when in doubt, log. The convention's contract text +is owned by `implementation:implement-dispatch` ("Divergence in non-interactive runs"); +this section records the house posture: opt-in for interactive sessions, required only +where a skill's own contract says so. + +**Recorded trigger.** The moment a second plugin reads `DEVIATIONS.md` (rather than +writing its own), the convention-registry rule fires and this section graduates to a +registry row per `PLUGIN-PHILOSOPHY.md` "Convention registry". + +## When HTML, and when not + +The corpus's examples index (S3) organizes twenty demos into nine categories — +exploration and planning, code review and understanding, design, prototyping, +illustrations and diagrams, decks, research and learning, reports, custom editing +interfaces — which double as the "when is HTML worth it" taxonomy: reach for a rendered +page when the information is spatial (diffs, call graphs), comparative (side-by-side +directions), interactive (motion you can only feel), or recurring (reports that benefit +from structure and color). + +- **Density rubric**: HTML earns its cost through tables, CSS, SVG, interaction, and + spatial layout. Markdown pushed past its density limit produces the degraded + workarounds (ASCII diagrams, unicode color) that signal you wanted a page. +- **Reading ceiling**: the author's ~100-line markdown ceiling is a practitioner + anecdote, recorded as such — not a measured threshold. +- **Sharing**: the publish-and-share argument is satisfied in this environment by the + Artifact tool; nothing extra to build. +- **Scoping rule**: HTML artifacts are for ephemeral and published outputs. They never + replace version-controlled instruction surfaces — HTML diffs are noisy (the author's + own admission) and generation costs 2-4x the markdown equivalent, so plans, skills, + and docs stay markdown in git. + +## The buy-in pattern + +For work that needs stakeholder agreement, the corpus's buy-in document has five +sections: demo first; the pitch; pre-answered objections; spec at a glance; risk and +rollback with named per-person asks and a deadline. The pre-answered-objections element +is the industry-standard core: Amazon's PR/FAQ carries an internal FAQ anticipating hard +leadership questions (Bezos 2017 shareholder letter; Bryar & Carr's Working Backwards), +and every surveyed RFC process — Rust RFCs, Oxide RFDs, Google design docs, Uber-style +RFCs — requires drawbacks/alternatives-considered sections. In all of those orgs the +persuasion artifact and the decision record are one document with a lifecycle, which is +why this repo extends existing planning artifacts rather than minting a parallel one. + +**Objection-evidence checklist** (reusable in PR descriptions): for each objection you +expect, write the question, the factual answer, and the evidence citation — before +anyone asks. An objection you can't answer factually is an unknown; route it back +through the [workflow](#the-five-pass-pre-implementation-workflow). + +## Cautions from the source author + +The corpus carries its own warning against exactly the move a plugin marketplace is +tempted to make, and this repo treats it as binding (it is why the deltas that landed are +judgment-preserving contract lines and doc entries, never generator skills): + +> I’m a little bit afraid that people will read this article and turn it into a /html +> skill or something. While there might be some value in that, I want to emphasize that +> you don’t need to do much to get Claude to do this. You can just ask it to “make a HTML +> file” or “make a HTML artifact”. +> +> The trick is knowing what you want the artifact to do and how you might use it. You may +> over time make a skill, but for now I’d suggest just prompting from scratch to get a +> hang of how to use it in different cases. (S2, "How to Get Started".) + +Two companions to the warning: + +- **Stay in the loop** is the evaluation lens for any artifact tooling: "All of the above + is to say that I think the real reason I use HTML is that I feel much more in the loop + with Claude." (S2, "Stay in the Loop".) Tooling that produces artifacts the user never + forms judgment about fails this criterion even when it satisfies density, sharing, and + ease. +- **Throwaway-editor doctrine**: a custom editing interface is "not a product, or a + reusable tool" — it is built for the exact thing being worked on and discarded. The + marketplace instinct to generalize a good throwaway into a shipped generator is the + failure mode the warning names. + +## Heuristics awaiting evidence + +The following corpus heuristics are recorded here as doc lines and candidate eval cases, +not as standing skill instructions — per `PLUGIN-PHILOSOPHY.md` "Instruction economy", +they graduate into a skill body only on observed, repeated stumble evidence: + +- **Observed-fact evidence bar** (brainstorming): each candidate option cites an observed, + falsifiable fact about the codebase (a path plus a claim that could be wrong), not just + a plausible path. +- **Already-built-but-disconnected scan**: before proposing new work, scan for dead + imports, dark feature flags, and unread tables — the improvement may already exist, + disconnected. +- **Non-obvious-behavior keying** (quizzes): author questions against behaviors a reader + would skim past, not against what the diff makes obvious. +- **Collapse self-check** (plans): before collapsing a section as "mechanical, trust me", + re-check that nothing in it is actually a judgment call — the corpus's failure case is + a design decision hidden in a collapsed section. + +## Sources and citation shape + +Citations in this doc use: URL, ISO retrieval date, and `sha256:` over the raw +snapshot bytes captured at retrieval. Content drift produces a new citation, never an +in-place hash edit. + +- **S1** — "A field guide to Claude Fable 5: Finding your unknowns", Thariq Shihipar, + Anthropic blog, published 2026-07-06. + `https://claude.com/blog/a-field-guide-to-claude-fable-finding-your-unknowns` + (retrieved 2026-09-01, + `sha256:ac8229699555d38eb0dfe6c80dd2e85353f30471a7abff0894d342b5107aad26`) +- **S2** — "Using Claude Code: The Unreasonable Effectiveness of HTML", X article by the + same author. `https://x.com/trq212/status/2052809885763747935` (retrieved 2026-09-01, + `sha256:07dc71b1a7fabe264b9a80ee003edbcd1e74013895372a8ffe13ee4bb178e63c`) +- **S3** — HTML-effectiveness examples index (20 demos, 9 categories, plus the 11-demo + "Know your unknowns" sub-collection). `https://thariqs.github.io/html-effectiveness` + (retrieved 2026-08-31, + `sha256:7e6da98b6b447ec39efdc6deb34602204e4641dc59f4e311e3f05fb23d74f98e`) +- **S4** — X draft of the field guide (citable only for draft-only content: the quadrant + taglines, the lifecycle-loop image, and three links the published blog dropped). + `https://x.com/trq212/status/2073100352921215386` (retrieved 2026-09-01; snapshot + pinned in the corpus work slice) +- Buy-in grounding: Bezos 2017 shareholder letter + (`https://www.aboutamazon.com/news/company-news/2017-letter-to-shareholders`), the + Working Backwards PR/FAQ + (`https://workingbackwards.com/concepts/working-backwards-pr-faq-process/`), Rust RFCs + (`https://raw.githubusercontent.com/rust-lang/rfcs/master/README.md`), Oxide RFD 1 + (`https://rfd.shared.oxide.computer/rfd/0001`), Google design docs + (`https://www.industrialempathy.com/posts/design-docs-at-google/`), and Uber-style + RFCs (`https://blog.pragmaticengineer.com/scaling-engineering-teams-via-writing-things-down-rfcs/`), + all retrieved 2026-09-01. diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index 3d7be3f41..c7b9514be 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -72,6 +72,21 @@ The healthiest of `context-guard`'s three context zones (`smart` / `acceptable` the band rather than any token figure — the band numbers are declared judgment defaults and tunable per consumer. +**unknowns quadrants** + +The four-way pre-prompt breakdown — known knowns, known unknowns, unknown knowns, unknown +unknowns — used to decide which unknown-finding pass a task needs. Owned by +[`FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md); entries cite it rather than restating the +quadrants. + +**blindspot finding types** + +The typed taxonomy a blindspot pass reports its findings in: Landmine (breaks something +non-obvious), History (a constraint the code no longer shows), Convention (an unwritten team +rule), Missing concept (a domain idea the prompt never named). The output contract lives in +`discovery:blindspot`; the taxonomy's rationale in +[`FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md). + ## Rejected terms Names considered for a concept this project already owns, recorded so they are not reintroduced. @@ -86,11 +101,17 @@ Each maps to the term or doctrine that owns the concept. | cache *(the doc-restating-environment sense)* | `docs-hygiene:audit-derivability`'s derivable-from-environment doctrine; the word is overloaded here (plugin cache, prompt cache) | | sediment | the `docs-hygiene` audit family's pruning doctrine; collides with the code-sense use in `playbooks:fable-5` | | sycophancy | nothing — a generic LLM-behavior term with no distinct project meaning. Free-prose use is unaffected; it is simply not project vocabulary | +| map / territory | the source author's metaphor, cited where it appears in [`FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md) "The unknowns taxonomy"; never house vocabulary (metaphor-jargon risk) | ## Provenance -Every term above was graded and adopted in lane 6 of the AI Hero course vetting +Terms through "smart zone" were graded and adopted in lane 6 of the AI Hero course vetting (2026-08-18). The decision rows, including the basis for each verdict and the rejected-term mappings, are in [`upstream/aihero-course.md`](upstream/aihero-course.md) under "Term adoption". Materialization of this file was tracked as [#3000](https://github.com/melodic-software/claude-code-plugins/issues/3000). + +"unknowns quadrants", "blindspot finding types", and the map/territory rejected-terms row were +adopted at the finding-your-unknowns integration sign-off (2026-09-01); the decision record is +[ADR 0025](adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md) and the +shipping PR carries the full decision sheet. diff --git a/docs/PLUGIN-PHILOSOPHY.md b/docs/PLUGIN-PHILOSOPHY.md index f57c03073..f8d60014f 100644 --- a/docs/PLUGIN-PHILOSOPHY.md +++ b/docs/PLUGIN-PHILOSOPHY.md @@ -637,6 +637,8 @@ doc before a second plugin adopts it. Fleet audits check conformance per row. | Always-on hook cost ceiling | [`docs/conventions/hook-budget/`](conventions/hook-budget/README.md) | | Tracker reference form inside a code comment | [`docs/conventions/tracker-reference-form/`](conventions/tracker-reference-form/README.md) | | Untrusted-content framing contract | [`docs/conventions/untrusted-content/`](conventions/untrusted-content/README.md) | +| Reply affordance on decision-collecting artifacts | [`docs/FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md#reply-affordance-convention) | +| Export button on interactive HTML artifacts | [`docs/FINDING-YOUR-UNKNOWNS.md`](FINDING-YOUR-UNKNOWNS.md#export-button-rule) | ## Cross-platform contract diff --git a/docs/adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md b/docs/adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md new file mode 100644 index 000000000..58a3b4c4b --- /dev/null +++ b/docs/adr/0025-adopt-the-unknowns-corpus-as-judgment-preserving-contract-deltas.md @@ -0,0 +1,60 @@ +# Adopt the "Finding Your Unknowns" corpus as judgment-preserving contract deltas + +- Status: accepted +- Date: 2026-09-01 + +## Context + +A practitioner corpus on artifact-first development — Thariq Shihipar's "A field guide to +Claude Fable 5: Finding your unknowns" (Anthropic blog, 2026-07-06), its X-article +methodology substrate "The Unreasonable Effectiveness of HTML", and a 20-demo example +collection — was ingested as 17 verified digest slices (byte-exact quoting, dual +verification) and worked through a full decision chain: a relentless interview, a +read-only evidence pass grading every named-skill collision, dual fresh-context +validators, external research grounding seven practice areas in primary sources, +blindspot/brainstorm/devils-advocate passes, and a signed single-sheet decision surface. +The working material lived in the branch's contract slice and prunes with it per the +topic-docs convention; the shipping PR (#3592) carries the full plan and verification +record, and the corpus itself is the primary source a future auditor reads. + +The corpus's own author warns against exactly the move a plugin marketplace is tempted to +make — turning the material into generator skills — and the marketplace's instruction +economy separately requires observed, repeated stumble evidence before any standing +instruction lands. Genuine alternatives existed: adopt the techniques as new skills, +adopt them as standing instructions, or reject codification entirely. + +## Decision + +Absorb the corpus behind a per-row evidence-gate classification, with the author's +anti-premature-codification warning treated as a binding constraint: + +- CONTRACT / POLICY / CONVENTION rows land now as team conventions adopted at the + sign-off, as additive lines in the owning skills' bodies with same-commit eval + expectations, never as generator skills. +- BEHAVIORAL rows never land as standing instructions: they ship as doc lines in + `docs/FINDING-YOUR-UNKNOWNS.md` plus tracked eval candidates (#3589), awaiting + observed-stumble evidence. +- `docs/FINDING-YOUR-UNKNOWNS.md` is the graduated reference and the owner doc for the + reply-affordance and export-button conventions (registry rows point at it, + owner-doc-first); it quotes the warning byte-faithfully under a stated fair-quotation + basis. +- Quiz-as-merge-gate reroutes to `verification:confirm`'s existing gate (one mechanism + per concern); the external-reference port gate is scoped to sources of truth outside + the repo's tree via the corrector method's declared-step-delta seam; the deviation log + ships opt-in with a recorded registry trigger (a second plugin reading `DEVIATIONS.md` + graduates it to an owner doc). +- The corpus's context-engineering companion routes to the incumbent effort recorded in + [ADR 0004](0004-rightsize-instruction-surfaces-by-incumbent-first-arbitration.md) + rather than a parallel lane; its three candidate inputs are tracked on the issue + tracker since that effort's contract slice has graduated. + +## Consequences + +Eight plugins gained contract lines and minor version bumps (discovery, education, +verification, prototype, planning, discipline, session-flow, implementation), each with +evals extended in the same commit. Two conventions are in force with named conformance +surfaces. Deferred sub-decisions carry recorded triggers on the tracker (#3590 buy-in +skill extension behind demand evidence; #3591 register-schema flag, tweak-likelihood +flip, deviation-log registry row, digest-pipeline hardening). Reversal is possible but +priced: each convention names its conformance surfaces, and the eval expectations +outlive any instruction ablation, which is what makes a future deletion round provable. diff --git a/plugins/discipline/.claude-plugin/plugin.json b/plugins/discipline/.claude-plugin/plugin.json index f85625b3a..ef66f7884 100644 --- a/plugins/discipline/.claude-plugin/plugin.json +++ b/plugins/discipline/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "discipline", - "version": "0.12.20", + "version": "0.13.0", "description": "Discipline correctors that re-anchor a standing rule mid-session, then audit both the work in flight and the pre-existing state and choices it trusts, and correct what has drifted: do-your-research (research and no-assumptions discipline; sibling do-your-research-deep escalates to a typed full inventory of the session's claims — assumptions, asserted facts, concrete specifics, load-bearing premises — verified at a configurable depth and reported as a per-item ledger), follow-our-standards (alignment to the consuming org's engineering conventions), point-dont-copy (pointer-over-copy discipline — no copied content, internal-name coupling, or closed capability lists), reason-dont-recite (interrogate inherited content — precedent is evidence of what is, never self-justifying authority), tighten-your-output (terseness discipline — fewer words or lines with no loss of meaning or correctness), recheck-against-upstream (existing state is not evidence of its own correctness — audit config, code, and infra against current official upstream docs; sibling recheck-against-upstream-deep fans subagents doc-by-doc over a whole subsystem), pick-for-the-problem (tool, library, framework, and approach selection fitted to the problem, not reached for out of habit, availability, incumbency, or preconception), mind-your-maxims (cooperative-communication discipline per Grice plus the AI-augmented transparency maxim), script-the-deterministic-work (offload deterministic sub-work — counts, diffs, sorts, transforms, and scaffolds — to a script that runs, reserving model output for judgment over its real output; the audit runs both ways, also catching an existing script that over-reaches into judgement), use-your-skills (actually use the skills already in context — scan the listing, map the task, invoke the fitting skill instead of reinventing it, and name skills when delegating to a subagent), and reuse-or-replace (anti-fragmentation — new work reuses an established way of doing something or openly replaces it (migrate the old uses, record the decision), never silently stands up a second parallel way; divergence is allowed but owes a recorded reason proportional to blast radius), and scrutinize-dont-coast (adversarial self-scrutiny — stop coasting on your own recent output and re-examine whether it is sound, not merely confidently produced, through a fresh-context pass blind to the reasoning that made it, then remediate with the user; it stops the trajectory first and remediates collaboratively rather than autonomously). Plus further species that are not correctors (examples, not a fixed list — each skill's own description is authoritative), including setup, sweep-all, a posture-batch runbook that composes them — it fans out an audit-only subagent per in-scope corrector, then applies the corrections on the main thread in a fixed order, with batch membership and order set by each corrector's own colocated tier metadata and an optional userConfig overlay — and wait-what, a one-shot user-invoked-only communication repair: type /discipline:wait-what when the last message did not land and the model re-pitches it, backing up as far as needed, adding the missing context, in ASD-STE100 Simplified Technical English, using the project's ubiquitous language; never model-invoked and never in the batch. Firing a corrector is a re-anchor, not an accusation; the audit may return clean.", "author": { "name": "Melodic Software", diff --git a/plugins/discipline/CHANGELOG.md b/plugins/discipline/CHANGELOG.md index efcd06008..70118c6b8 100644 --- a/plugins/discipline/CHANGELOG.md +++ b/plugins/discipline/CHANGELOG.md @@ -5,6 +5,26 @@ All notable changes to the `discipline` plugin are documented here. Format follo Entries below `0.9.0` were released under the plugin's former name, `re-anchor`. +## [0.13.0] + +### Added + +- **`point-dont-copy`: the no-analogue trap check and a canonical invocation hint.** The audit + list gains the cross-stack port trap: a source-side primitive with no target-side analogue (a + language feature, a library guarantee, an implicit runtime behavior) whose invariant the port + silently drops — the port must name the convention now carrying that invariant, or the finding + stands. The skill also gains an `argument-hint` showing the canonical invocation. Adopted from + the "Finding Your Unknowns" corpus at the integration sign-off (E7, E8; provenance in + `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository). Evals extended. +- **`point-dont-copy`: semantics map + confirmation gate for external-reference ports.** A + declared step delta on the shared re-anchor/audit/correct loop, scoped to ports whose source + of truth lives outside this repo's tree (vendored, foreign-language, other-repo): between + audit and correct-forward, produce a five-section semantics map (what the source does, + side-by-side pairs, preserved/changed/dropped ledger, edge-case parity table, open questions) + and stop at a confirmation gate until the user confirms it — "semantics confirmed" recommended, + not required. In-tree corrections stay do-it-now; the no-analogue trap check feeds the dropped + ledger. Same adoption basis (E6, boundary per the signed C3); a new eval case covers the gate. + ## [0.12.20] ### Changed diff --git a/plugins/discipline/skills/point-dont-copy/SKILL.md b/plugins/discipline/skills/point-dont-copy/SKILL.md index e2e8e89f8..b2bf0865b 100644 --- a/plugins/discipline/skills/point-dont-copy/SKILL.md +++ b/plugins/discipline/skills/point-dont-copy/SKILL.md @@ -1,5 +1,6 @@ --- description: "Re-anchor pointer-over-copy discipline, then audit the work in flight for copied content, internal-name coupling, and closed capability lists, and correct by pointing at the living source. Use when: 'point don't copy', 'you copied that', 'don't duplicate the docs', 'cite instead of paste', 'link don't restate', 'you enumerated the tools', 'that couples to internal names', 'this will drift', or at conversation start on documentation work." +argument-hint: "[target] (e.g., /discipline:point-dont-copy the new setup guide, or empty to audit the work in flight)" user-invocable: true disable-model-invocation: false metadata: @@ -81,7 +82,12 @@ Name concrete, located findings (per the method doc's step 2, self-audit): invocation contract would do; - a closed enumeration of duties or mechanisms that will drift as the surface evolves; -- the same passage, literal, or concept appearing in two or more places. +- the same passage, literal, or concept appearing in two or more places; +- in a port from another stack or language: a source-side primitive with no + target-side analogue (a language feature, a library guarantee, an + implicit runtime behavior) whose invariant the port silently drops. The + port must name the convention now carrying that invariant, or the + finding stands. Correct each forward now: replace the copy with a pointer to its owner, swap an internal-name reference for the public contract, and reopen a @@ -89,6 +95,26 @@ closed enumeration into a general duty with marked examples. Where content is genuinely this project's own to hold (an adapted config, a self-pinned constraint, a dated research deliverable), say so and leave it. +## External-reference ports. Semantics map + confirmation gate + +**Scope.** This section governs external-reference ports only: work whose source of truth +lives outside this repo's tree: vendored, foreign-language, other-repo. In-tree +corrections stay on the method doc's do-it-now side; nothing here changes that. + +**Declared step delta** (per the method doc's "Declared step deltas" allowance): for an +external-reference port, insert between the loop's steps 2 and 3 a semantics map and a +confirmation gate, because a port that starts before the semantics are agreed bakes +misreads into working code, where the audit can no longer see them as findings: + +- **Semantics map**, externalized, five sections: what the source does; side-by-side + pairs (source construct against port construct); a preserved / changed / dropped + ledger; an edge-case parity table; the open questions the port cannot settle alone. + The no-analogue trap check above feeds the dropped ledger: every dropped source + primitive names the convention now carrying its invariant. +- **Confirmation gate.** Stop and wait for the user to confirm the map before port work + proceeds. A reply of "semantics confirmed" is the recommended token, not a required + one; any clear confirmation opens the gate. + ## What this skill does NOT do - **Does not strip legitimate local content.** An adapted config, a diff --git a/plugins/discipline/skills/point-dont-copy/evals/evals.json b/plugins/discipline/skills/point-dont-copy/evals/evals.json index 5dc589872..42444ca4f 100644 --- a/plugins/discipline/skills/point-dont-copy/evals/evals.json +++ b/plugins/discipline/skills/point-dont-copy/evals/evals.json @@ -10,7 +10,8 @@ "expectations": [ "Flags both the verbatim-pasted reference and the reworded paraphrase as duplication findings", "States that a reworded paraphrase drifts the same as a verbatim copy", - "Corrects forward by replacing the copied content with a pointer/citation to the owning source" + "Corrects forward by replacing the copied content with a pointer/citation to the owning source", + "In a cross-stack port, a source-side primitive with no target analogue is flagged unless the port names the convention now carrying its invariant" ] }, { @@ -48,6 +49,19 @@ "Recommends consolidating to a single source and pointing at it", "Leaves room for a merits-based legitimate-divergence exception rather than an absolute rule" ] + }, + { + "id": 5, + "name": "external-reference-port-gate", + "prompt": "Port this Python rate-limiter module from the vendored library into our TypeScript services package. Keep the behavior identical.", + "expected_output": "Recognizes an external-reference port (source of truth outside this repo's tree: vendored, foreign-language, other-repo) and applies the declared step delta: produces the five-section semantics map (what the source does; side-by-side pairs; preserved/changed/dropped ledger; edge-case parity table; open questions), with the no-analogue trap check feeding the dropped ledger, then stops at the confirmation gate and waits for the user to confirm the map before any port code is written. A 'semantics confirmed' reply is recommended, not required.", + "files": [], + "expectations": [ + "Classifies the task as an external-reference port (source of truth outside this repo's tree) and applies the semantics-map step delta", + "Produces a semantics map with side-by-side pairs, a preserved/changed/dropped ledger, and an edge-case parity table before porting", + "Stops and waits for the user to confirm the map before port work proceeds, recommending but not requiring a 'semantics confirmed' reply", + "Does not extend the stop-and-wait gate to in-tree corrections, which stay do-it-now per the shared method doc" + ] } ] } diff --git a/plugins/discovery/.claude-plugin/plugin.json b/plugins/discovery/.claude-plugin/plugin.json index 12643c2f0..b5d5c6d6b 100644 --- a/plugins/discovery/.claude-plugin/plugin.json +++ b/plugins/discovery/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "discovery", - "version": "0.18.0", + "version": "0.19.0", "description": "Structured discovery before changes: explore the local codebase, run disciplined multi-source external research, and reconstruct why a past decision was made from evidence outside the code — each dispatching a purpose-built subagent by default so the reading stays out of the main conversation, with source tiers, falsification, recency gates, an intent-evidence tier, and a corpus-coverage ledger — persisting EXPLORE.md / RESEARCH.md / INTENT.md index-plus-sidecar handoff artifacts.", "author": { "name": "Melodic Software", diff --git a/plugins/discovery/CHANGELOG.md b/plugins/discovery/CHANGELOG.md index cfc2e2248..5020776a4 100644 --- a/plugins/discovery/CHANGELOG.md +++ b/plugins/discovery/CHANGELOG.md @@ -1,5 +1,19 @@ # Changelog — discovery plugin +## [0.19.0] + +### Added + +- **`blindspot`: typed finding cards and a scan-scope disclosure line.** Each blindspot card now + leads with a finding type from a four-way taxonomy — Landmine (breaks something non-obvious), + History (a constraint whose reason the code no longer shows), Convention (an unwritten team + rule), Missing concept (a domain idea the framing never named) — so repeated runs teach the user + which kinds of unknowns they tend to carry. The output also ends with a one-line scan-scope + disclosure naming which lane(s) ran and what was and was not scanned. Adopted from the + "Finding Your Unknowns" corpus at the integration sign-off (team-convention tier, evidence and + provenance in `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository); evals extended to + cover both contract lines. + ## [0.18.0] ### Changed diff --git a/plugins/discovery/skills/blindspot/SKILL.md b/plugins/discovery/skills/blindspot/SKILL.md index 397abd83f..f3285e273 100644 --- a/plugins/discovery/skills/blindspot/SKILL.md +++ b/plugins/discovery/skills/blindspot/SKILL.md @@ -43,9 +43,9 @@ understanding rather than the agent's. would break. - **Domain lane**. Build a lightweight vocabulary ladder grounded in sources fetched this session (repo files, official docs), never bare training recall. -3. **Output. Blindspot cards.** One card per blindspot: the gap, why it matters here, and a copyable - prompt-fix line. Close by assembling the fixes into ONE improved implementation prompt the user can - run next. +3. **Output. Blindspot cards.** One card per blindspot, typed by the kind of gap it is (Landmine / + History / Convention / Missing concept): the gap, why it matters here, and a copyable prompt-fix + line. Close by assembling the fixes into ONE improved implementation prompt the user can run next. 4. **Escalate when depth warranted**, a domain too deep for a lightweight ladder gets a recommendation to run proper external research (`/discovery:research`) or whatever structured-learning capability the environment provides. @@ -54,6 +54,10 @@ understanding rather than the agent's. Present each blindspot as a card: +- **Type**, one of four: **Landmine** (the change would break something non-obvious), **History** + (a constraint whose reason the code no longer shows), **Convention** (an unwritten team rule the + work must follow), or **Missing concept** (a domain idea the user's framing never named). The + type tells the user which kind of unknown they were carrying, so repeated runs teach a pattern. - **Gap**, the specific thing the user's current framing did not account for. - **Why it matters here**, the concrete consequence in this codebase or domain, not a generic caution. - **Prompt-fix**, a single copyable line the user can drop into their prompt to close the gap. @@ -61,6 +65,10 @@ Present each blindspot as a card: Then assemble every prompt-fix into ONE improved implementation prompt, wrapped in clear copy-start / copy-end markers so the exact text to reuse is unambiguous. +End with one scan-scope disclosure line: which lane(s) ran and what was and was not scanned (areas +read, sources fetched), so the user knows what the cards do and do not cover. One line, not a +methodology dump. + This skill does NOT write `EXPLORE.md`. Its deliverable is the user's understanding plus the improved prompt. When the scan's findings also serve as stage-1 codebase exploration, offer to hand off to `/discovery:explore` to persist the `EXPLORE.md` artifact rather than diff --git a/plugins/discovery/skills/blindspot/evals/evals.json b/plugins/discovery/skills/blindspot/evals/evals.json index bcd50d44c..9f756491c 100644 --- a/plugins/discovery/skills/blindspot/evals/evals.json +++ b/plugins/discovery/skills/blindspot/evals/evals.json @@ -11,7 +11,9 @@ "Output builds the USER's understanding (blindspot cards + an improved prompt), not just the agent's internal findings", "The run asks one intake question about the user's starting point before scanning", "Each blindspot is expressed as a card naming the gap, why it matters here, and a copyable prompt-fix line", + "Each card carries a finding type from the four-way taxonomy: Landmine, History, Convention, or Missing concept", "Output closes by assembling the fixes into a single improved implementation prompt the user can run next", + "The output ends with a one-line scan-scope disclosure naming which lane(s) ran and what was and was not scanned", "The run does not write EXPLORE.md" ] }, diff --git a/plugins/education/.claude-plugin/plugin.json b/plugins/education/.claude-plugin/plugin.json index 4cc3cfd3c..f5683749b 100644 --- a/plugins/education/.claude-plugin/plugin.json +++ b/plugins/education/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "education", - "version": "0.8.8", + "version": "0.9.0", "description": "Interactive multi-session learning coach: teaches a general subject or a concept grounded in the consuming repo through the Knowledge-Skills-Wisdom progression, with persistent per-topic learning state. Also a single-session domain primer, a one-shot plain-language explainer that drops anything to genuinely plain words, and a post-work comprehension check that quizzes the human on a completed change.", "author": { "name": "Melodic Software", diff --git a/plugins/education/CHANGELOG.md b/plugins/education/CHANGELOG.md index e24611d85..40c2ad379 100644 --- a/plugins/education/CHANGELOG.md +++ b/plugins/education/CHANGELOG.md @@ -3,6 +3,24 @@ All notable changes to the `education` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.9.0] + +### Added + +- **`explain`: vocabulary-ladder entries and an original-ask success condition.** Rung-2 terms of + art now arrive as ladder entries — the term, an ordinary-words definition, and a modeled "you + can now say" sentence the user can reuse — and when the explanation serves a task the user was + stuck on, success is judged by whether their next prompt names what they mean (bare + comprehension asks are exempt by scope). Adopted from the "Finding Your Unknowns" corpus at the + integration sign-off (team-convention tier; provenance in `docs/FINDING-YOUR-UNKNOWNS.md` in the + marketplace repository). Evals extended, including a new original-ask case. +- **`quiz-me`: diff-sourced, anchored questions and a fresh-context answer key.** Quiz questions + are authored from the change's actual diff and the report's own sections; every question is + anchored to the section that teaches its answer and a miss routes the reader to that exact + section before any retry; the embedded answer key is produced or verified by a fresh-context + pass reading only the report and diff (re-derived from the artifact alone when no fresh surface + is available). Same adoption basis; evals extended for all three contract lines. + ## [0.8.8] ### Changed diff --git a/plugins/education/skills/explain/SKILL.md b/plugins/education/skills/explain/SKILL.md index 53113494e..918c194f5 100644 --- a/plugins/education/skills/explain/SKILL.md +++ b/plugins/education/skills/explain/SKILL.md @@ -62,7 +62,7 @@ actually know X"). Never front-load a higher rung. | Rung | Altitude | Move | |------|----------|------| | 1 (default) | **Plain / ELI5** | Concrete everyday analogy, zero jargon. The floor and the default landing. | -| 2 (on request) | **High-school** | Introduce one or two real terms of art, each defined as it appears. Keep the analogy as scaffolding. | +| 2 (on request) | **High-school** | Introduce one or two real terms of art as vocabulary-ladder entries: the term, its definition in ordinary words, and one modeled "you can now say: …" sentence showing the term doing work in the user's own next prompt. Keep the analogy as scaffolding. | | 3 (on request) | **Peer** | Full precision, jargon allowed, edge cases and tradeoffs, the explanation a colleague in the field would want. | Offer the next rung as a one-line invitation, not a wall of text: "That's the @@ -79,6 +79,14 @@ why, and ground harder (re-read the source, fetch the primary reference) before claiming to explain it. A confident-sounding restatement of jargon is the failure mode this check exists to catch. +## Success condition (original-ask invocations only) + +When the explanation serves a task the user was stuck on, the success test is their **next +prompt**: it names what they mean in the newly plain terms instead of re-gesturing at the +confusion. Judge the explanation by that, and shape rung-2 vocabulary entries so the user can +reuse them. A bare comprehension ask with no task behind it ("I don't get it", full stop) has no +next-prompt contrast; this check does not apply there. + ## Handoff to `education:teach` Close every explanation with a single lightweight line offering the multi-session diff --git a/plugins/education/skills/explain/evals/evals.json b/plugins/education/skills/explain/evals/evals.json index 714dd572d..c754f3290 100644 --- a/plugins/education/skills/explain/evals/evals.json +++ b/plugins/education/skills/explain/evals/evals.json @@ -34,7 +34,8 @@ "expectations": [ "Recognizes the explicit request for higher altitude and climbs the rung ladder rather than staying pinned at rung 1", "Treats altitude as request-driven — it does not default to dumping the peer-level explanation on an unqualified 'explain X'", - "Introduces real terms of art with definitions as altitude increases rather than assuming them silently" + "Introduces real terms of art with definitions as altitude increases rather than assuming them silently", + "Rung-2 terms arrive as vocabulary-ladder entries: the term, an ordinary-words definition, and a modeled 'you can now say' sentence the user can reuse in their next prompt" ] }, { @@ -84,6 +85,18 @@ "Asks 'What would you like explained?' (or equivalent) instead of proceeding blind or inventing a topic to explain", "Does not hallucinate a referent or produce a confident plain-language explanation of something never stated" ] + }, + { + "id": 8, + "name": "original-ask-success-condition", + "prompt": "I'm trying to write a Postgres migration that adds a partial index but it keeps rejecting my syntax, and I don't get what \"predicate\" means in the docs. Explain it so I can fix my migration.", + "expected_output": "Lands a rung-1 plain explanation of a partial-index predicate (concrete analogy, jargon defined inline), aimed at unblocking the migration the user is stuck on. Because an original ask exists, the close shapes the vocabulary so the user's NEXT prompt can name what they mean (using \"predicate\" correctly), treating that next prompt as the success test rather than the explanation itself.", + "files": [], + "expectations": [ + "Recognizes the original ask behind the comprehension request and aims the explanation at unblocking it", + "Treats the user's next prompt as the success test: the close equips them to name what they mean (reusing the term correctly) rather than re-gesturing at the confusion", + "Still lands at rung 1 first with a concrete analogy and inline definitions" + ] } ] } diff --git a/plugins/education/skills/quiz-me/SKILL.md b/plugins/education/skills/quiz-me/SKILL.md index 525d7e741..c229b3936 100644 --- a/plugins/education/skills/quiz-me/SKILL.md +++ b/plugins/education/skills/quiz-me/SKILL.md @@ -76,6 +76,19 @@ pattern ("a quiz at the bottom on the changes that I must pass"). Match each nar section's length to what the change needs: cover the substance, but do not pad with filler, redundant summaries, or boilerplate. +- **Questions are diff-sourced.** Author each quiz question from the change's actual diff + and the report sections that explain it, never from generic topic knowledge a reader + could answer without having followed this change. +- **Each question carries a source anchor, and a miss routes to it.** Anchor every + question to the report section that teaches its answer (a report-internal anchor, or a + durable pointer per the reference discipline below). On a missed question, send the + reader to that exact section — the skimmed material, quoted or linked — before any + retry; the miss's job is routing, not scoring. +- **The answer key is fresh-context authored.** Produce or verify the embedded key with a + fresh-context pass that reads only the report and the diff, not the authoring + conversation, so grading tests what the artifact actually supports rather than what its + author remembers meaning. Where no fresh sub-agent surface is available, re-derive the + key from the artifact alone before embedding it. - **Answer key persists with the artifact.** Embed the key in the report, a collapsed `
` block in HTML, an appendix section in the markdown fallback. Grade in-conversation in the same session; a later or compacted session grades by reading the diff --git a/plugins/education/skills/quiz-me/evals/evals.json b/plugins/education/skills/quiz-me/evals/evals.json index 07e37624b..2d07cb1f9 100644 --- a/plugins/education/skills/quiz-me/evals/evals.json +++ b/plugins/education/skills/quiz-me/evals/evals.json @@ -10,7 +10,10 @@ "expectations": [ "Produces a self-contained HTML report (inline CSS/JS, no remote fetch) with context/intuition/decisions/what-was-done sections and a quiz at the bottom", "Treats the human's comprehension of the completed work as the object under test — not whether the artifact is correct or works", - "Embeds the answer key in the artifact (collapsed details in HTML) rather than leaving grading impossible for a later session" + "Embeds the answer key in the artifact (collapsed details in HTML) rather than leaving grading impossible for a later session", + "Quiz questions are authored from the change's actual diff and the report's own sections, not from generic topic knowledge", + "Each question is anchored to the report section that teaches its answer, and a missed question routes the reader to that exact section before any retry", + "The answer key is produced or verified by a fresh-context pass reading only the report and diff, or re-derived from the artifact alone when no fresh surface is available" ] }, { diff --git a/plugins/implementation/.claude-plugin/plugin.json b/plugins/implementation/.claude-plugin/plugin.json index ba17112aa..aae0acca9 100644 --- a/plugins/implementation/.claude-plugin/plugin.json +++ b/plugins/implementation/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "implementation", - "version": "0.15.9", + "version": "0.16.0", "description": "Disciplined implementation stage: execute approved plans inline (`/implementation:implement`) or via orchestrated worker subagents (`/implementation:implement-dispatch`) with incremental validation, TDD-by-default cadence, green-checkpoint commits, scope-fence drift detection, and divergence detection that routes back to planning. Build/test/lint, testing, and outcome verification live in the companion `toolchain`, `testing`, and `verification` plugins, invoked when installed.", "author": { "name": "Melodic Software", diff --git a/plugins/implementation/CHANGELOG.md b/plugins/implementation/CHANGELOG.md index dea1adafb..aa5982208 100644 --- a/plugins/implementation/CHANGELOG.md +++ b/plugins/implementation/CHANGELOG.md @@ -3,6 +3,23 @@ All notable changes to the `implementation` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.16.0] + +### Added + +- **Deviation-log convention: typed entries, interactive opt-in, and a completion fold-back.** + `implement-dispatch`'s "Divergence in non-interactive runs" contract gains entry types + (plan-confirmed / discovery / deviation / human-decision, the last marked blocking or + non-blocking) and four deviation fields (plan said / found / chose / revisit), stated as this + plugin's own output contract for its own log file, never a format imposed on consumer repos. + `implement` Step 3 gains the interactive opt-in (same log, same contract, for long or + contested sessions), and Step 5 gains a deviation fold-back item: read `DEVIATIONS.md` at + completion and emit one plan-amendment bullet per unresolved entry. Recorded trigger: when a + second plugin reads `DEVIATIONS.md`, the marketplace's convention-registry rule fires and the + contract graduates to an owner doc. Adopted from the "Finding Your Unknowns" corpus at the + integration sign-off (E1, E2; provenance in `docs/FINDING-YOUR-UNKNOWNS.md` in the + marketplace repository). Evals extended in both skills. + ## [0.15.9] ### Changed diff --git a/plugins/implementation/skills/implement-dispatch/SKILL.md b/plugins/implementation/skills/implement-dispatch/SKILL.md index fc78cdbf3..93e0a546f 100644 --- a/plugins/implementation/skills/implement-dispatch/SKILL.md +++ b/plugins/implementation/skills/implement-dispatch/SKILL.md @@ -68,6 +68,9 @@ In a session with no human to escalate to, stop-and-escalate on Moderate diverge - **Evidence is a pointer, not prose**. A commit SHA, a `file:line`, a test name, an artifact path. Prefer evidence a committed script produced over a hand-made one-off, so the reviewer can re-run it rather than believe it. - **Carry the outcome, not just the choice.** An entry whose result is still unknown says so (`unverified`) rather than reading as settled; an entry claiming a result names the check that produced it. State which work is unverified rather than omitting the distinction, the same grounding rule `work-items:work-loop` and `source-control:babysit-loop` apply to their cycle reports. - **One entry is one decision.** If it does not fit on a line or two, the decision is not crisp yet, split it, or say plainly that it is still open. +- **Entries are typed, and a deviation carries four fields.** Type each entry as one of: plan-confirmed (a load-bearing plan assumption checked out), discovery (something learned the plan never spoke to), deviation (the plan said X, the run did Y), or human-decision (a call only a person can make, marked blocking or non-blocking). A deviation entry answers: plan said / found / chose / revisit. This taxonomy is this plugin's own output contract for its own log file, never a format imposed on consumer repos. + +Interactive sessions may opt into this same log rather than leaving Moderate adjustments in scrollback (see `/implementation:implement` "Step 3: Divergence Detection"); the house posture and rationale live in `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository. Recorded trigger: the moment a second plugin READS `DEVIATIONS.md` rather than writing its own, the marketplace's convention-registry rule fires and this contract graduates to an owner doc with a registry row. An entry whose evidence does not resolve, or whose result was never verified, is the PR review catching a gap. That is the log working. Major divergence (fundamental assumption wrong) still STOPS even autonomously. Park the run with a handoff note rather than improvising a new design. Interactive sessions keep the `/implementation:implement` "Step 3: Divergence Detection" escalation ladder unchanged. diff --git a/plugins/implementation/skills/implement-dispatch/evals/evals.json b/plugins/implementation/skills/implement-dispatch/evals/evals.json index d5d4bab9e..28419c252 100644 --- a/plugins/implementation/skills/implement-dispatch/evals/evals.json +++ b/plugins/implementation/skills/implement-dispatch/evals/evals.json @@ -61,6 +61,7 @@ "Does NOT deadlock the autonomous run waiting for a human on a moderate divergence", "Picks the conservative option (closest to plan intent, smallest blast radius) for the moderate divergence", "Logs the deviation to a DEVIATIONS.md beside the plan artifact (what was planned, what was done, why, blast radius)", + "The logged entry is typed (plan-confirmed / discovery / deviation / human-decision), and a deviation entry answers plan said / found / chose / revisit", "Reserves a hard STOP for major divergence (a fundamental assumption wrong), not this moderate one" ] }, diff --git a/plugins/implementation/skills/implement/SKILL.md b/plugins/implementation/skills/implement/SKILL.md index 77d365a6e..ede901f1a 100644 --- a/plugins/implementation/skills/implement/SKILL.md +++ b/plugins/implementation/skills/implement/SKILL.md @@ -116,6 +116,8 @@ Most important discipline in execution. Plans are hypotheses, implementation is **Non-interactive fork (autonomous runs only):** see `/implementation:implement-dispatch` "Divergence in non-interactive runs". Moderate divergence takes the conservative option + a deviations log instead of deadlocking; Major still STOPS. Interactive sessions keep the escalation ladder above unchanged. +**Opt-in deviation log (interactive):** an interactive session may keep the same append-only `DEVIATIONS.md` beside the plan artifact, typing entries per the contract in `/implementation:implement-dispatch` "Divergence in non-interactive runs" (plan-confirmed / discovery / deviation / human-decision; a deviation answers plan said / found / chose / revisit). Worth opting into when the session is long, the plan is contested, or a handoff is likely: the Moderate rung's "document what changed and why" then has a durable home instead of scrollback, and Step 5's fold-back has something to read. + ## Step 3.5: Scope-fence drift detector (run at every decision boundary) **When**: at each phase boundary, at each worker-agent return, and BEFORE proposing any action not literally in the approved plan's work items. @@ -177,13 +179,14 @@ When all planned work is done: 1. **Final build check**. Invoke `/toolchain:check` via the Skill tool for all affected ecosystems when the `toolchain` plugin is installed; otherwise run the project's own build/test command 2. **Run all affected tests**. Include the tests you wrote and any tests your changes could impact -3. **Self-review (a floor, not the final verdict)**. The producing context converges on approval, so this catches slips but does not render the outcome verdict (step 5 hands to `/verification:confirm`, which renders it from outside the producing loop). Read through changes (`git diff HEAD~N`) looking for: +3. **Self-review (a floor, not the final verdict)**. The producing context converges on approval, so this catches slips but does not render the outcome verdict (step 6 hands to `/verification:confirm`, which renders it from outside the producing loop). Read through changes (`git diff HEAD~N`) looking for: - Consistency with existing patterns - No debugging artifacts left behind - No commented-out code - No TODO comments that should be actual work -4. **Rubber-duck advisor checkpoint (HIGH/CRITICAL only)**. For changes involving concurrency, security, cross-platform behavior, external API integration, or with significant divergence from the original plan, call the `advisor` tool (when available in the session) for a quick cross-model critique pass before the review gate. Skip for trivial changes -5. **Hand off to the pre-PR sequence**. Hand off, do not re-order: that sequence owns the step order (invoke `/session-flow:workflow pre-pr` via the Skill tool when the `session-flow` plugin is installed to read it; otherwise follow the consuming setup's own pre-PR checklist). Its order puts **review before outcome verification**, because the simplify pass sits between them and outcome verification must judge the code that ships. So: suggest the project's review flow first (`/review:quality-gate` when the `review` plugin is installed; otherwise the consuming setup's review step), then `/verification:confirm` for outcome verification once the diff is final (when the `verification` plugin is installed; otherwise self-verify the outcome against the plan/intent directly), then the PR (`/source-control:pull-request` when that plugin is installed; otherwise whatever the consuming setup provides. The user controls timing). Do not commit-and-push unilaterally, final staging and PR creation belong to that flow +4. **Deviation fold-back**. When a `DEVIATIONS.md` exists for this work (the non-interactive fork wrote one, or the session opted in per Step 3), read it now and emit one plan-amendment bullet per unresolved deviation or human-decision entry: what the plan should say next time, or what still needs a person. The log is the run's memory; a completion that never reads it back hands the PR reviewer deviations the author already knew about. Fold the bullets into the phase-boundary plan updates (Step 4 ritual) or the handoff summary +5. **Rubber-duck advisor checkpoint (HIGH/CRITICAL only)**. For changes involving concurrency, security, cross-platform behavior, external API integration, or with significant divergence from the original plan, call the `advisor` tool (when available in the session) for a quick cross-model critique pass before the review gate. Skip for trivial changes +6. **Hand off to the pre-PR sequence**. Hand off, do not re-order: that sequence owns the step order (invoke `/session-flow:workflow pre-pr` via the Skill tool when the `session-flow` plugin is installed to read it; otherwise follow the consuming setup's own pre-PR checklist). Its order puts **review before outcome verification**, because the simplify pass sits between them and outcome verification must judge the code that ships. So: suggest the project's review flow first (`/review:quality-gate` when the `review` plugin is installed; otherwise the consuming setup's review step), then `/verification:confirm` for outcome verification once the diff is final (when the `verification` plugin is installed; otherwise self-verify the outcome against the plan/intent directly), then the PR (`/source-control:pull-request` when that plugin is installed; otherwise whatever the consuming setup provides. The user controls timing). Do not commit-and-push unilaterally, final staging and PR creation belong to that flow ## Skill chaining during execution diff --git a/plugins/implementation/skills/implement/evals/evals.json b/plugins/implementation/skills/implement/evals/evals.json index beca6e706..155a37434 100644 --- a/plugins/implementation/skills/implement/evals/evals.json +++ b/plugins/implementation/skills/implement/evals/evals.json @@ -37,7 +37,8 @@ "Classifies the wrong SDK-capability assumption as major divergence, not a minor inline fixup", "STOPS writing code instead of pushing through with workarounds/hacks to force the original plan to fit", "Runs external research for alternatives before re-planning, then routes back to the planning skill for the user to approve the new direction", - "Does NOT silently expand scope or improvise a new design without surfacing it to the user" + "Does NOT silently expand scope or improvise a new design without surfacing it to the user", + "When a DEVIATIONS.md exists for the work, completion reads it back and emits a plan-amendment bullet per unresolved deviation or human-decision entry rather than handing the reviewer a log nobody folded back" ] }, { diff --git a/plugins/planning/.claude-plugin/plugin.json b/plugins/planning/.claude-plugin/plugin.json index 3bcf51835..8b8a1a528 100644 --- a/plugins/planning/.claude-plugin/plugin.json +++ b/plugins/planning/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "planning", - "version": "0.34.16", + "version": "0.35.0", "userConfig": { "use_ask_user_question": { "type": "boolean", diff --git a/plugins/planning/CHANGELOG.md b/plugins/planning/CHANGELOG.md index 0e1e4e36f..edfeb81ce 100644 --- a/plugins/planning/CHANGELOG.md +++ b/plugins/planning/CHANGELOG.md @@ -3,6 +3,44 @@ All notable changes to the `planning` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.35.0] + +### Added + +- **`plan`: switch conditions on alternatives and pre-drafted revision replies.** Every rejected + alternative in the plan template now carries a one-line switch condition (the observable fact + that would make it the better choice), and Step 5's presentation closes with 2-4 pre-drafted + one-line revision replies, one per flagged close call, so the user's cheapest reaction is + pasting one back. The sanity-check paragraph also names what those checks back downstream: + implementation's every-step-lands-green expectation. Adopted from the "Finding Your Unknowns" + corpus at the integration sign-off (D32, D33, D35; provenance in + `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository). Evals extended. +- **`interview`: free-text resolution-field flag.** A reply that RESOLVES its question but + arrives as free text rather than an authored option (a complete answer in the user's own + words, or an explicit "you pick", which resolves to the recommendation) is recorded with a + `free-text:` prefix in the register row's resolution field so downstream passes scrutinize + it; a partial or non-resolving reply keeps its row `open` under the drift check, so the flag + never launders a non-answer into `answered`. Deliberately a convention inside the free-form + field: `check-open-questions.sh` grades statuses, not resolutions, so the flag is + gate-invisible (limitation recorded in `context/loop.md`); the 5-field register schema is + unchanged (D28). Evals extended. +- **`design`: tweak-likelihood ordering in discussion rounds.** Phase 5 findings are presented + in the same tweak-likelihood order `plan` Step 5 documents: contracts, data shapes, and + user-facing surfaces lead; mechanical threads sit at the bottom (D36). Evals extended. +- **`brainstorm`: session-start rationale line; `wayfind`: five-pass workflow cross-ref.** One + citable line each (D9; Q7), both pointing at the marketplace repository's + `docs/FINDING-YOUR-UNKNOWNS.md`. + +### Changed + +- **`interview-defenses` digests refreshed for the D28 addition.** The free-text-flag paragraph + lands inside the digested open-question-register section of `context/loop.md`, and its eval + expectation moved from case 12 (no answer arrives in that scenario, so the criterion was + ungradeable there) to case 1 (answers arrive). Both defenses re-read and confirmed intact: + the flag adds scrutiny on answered rows and qualifies neither the ask-time write rule nor + the gap/blocker register bindings. Register-section and case-1 digests updated in the same + change, per the suite's own contract. + ## [0.34.16] ### Changed diff --git a/plugins/planning/skills/brainstorm/SKILL.md b/plugins/planning/skills/brainstorm/SKILL.md index f9cef000a..beb37f494 100644 --- a/plugins/planning/skills/brainstorm/SKILL.md +++ b/plugins/planning/skills/brainstorm/SKILL.md @@ -12,6 +12,8 @@ metadata: The divergence step before any scoping: unknown-knowns (criteria the user only recognizes when seen) surface cheapest at candidate-list time. Finding one mid-implementation costs a re-plan. A brainstorm round also calibrates scope: reacting to a cheapest→most-ambitious spread prevents locking a scope that is too narrow (missed the high-value approach) or too wide (ambition the problem doesn't need). +Opening a fresh session on a rough problem with a brainstorm is a citable practice, not a detour: the cheapest→ambitious spread is the cheapest artifact that surfaces criteria the user only recognizes when seen (rationale and sources: `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository). + Distinct neighbors: `/planning:design` Phase 1 decomposes the problem space WITHIN a design task already chosen; a proactive architecture-friction scan (e.g. `/architecture:improve`, if installed) hunts on its own lanes; a UI-variation prototyper (e.g. `/prototype:explore-directions`, if installed) builds visual variations of a chosen direction. This skill is the general, problem-shaped entry upstream of all three. Creative-domain ideation owned by a domain skill (e.g. songwriting brainstorms → `/songwriting:workflow`, if installed) stays with that skill. ## Task diff --git a/plugins/planning/skills/design/SKILL.md b/plugins/planning/skills/design/SKILL.md index 58541939d..e6fd6da2e 100644 --- a/plugins/planning/skills/design/SKILL.md +++ b/plugins/planning/skills/design/SKILL.md @@ -136,7 +136,7 @@ Systematic gap-finding. For each round: 1. Re-read all design artifacts 2. Identify underspecified types, missing contracts, boundary friction, pattern concerns, and design-default gaps (configurability, extension axes, observability, testability). Record these as design threads -3. Present findings to user for discussion +3. Present findings to user for discussion, ordered by tweak likelihood (the same presentation default `/planning:plan` Step 5 documents): the threads the user is most likely to redirect — public contracts, data shapes, user-facing surfaces — lead the round; settled-looking mechanical threads sit at the bottom. Presentation order only; thread dependencies still govern what can resolve when 4. When discussion surfaces project-wide principles, suggest codifying them immediately in the project's own rules Continue rounds until no new gaps surface. Then run the `handoff` action, which invokes `/planning:design-handoff` via the Skill tool for the binary gate and plan-ready summary. diff --git a/plugins/planning/skills/design/evals/evals.json b/plugins/planning/skills/design/evals/evals.json index ff93d8894..bfc0a04f6 100644 --- a/plugins/planning/skills/design/evals/evals.json +++ b/plugins/planning/skills/design/evals/evals.json @@ -10,6 +10,7 @@ "expectations": [ "Output explores the design collaboratively, asking the user rather than unilaterally deciding the types/boundaries", "Output tracks design threads with a resolution status (resolved / directional / deferred)", + "Discussion-round findings are presented in tweak-likelihood order: contracts, data shapes, and user-facing surfaces lead; settled-looking mechanical threads sit at the bottom", "Output builds design artifacts (e.g. capability-matrix / type-inventory / design-threads / topology) rather than jumping to an implementation plan" ] }, diff --git a/plugins/planning/skills/interview/context/loop.md b/plugins/planning/skills/interview/context/loop.md index 27f8905b5..a7858879a 100644 --- a/plugins/planning/skills/interview/context/loop.md +++ b/plugins/planning/skills/interview/context/loop.md @@ -206,6 +206,8 @@ Fields: `Q | status | round | question | resolution`. Statuses: `Q` matches the terminal numbering, runs continuously across rounds, and never has a gap — a gap means a row was dropped after it was written, and the gate refuses to grade a register with one. +**Free-text flag — a resolution-field convention.** When a reply RESOLVES its question but arrives as free text rather than a pick from the authored options — the escape hatch, a complete answer in the user's own words, an explicit "you pick" (which resolves to the recommendation) — lead the resolution field with `free-text:` before the answer. Downstream passes (answer audits, plan formulation) treat flagged rows as deserving scrutiny rather than as settled picks: a free-text answer is where a misread lands silently. The flag never launders a non-answer into `answered`: a partial or non-resolving reply keeps its row `open` under the drift check below, exactly as if the reply had changed the subject. This lives inside the free-form resolution field by design; `check-open-questions.sh` grades statuses, not resolutions, so the flag is gate-invisible (a known limitation, recorded here) — a consumer needing mechanical reads of it means a register-schema change, carried by a version bump per the plugin's changelog discipline. + ### Drift check — a reply that does not answer is not an answer **After every user reply, before doing anything else, check the reply against the register's `open` rows.** Any row the reply did not address stays `open`, and you restate it at the top of your next response — even when the reply changed the subject entirely, even when you are mid-answer to something else, and even when the reply reads as agreement. Conversational drift is never consent, and the user changing the subject is ordinary conversation, not a defect on their side. diff --git a/plugins/planning/skills/interview/evals/evals.json b/plugins/planning/skills/interview/evals/evals.json index c5982337c..6093739d6 100644 --- a/plugins/planning/skills/interview/evals/evals.json +++ b/plugins/planning/skills/interview/evals/evals.json @@ -11,7 +11,8 @@ "Output asks the round's independent frontier questions together as one numbered set, not spread across separate turns", "Each question leads with a recommended answer and a one-line basis", "The round is asked inline in prose, not via a side-by-side AskUserQuestion card", - "Where a question is answerable from the codebase, the skill resolves it by inspection instead of spending a question on it" + "Where a question is answerable from the codebase, the skill resolves it by inspection instead of spending a question on it", + "A reply that resolves its question but arrives as free text rather than an authored option is recorded with the free-text: resolution-field flag so downstream passes scrutinize it; a partial or non-resolving reply keeps its row open" ] }, { diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index 399e1797c..7e2955f01 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -95,7 +95,10 @@ Produce a structured plan using the template in [context/plan-template.md](conte - **Approach**: the specific steps, in order - **Test strategy**: how we'll verify the changes work. For which test type each kind of change needs (unit / integration / e2e / architecture / analyzer), `/testing:plan`'s file-type classification table is the SSOT **when the `testing` plugin is installed**; **invoke `/tdd:principles` via the Skill tool (if installed)** when formulating this section for authoritative guidance on what to test, which testing style fits, and when to mock; otherwise apply standard test-design judgment. TDD is the default approach. The test strategy should specify Red-Green-Refactor unless genuinely impractical. **Name the test boundaries**. The public interfaces the tests will drive, and for each whether it already exists or is being introduced (prefer driving an existing interface over introducing one for testability alone). Naming them is what lets Step 5's approval settle them, so implementation writes no test against a boundary the plan never named; on an unattended run, a boundary chosen during implementation that this section did not name is a deviation, logged for PR-time review (`DEVIATIONS.md` beside `PLAN.md` in the contract slice) rather than silently taken - **Files affected**: what gets created, modified, or deleted -- **Alternatives considered**: what was rejected and why +- **Alternatives considered**: what was rejected and why — and, per alternative, a one-line + switch condition: the observable fact that, if it turned up, would make this the better choice. + A rejection with no switch condition is not revisable; the condition is what lets a reviewer + (or a later phase) flip the decision without re-deriving the analysis - **Risks and mitigations**: what could go wrong Scale the plan to the task: @@ -117,7 +120,7 @@ Per-scale calibration examples live in [context/plan-template.md](context/plan-t **File inventory for large-scope plans**. When a plan or phase touches ≥10 files, emit a checkbox inventory table per phase (file, action, rationale). Checkboxes enforce verification discipline. The agent ticks each file as processed; the reviewer sees completeness at a glance. Include KEEP rows for files audited and deliberately left unchanged. Full format in [context/plan-template.md](context/plan-template.md) "File Inventory". -**Sanity-check verifiable-criterion enforcement**. Every phase ends with at least one `**Sanity Check:**` bullet. Criteria MUST be mechanically verifiable (a specific grep, file Read assertion, build exit code, test exit code, or runtime probe). Never vague (~~"documented appropriately"~~, ~~"behaves as expected"~~, ~~"all cases covered"~~). Rewrite vague criteria as exact commands a fresh session can execute without inferential judgement. Full format guide in [context/plan-template.md](context/plan-template.md) "Sanity-Check Format". +**Sanity-check verifiable-criterion enforcement**. Every phase ends with at least one `**Sanity Check:**` bullet. Criteria MUST be mechanically verifiable (a specific grep, file Read assertion, build exit code, test exit code, or runtime probe). Never vague (~~"documented appropriately"~~, ~~"behaves as expected"~~, ~~"all cases covered"~~). Rewrite vague criteria as exact commands a fresh session can execute without inferential judgement. Full format guide in [context/plan-template.md](context/plan-template.md) "Sanity-Check Format". Phase-scoped sanity checks are also what backs implementation's every-step-lands-green expectation: each phase can be verified green at its own boundary rather than only at the end. **Build-technique selection**. BEFORE ordering phases, pick the de-risking technique by the task's *uncertainty type*, not by habit. A design or viability unknown (*might abandon*) resolves **upstream**. `/planning:design` for design-significant questions, a throwaway `/prototype:pressure-test` spike (if installed) or research for raw feasibility. And plan **consumes that outcome** rather than re-deriving it inline. Plan's own call is the *kept* slice: a tracer bullet / walking skeleton when you are committed to ship and the risk is integration. When an upstream feasibility spike and ship-commitment both hold, sequence the kept tracer-bullet slice after the spike's outcome lands. Trivial / pure-horizontal work skips all techniques. @@ -219,6 +222,7 @@ Present the final plan to the user. The plan is a proposal, not a commitment. Th 4. **Execution shape** (from Step 4.5). Parallelism shape AND per-phase routing table. Skipped for single-phase plans 5. **Decisions made (gate-passed)** (from Step 4.6). TABLE per [context/tag-decisions.md](context/tag-decisions.md) "Presentation contract": `Decision | What it changes in the plan | Basis (evidence)`, one row per gate-passed `[EXEC-SHAPE]` / `[FALLBACK]` tag, written for a cold reader (no session shorthand). Below-bar decisions never appear here. They were interviewed before the plan locked. An empty section ("no unilateral decisions. Every PLAN item traces to brief") is also valid output 6. **Explicit approval request**: "Approve this plan to proceed to execution, or provide feedback to revise. Anything tagged `[EXEC-SHAPE]` or `[FALLBACK]` above is /planning:plan's discretion. Flag any you want changed." +7. **Highest-leverage replies**: close with 2-4 pre-drafted one-line revision replies, one per flagged close call or gate-passed decision, each a copyable sentence that flips exactly that decision (e.g. "Switch phase 2 to the queue-based alternative"). The user's cheapest possible reaction is pasting one back; a presentation whose flagged decisions have no pre-drafted flip line makes the user compose the revision themselves **Presentation order. Tweak-likelihood first.** Order the presentation by what the user is most likely to change on review: data-model/schema choices, type interfaces and public contracts, and user-facing surfaces LEAD (flag close calls with their alternatives); mechanical refactoring and low-judgment work sits at the bottom. Presentation order only. Phase EXECUTION order stays integration-first per Step 2. Optionally offer a self-contained HTML plan view (decisions-first layout, flagged choices with toggleable alternatives), rendered to the topic-docs **ephemeral tier**, never the contract slice beside `PLAN.md`, which stays the tracked record. Placement and rules: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md). diff --git a/plugins/planning/skills/plan/evals/evals.json b/plugins/planning/skills/plan/evals/evals.json index a896cc324..367187559 100644 --- a/plugins/planning/skills/plan/evals/evals.json +++ b/plugins/planning/skills/plan/evals/evals.json @@ -9,8 +9,10 @@ "files": [], "expectations": [ "Output produces a structured plan with at minimum a goal, an ordered approach, and a test strategy", + "Each rejected alternative carries a one-line switch condition naming the observable fact that would make it the better choice", "Output includes a blast-radius assessment line", "Output ends by requesting explicit user approval before execution rather than starting to implement", + "The presentation closes with pre-drafted one-line revision replies, one per flagged close call, each a copyable sentence that flips exactly that decision", "The run does not write or edit any source code file" ] }, diff --git a/plugins/planning/skills/wayfind/SKILL.md b/plugins/planning/skills/wayfind/SKILL.md index c7d801166..e80219761 100644 --- a/plugins/planning/skills/wayfind/SKILL.md +++ b/plugins/planning/skills/wayfind/SKILL.md @@ -179,6 +179,10 @@ owns the trigger's meaning (too-big + fog, both, not either alone). | External-evidence item | `/discovery:research` | `research`-typed items route here (autonomous) | | The plan itself | `/planning:plan` | Graduation target when the destination is a PLAN | +For pre-implementation efforts, the routed items above compose into a known five-pass order +(blindspot → brainstorm/prototype → interview → reference port → plan); the workflow section of +`docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository states it with rationale. + ## What this skill does NOT do - **Does not do build work.** A map holds decisions; build items live on the ordinary tracker diff --git a/plugins/planning/tests/interview-defenses.test.sh b/plugins/planning/tests/interview-defenses.test.sh index ac1efe470..c9bd1b1a5 100755 --- a/plugins/planning/tests/interview-defenses.test.sh +++ b/plugins/planning/tests/interview-defenses.test.sh @@ -483,7 +483,7 @@ pin_section "loop.md open-question register section is unchanged (it binds gaps "$LOOP" \ "## The open-question register" \ "## Step 3 — Recognize the stop condition" \ - "66dd3352d4ad6152aa6237b92f1cc1abc31f2cdd5ad5a517adb859408f52f26e" + "1507ecb169de8ff22e11e6fec211906069344d6afa4fcd05e283e456bd6926da" # loop.md carries TWINS of two SKILL.md lines that are byte-pinned there: the # confirmation-gate exemption ("`lock` is exempt … its STOP-on-gap rule still applies") in # Step 3, and the `USER-RESERVED` arbiter guidance in Step 4. A twin with no pin is a @@ -577,7 +577,7 @@ pin_case_digest "case 12 still refuses to read drift as consent" \ "e45fe64a00cf78e6dd089837e81c52d8a0947ccf924be6472c6f47eeadcd5942" pin_case_digest "case 1 still resolves codebase-answerable questions without asking, and only those" \ "relentless-me-mode-frontier-rounds" \ - "a1d108f02272c18494b5ca0a0c108385b776ff63bc423cb075c6e052810abc4a" + "5e38782253a410890320cddc3c5c44d71ab64666bb596bc954167f1447059bdd" pin_file "case A fixture: the task context still plants the open decision" \ "$FIXTURES/lock-stop-on-gap/task-context.md" \ diff --git a/plugins/prototype/.claude-plugin/plugin.json b/plugins/prototype/.claude-plugin/plugin.json index e32435c24..78f31422b 100644 --- a/plugins/prototype/.claude-plugin/plugin.json +++ b/plugins/prototype/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "prototype", - "version": "0.9.8", + "version": "0.10.0", "description": "Builds throwaway code to answer a design question before committing to architecture — a logic facet (an interactive terminal app over a portable state model) and a UI facet (radically different visual variants on one route).", "author": { "name": "Melodic Software", diff --git a/plugins/prototype/CHANGELOG.md b/plugins/prototype/CHANGELOG.md index f5be3658c..18e4f5148 100644 --- a/plugins/prototype/CHANGELOG.md +++ b/plugins/prototype/CHANGELOG.md @@ -3,6 +3,29 @@ All notable changes to the `prototype` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.10.0] + +### Added + +- **`explore-directions`: same-data control variable, single-decision graft capture, and a + machine-legible reply template.** Variants now bind one identical data set (the data is the + control variable, so only the design differs); the handover closes with a fillable + direction/steal/skip/next-target reply template (what the mockup's copy-out terminator lifts); + and the capture step records steal/skip decisions per named piece so grafts compose across + variants. Adopted from the "Finding Your Unknowns" corpus at the integration sign-off (D20, + D21, D22; provenance in `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository). Evals + extended. +- **`pressure-test`: validation answer set and a fake-data disclosure footer on the HTML demo + shell.** The demo page carries the questions it exists to answer as forced choices whose + options each name their cost (plus a free-text escape hatch), with a copy-out control, and a + visible footer stating the page is synthetic end to end and, when decided, where real wiring + lives and behind which flag; when integration is not yet decided, or no flag is planned, the + footer says so explicitly rather than inventing production details. The capture step carries + the filled answer set into the durable answer verbatim. Same adoption basis (D24, D25, D26); + evals extended. +- **Shared discipline: "mock before you wire" ordering note.** The composition table now states + that the throwaway mock runs before any real wiring when a change has both questions (D27). + ## [0.9.8] ### Added diff --git a/plugins/prototype/context/discipline.md b/plugins/prototype/context/discipline.md index 8579a124c..8af80cb5c 100644 --- a/plugins/prototype/context/discipline.md +++ b/plugins/prototype/context/discipline.md @@ -71,3 +71,8 @@ written here is gone, and the question gets re-litigated from scratch the next t | Architecture discovery surfaced a design question | `/architecture:improve` (when installed) | Improvement pass surfaces the opportunity → prototype validates the approach | | Prototype answered the question | `/planning:plan` (when installed) | Validated decision feeds the plan | | Logic module worth keeping | `/implementation:implement` (when installed) | Lift the pure module into production; delete the TUI shell | + +Ordering note — **mock before you wire**: when a change has both a "does the interaction work" +question and real integration work, run the throwaway mock (this plugin) before any wiring. A +mock that fails kills the wiring work for free; wiring first turns every design misfire into +rework of live code. diff --git a/plugins/prototype/skills/explore-directions/SKILL.md b/plugins/prototype/skills/explore-directions/SKILL.md index c103ecbb8..5546f5ef0 100644 --- a/plugins/prototype/skills/explore-directions/SKILL.md +++ b/plugins/prototype/skills/explore-directions/SKILL.md @@ -100,6 +100,10 @@ Constraints: - **Synthetic data only.** A throwaway prototype binds synthetic data, never real or captured values. +- **Same data across variants.** All variants bind one identical data set; the data is the + control variable, so the only thing that differs between variants is the design. On the real + stack, sub-shape A's shared fetching above the switcher already enforces this; on the mockup + substrate, define the synthetic set once and have every variant render it. - **No remote fetch by construction.** Vendor everything inline so the page opens straight from `file://`. No external scripts, fonts, or data fetches. Enforce this rather than trusting it: emit a restrictive CSP meta tag in the page `` so the browser blocks any remote resource: @@ -213,14 +217,27 @@ Requirements: ### 5. Hand it over Surface the URL and variant keys. Interesting feedback is usually "I want the header from B with -the sidebar from C". That's the actual design discovered. +the sidebar from C". That's the actual design discovered. Close the handover with a +machine-legible reply template the user fills, so their reaction comes back as the next prompt +rather than prose to re-parse (on the mockup substrate this is what the copy-out terminator +lifts): + +```text +direction: +steal: from (repeat per piece) +skip: because +next-target: +``` ### 6. Capture the answer and clean up Per the shared discipline. Record which variant won and why, and record the directions that lost -with their reasons. When the verdict is a graft rather than a single winner, say which piece came -from where **and what the discarded parts held that the graft deliberately left behind**. The -deletions below are irreversible: whatever is not written down now is gone. +with their reasons. Capture at single-decision granularity: each named piece (a header, a +hierarchy choice, a primary affordance) gets its own steal/skip/adapt entry, so grafts compose +across variants instead of collapsing into one "variant B, mostly" note. When the verdict is a +graft rather than a single winner, say which piece came from where **and what the discarded parts +held that the graft deliberately left behind**. The deletions below are irreversible: whatever is +not written down now is gone. - **Sub-shape A**. Delete losing variants and the switcher; fold the winner into the existing page. - **Sub-shape B**. Promote the winner to a real route; delete the throwaway route and switcher. diff --git a/plugins/prototype/skills/explore-directions/evals/evals.json b/plugins/prototype/skills/explore-directions/evals/evals.json index 4955a9430..5e5c81aa3 100644 --- a/plugins/prototype/skills/explore-directions/evals/evals.json +++ b/plugins/prototype/skills/explore-directions/evals/evals.json @@ -32,7 +32,9 @@ "files": [], "expectations": [ "The generated variants differ structurally (layout / information hierarchy / primary affordance), not only in color or copy", - "The response declines to make recolors the only difference between variants, while still letting each variant carry its own visual direction on top of its structure" + "The response declines to make recolors the only difference between variants, while still letting each variant carry its own visual direction on top of its structure", + "The handover closes with a machine-legible reply template (direction / steal / skip / next-target) for the user to fill", + "The capture records steal/skip decisions at single-decision granularity (per named piece), so grafts compose across variants" ] }, { @@ -54,6 +56,7 @@ "files": [], "expectations": [ "The mockup is a single self-contained `file://` HTML page using synthetic data only (no real/captured values)", + "All variants render one identical data set: the data is the control variable, so only the design differs between variants", "The page includes a restrictive CSP meta tag that blocks remote scripts/fonts/fetches", "The mockup file is generated into a temp or gitignored scratch location, not a tracked repo path" ] diff --git a/plugins/prototype/skills/pressure-test/SKILL.md b/plugins/prototype/skills/pressure-test/SKILL.md index 96f64d769..7bd78be53 100644 --- a/plugins/prototype/skills/pressure-test/SKILL.md +++ b/plugins/prototype/skills/pressure-test/SKILL.md @@ -73,6 +73,17 @@ business, not the reducer, because the driver is not reading code: case, an attempt at something that should be illegal. Each is a short plain-language description plus the ordered buttons to press; starting a walkthrough **resets to a known initial state** so the scenario runs the same way every time. +5. **Validation answer set**, the questions this demo exists to answer, each as a forced choice + with a small authored option set, every option naming its cost in plain language (what + picking it gives up), plus a free-text escape hatch for the answer the options missed. The + driver's picks are the demo's real output; pair the set with a copy-out control that lifts + the filled answers back out as text to paste into the session. +6. **Fake-data disclosure footer**, one visible line stating the page is synthetic end to end, + that nothing on it reads from or writes to the real app, and, when decided, where the real + wiring lives (or will live) and behind which flag; when integration is not yet decided, or no + flag is planned, the footer says so explicitly rather than inventing production details. The + driver is not reading code; the footer is what keeps a convincing mock from being mistaken + for the wired feature. Constraints (the same set as explore-directions' HTML mockup substrate): @@ -172,9 +183,11 @@ Prototypes evolve. ### 7. Capture the answer -When done, capture what the prototype taught (per the shared discipline). The logic module behind -the shell is often worth keeping; the shell, TUI or HTML page, is not: lift the validated -module into production and delete the shell. +When done, capture what the prototype taught (per the shared discipline). For the HTML demo +shell, carry the filled validation answer set into the durable answer verbatim: the chosen +option per question, with the cost the driver accepted, is the record of what was actually +decided. The logic module behind the shell is often worth keeping; the shell, TUI or HTML page, +is not: lift the validated module into production and delete the shell. ## Anti-patterns diff --git a/plugins/prototype/skills/pressure-test/evals/evals.json b/plugins/prototype/skills/pressure-test/evals/evals.json index 8a44ec4b7..0d53269be 100644 --- a/plugins/prototype/skills/pressure-test/evals/evals.json +++ b/plugins/prototype/skills/pressure-test/evals/evals.json @@ -11,7 +11,8 @@ "The prototype records the question being tested at the top of the file before building anything", "The scheduling logic lives in a pure module (e.g. a reducer or explicit state machine) separate from the TUI shell", "The TUI re-renders the whole frame on each action (replace, not append) and lists available actions", - "The prototype is runnable via a single command — wired into the project's existing task runner, or documented at the top of a prototype README when the project has no task runner" + "The prototype is runnable via a single command — wired into the project's existing task runner, or documented at the top of a prototype README when the project has no task runner", + "When the HTML demo shell is the substrate, the page carries a validation answer set (forced-choice questions whose options each name their cost, plus a free-text escape hatch) and a visible fake-data disclosure footer, and the capture step carries the filled answer set into the durable answer" ] }, { diff --git a/plugins/session-flow/.claude-plugin/plugin.json b/plugins/session-flow/.claude-plugin/plugin.json index c2c1d965f..1ce87ca8f 100644 --- a/plugins/session-flow/.claude-plugin/plugin.json +++ b/plugins/session-flow/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "session-flow", - "version": "0.34.15", + "version": "0.34.16", "description": "Session-lifecycle toolkit of fourteen skills: workflow (navigate a staged dev workflow and suggest the next stage), handoff (write a save-point and resume prompt for /clear-and-resume), continue-in-background (delegate the task to a fresh background agent that continues it now \u2014 same save-point engine as handoff, delivered by launching a detached claude --bg session seeded with the resume prompt; launches only on explicit user request), keep-going (recover and continue after any interruption OR when live off-thread work looks stalled \u2014 inventory off-thread work, inspect its real output, act only on evidence, then continue; after a usage limit lifts it continues rather than summarizing-and-stalling), find-handoff (recover a lost handoff after /clear \u2014 when the resume prompt was written but never copied \u2014 via a read-only detection ladder: known-location glob of the handoffs dir, then a bounded, recency-ranked transcript scan for the handoff directive and dashed-rail markers, then a confirm-before-resume gate; surfaces only the resume prompt + metadata, never raw transcript content), clean-stop (get to a durable, linked stopping point before the machine may go away \u2014 sweep every repo/worktree for uncommitted, unpushed, or PR-less work, push it durable, put breadcrumbs in PR/issue bodies, then give a free-and-clear verdict), retro (structured end-of-session retrospective with transcript metrics and learning codification), running-retro (in-flight retrospective checkpoints that spawn a subagent to analyze the transcript so far and append classified findings to a cumulative running ledger \u2014 capture and route only, the live counterpart to retro; also owns a detached-observer substrate that can watch a session out-of-band and run the checkpoint autonomously after the session ends), orient (read-only session orientation \u2014 synthesize where we stand, what we are doing, and why, from durable + off-thread state the built-in /recap never sees: ledgers, handoffs, workflow checklists, running-retro ledgers, open PRs and work-items, and git), orchestrate (arm a session or worker with proactive-orchestration imperatives), reanchor (verify a session's working assumptions are still true against live reality \u2014 referenced PRs/issues/branches, base-branch drift, renamed/version-drifted surfaces, stale memory-tier files, and the goal a handoff records, compared across the chain so a re-derived goal reports as drift \u2014 before building on them), reconcile (retire finished off-thread work and reconcile this session's task ledger with reality \u2014 the prune-and-reconcile counterpart to keep-going's resume: inventory the work this session spawned, inspect its real state, retire the finished and close proven-done tasks, auto-settling the finished and gating any kill of still-running work; sibling sessions in the project are reported read-only), setup (check-centric verification of the observer's runtime prerequisites and configuration), and show-options (lay out which skills fit this moment as a ranked, nothing-hidden menu \u2014 a shortlist per bucket plus the complete remainder by name, resolved from the full installed catalog rather than the truncated in-context listing, so the human decides and no option is withheld for looking already-done).", "author": { "name": "Melodic Software", diff --git a/plugins/session-flow/CHANGELOG.md b/plugins/session-flow/CHANGELOG.md index cbd528129..de3a1a81f 100644 --- a/plugins/session-flow/CHANGELOG.md +++ b/plugins/session-flow/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog — session-flow plugin +## [0.34.16] + +### Added + +- **`workflow`: five-pass pre-implementation cross-ref.** One doc line under the at-a-glance + diagram noting that stages 0-3 expand, for unfamiliar territory, into the known five-pass + order (blindspot → brainstorm/prototype → interview → reference port → plan), stated with + rationale in `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository. Recorded at the + finding-your-unknowns integration sign-off (Q7); no contract or trigger change, so no eval + delta. + ## [0.34.15] ### Changed diff --git a/plugins/session-flow/skills/workflow/SKILL.md b/plugins/session-flow/skills/workflow/SKILL.md index 0bf20f571..d6643398a 100644 --- a/plugins/session-flow/skills/workflow/SKILL.md +++ b/plugins/session-flow/skills/workflow/SKILL.md @@ -80,6 +80,10 @@ Parse the first argument to determine mode; when it is `continue`, parse the sec PR lifecycle: prep → create → monitor CI → merge (runs after step 7) ``` +Stages 0-3 expand, for unfamiliar territory, into a known five-pass pre-implementation order +(blindspot → brainstorm/prototype → interview → reference port → plan); the workflow section of +`docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository states it with rationale. + ### 2. Detect current position Check conversation context for evidence of completed stages: diff --git a/plugins/verification/.claude-plugin/plugin.json b/plugins/verification/.claude-plugin/plugin.json index 14caa0ebd..2fca01741 100644 --- a/plugins/verification/.claude-plugin/plugin.json +++ b/plugins/verification/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "verification", - "version": "0.5.11", + "version": "0.6.0", "description": "Outcome-verification stage: prove a change achieved its intended outcome (`/verification:confirm` — a mechanical build/test/lint prerequisite gate, then intent-match + evidence + verdict with the criterion auto-detected by change type), and verify measurable-improvement claims against a planning-time baseline (`/verification:measure`), never fabricating numbers.", "author": { "name": "Melodic Software", diff --git a/plugins/verification/CHANGELOG.md b/plugins/verification/CHANGELOG.md index e53b54f98..6b4606939 100644 --- a/plugins/verification/CHANGELOG.md +++ b/plugins/verification/CHANGELOG.md @@ -3,6 +3,19 @@ All notable changes to the `verification` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.6.0] + +### Added + +- **`confirm`: out-of-diff couplings get their own report table.** Stage 2's intent match now + names the existing behavior the change leans on: unchanged code whose contract the diff depends + on, carried in the outcome report as a dedicated table (coupling, where it lives, evidence it + still holds). A named coupling is checkable; an implied one is where regressions hide. The + PR-prep edge case also records that a comprehension layer (`education:quiz-me`, when installed) + may precede the gate while the merge gate itself stays here. Adopted from the "Finding Your + Unknowns" corpus at the integration sign-off (D19, D18; provenance in + `docs/FINDING-YOUR-UNKNOWNS.md` in the marketplace repository). Evals extended. + ## [0.5.11] ### Changed diff --git a/plugins/verification/skills/confirm/SKILL.md b/plugins/verification/skills/confirm/SKILL.md index c83b4e825..730c7cdd2 100644 --- a/plugins/verification/skills/confirm/SKILL.md +++ b/plugins/verification/skills/confirm/SKILL.md @@ -95,7 +95,7 @@ Read the criterion context file for the dispatched mode, then run the flow below 1. **Auto-trigger `/testing:run-e2e` (when runtime-affecting)**. Inspect changed files. If any match an `e2e-*` category from the Runtime-affecting paths above, or touch observability code paths verifiable end-to-end, or the user said "test the app", invoke `/testing:run-e2e` via the Skill tool when the `testing` plugin is installed. Otherwise drive the live app directly (Claude Code's bundled `/run`, or a manual orchestrator launch) and capture the same evidence. When present, it validates prerequisites, starts the app, exercises the changed flow, and captures evidence (screenshots, console, network, traces). Carry that into the evidence table. If not runtime-affecting (pure refactor, internal lib, doc-only): note "E2E not applicable" and skip. 2. **Intent retrieval**. Scan the conversation for the original request, the approved plan, refinements, and acceptance criteria. If none is clear, ask the user what the goal was. 3. **Implementation inventory**. Changed files, new capabilities, behavior changes, config/infra changes. -4. **Intent match**. Every requirement has implementation; every implementation traces to a requirement; flag scope additions and gaps (including implicit requirements. Error handling, edge cases, tests). +4. **Intent match**. Every requirement has implementation; every implementation traces to a requirement; flag scope additions and gaps (including implicit requirements. Error handling, edge cases, tests). Name the out-of-diff couplings: the existing behavior this change leans on, unchanged code whose contract the diff now depends on. A named coupling is checkable; an implied one is where regressions hide. The report carries them as their own table (see [context/outcome.md](context/outcome.md)). 5. **Evidence collection**. Stage-1 results, E2E results, test names + assertions proving the claimed behavior. For UI changes: the UI evidence artifacts per [context/outcome.md](context/outcome.md) (pre/action/post snapshot, console, network, behavior assertion. "screenshot looks fine" is NOT an assertion). When the plan states a measurable goal: the `/verification:measure` comparison table. 6. **Report + verdict**. Emit the outcome report (intent-match table, mechanical results, E2E + UI-evidence tables when triggered, evidence table, measurements when applicable) and a `CONFIRMED` / `NEEDS WORK` verdict. Report template and verdict criteria in [context/outcome.md](context/outcome.md). @@ -116,7 +116,7 @@ For "run the live app and watch it behave," beyond automated `/testing:run-e2e`, - **No git changes but user runs `/verification:confirm all`**: run Stage 1 across all ecosystems anyway (useful after a rebase or pull), then outcome verification if intent is in scope. - **Changed file outside any known ecosystem**: Stage 1 skips it with a note; Stage 2 still assesses intent match. - **Missing tools**: `/toolchain:check` / `/toolchain:lint` report `skip` with install hint, not failure. Except the core toolchain the project's own code requires. -- **Invoked from a PR-prep flow**: treat the verdict as a hard gate. Any FAIL or unresolved CRITICAL gap blocks PR creation. +- **Invoked from a PR-prep flow**: treat the verdict as a hard gate. Any FAIL or unresolved CRITICAL gap blocks PR creation. A comprehension layer (an `education:quiz-me` report, when that plugin is installed) may precede this gate and inform it; the merge gate itself lives here, one mechanism per concern. ## Skill chaining diff --git a/plugins/verification/skills/confirm/context/outcome.md b/plugins/verification/skills/confirm/context/outcome.md index fcd94d8f5..c4a3b7fdd 100644 --- a/plugins/verification/skills/confirm/context/outcome.md +++ b/plugins/verification/skills/confirm/context/outcome.md @@ -53,6 +53,11 @@ Justified additions are fine but should be noted. Unjustified additions should b |---|----------|-----------|-----------| | 1 | | Yes/No | | +### Existing behavior this leans on (out-of-diff couplings) +| # | Coupling | Where it lives | Evidence it still holds | +|---|----------|----------------|-------------------------| +| 1 | | | | + ### Assessment - Plan items: X/Y complete (Z%) - Deviations: N (all justified / N unjustified) diff --git a/plugins/verification/skills/confirm/evals/evals.json b/plugins/verification/skills/confirm/evals/evals.json index 92761bf42..3b68fb636 100644 --- a/plugins/verification/skills/confirm/evals/evals.json +++ b/plugins/verification/skills/confirm/evals/evals.json @@ -11,6 +11,7 @@ "Auto-detects the `outcome` criterion from the post-implementation context (no mode argument given)", "Stage 1 delegates to /toolchain:check and /toolchain:lint cross-cutting — does NOT reimplement build/test/lint or inline exec-bit/gitleaks bash", "Stage 2 retrieves intent (plan / conversation) and produces an intent-match table", + "The report names the out-of-diff couplings as their own table: existing behavior the change leans on, where it lives, and evidence it still holds", "Emits a CONFIRMED or NEEDS WORK verdict, not just a green build" ] },