pi-feature-dev 1.13.0 → 1.15.0

package/README.md

@@ -14,6 +14,11 @@ feature work:
 
 It does not require specific task-tracking, question, delegation, or review tools. If the current environment provides equivalent capabilities, use them; otherwise follow the same workflow directly in chat and with normal code tools.
 
+The `deslop` skill audits or applies evidence-backed subtractive cleanup for
+accumulated test bloat, circular verification, and defensive or fallback
+machinery. Audit mode is read-only. Only an explicit `apply` request authorizes
+edits.
+
 The `plan-exec` skill executes implementation plan files task by task with
 isolated workers, Git task commits, internal reviews, finalize, and a portable
 run summary. It is portable across host agents that provide fresh-context
@@ -42,10 +47,15 @@ into concrete work without losing the creator's taste, feeling, or human focus.
 It applies to creative technical and everyday work, while staying out of
 factual, mechanical, exact, or fully specified tasks.
 
+The `prototype` skill builds disposable logic or UI experiments that answer one
+design question before production implementation. It follows the current
+project and adapts its handoff, preview, task, and source-control steps to the
+capabilities of the current agent environment.
+
 The `visual-recap` skill turns a plan or completed non-trivial change into an
 evidence-backed visual review aid. It helps a reviewer see the outcome, affected
 system parts, risk, and the best place to inspect first. It adapts to the current
-host agent and always keeps a portable inline fallback.
+host agent, uses Mermaid for portable diagrams, and keeps an inline fallback.
 
 ## Install
 
@@ -89,6 +99,8 @@ from:
 - [umputun/cc-thingz](https://github.com/umputun/cc-thingz)
 - [anthropics/claude-code feature-dev plugin](https://github.com/anthropics/claude-code/tree/main/plugins/feature-dev)
 - [mattpocock/skills batch-grill-me and domain-modeling skills](https://github.com/mattpocock/skills)
+- [mattpocock/skills prototype](https://github.com/mattpocock/skills/tree/main/skills/engineering/prototype)
+- [MrZoyo/deslop-GPT](https://github.com/MrZoyo/deslop-GPT/tree/main/skills/deslop)
 - [danyuchn/asd-ste100-skill](https://github.com/danyuchn/asd-ste100-skill)
 - [AminBlg/SimpleEnglish](https://github.com/AminBlg/SimpleEnglish/tree/main/skills/simple-english)
 - [ayghri/i-have-adhd](https://github.com/ayghri/i-have-adhd)
@@ -109,6 +121,12 @@ Natural language also works when Pi's skill matcher triggers:
 Use feature-dev to implement API rate limiting.
 ```
 
+Audit accumulated complexity without editing files:
+
+```text
+/skill:deslop audit the current branch for test, verification, and fallback bloat.
+```
+
 Carry an incomplete creative brief into the work itself:
 
 ```text
@@ -121,6 +139,12 @@ Create a visual review aid for a plan or completed change:
 /skill:visual-recap Show the architecture impact of the current change.
 ```
 
+Build a disposable prototype to answer one design question:
+
+```text
+/skill:prototype Compare three structurally different settings-page layouts.
+```
+
 The files under `skills/*/SKILL.md` are portable Markdown and can be adapted for
 other agent environments.
 
@@ -200,6 +224,11 @@ pi-feature-dev/
     ├── creator-vibe/
     │   ├── agents/openai.yaml
     │   └── SKILL.md
+    ├── deslop/
+    │   ├── agents/openai.yaml
+    │   ├── references/
+    │   ├── LICENSE.txt
+    │   └── SKILL.md
     ├── feature-dev/
     │   ├── agents/openai.yaml
     │   └── SKILL.md
@@ -225,6 +254,11 @@ pi-feature-dev/
     ├── plan-review/
     │   ├── agents/openai.yaml
     │   └── SKILL.md
+    ├── prototype/
+    │   ├── agents/openai.yaml
+    │   ├── LOGIC.md
+    │   ├── UI.md
+    │   └── SKILL.md
     ├── ste/
     │   ├── agents/openai.yaml
     │   ├── references/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-feature-dev",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "Portable coding-agent workflows packaged as skills.",
   "license": "MIT",
   "type": "module",

package/skills/deslop/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: deslop
+description: Audit or apply evidence-backed, test-first subtractive cleanup for accumulated agent-created test bloat, verification theater, and defensive or fallback bloat while preserving independent external behavior. Invoke explicitly for semantic simplification, not generic refactoring.
+---
+
+# Deslop
+
+Deslop removes complexity accumulated during repeated coding-agent implementation and correction cycles. It is a semantic cleanup policy, not a beautifier, dead-code sweeper, generic refactoring tool, or redesign assistant.
+
+## Priority order
+
+Work in this order. Do not let an easy dead-code deletion displace a higher-priority cluster.
+
+1. **Test-suite bloat.** Treat tests as production code that can accumulate after every agent correction. Remove duplicate, self-referential, implementation-detail, and obsolete tests while retaining a minimum sufficient set of independent behavioral evidence.
+2. **Verification theater.** Investigate checksums, receipts, manifests, validators, recomputation, and result envelopes whose producer and verifier share the same information and failure domain.
+3. **Defensive and fallback bloat.** Investigate broad catches, catch-and-fallback paths, speculative compatibility branches, repeated validation, and recovery machinery that masks errors without a current contract.
+
+Generic dead code, wrappers, abstractions, comments, and ordinary duplication are secondary. Touch them only when they belong to one of the three target clusters or have direct high-confidence evidence.
+
+**Reduce test surface, not behavior surface.** Evidence that a test is redundant or accumulated test-suite bloat justifies deleting or consolidating that test; it is not independent evidence for changing the production behavior the test exercises. When test-suite bloat is the active target, keep distinct externally observable production semantics—including public success, rejection, error, edge-case, and supported compatibility behavior—outside the deletion target unless the production construct is separately justified for removal by another target cluster, or direct evidence from current requirements, real callers, specifications, or history establishes that the behavior is obsolete or incorrect. Do not reclassify tested behavior as defensive or validation bloat merely because deleting its test leaves nothing else requiring it; the test may be its clearest executable specification.
+
+Adding tests is not the default response to cleanup. When production slop is deleted, tests whose only purpose is to protect that slop should normally be deleted in the same change.
+
+## Test-first evidence pass
+
+When tests are in scope, complete this pass before changing production behavior:
+
+1. Inventory collected test nodes plus their fixtures, fakes, helper stacks, generated inputs, output targets, skips, and deselection rules.
+2. Map each test to `current owner -> production branch -> observable result -> independent oracle -> failure domain`.
+3. Group tests by failure domain. Consolidate inputs that reach the same branch and result; preserve separate rejection, safety, persistence, protocol, resource, and numerical semantics.
+4. Choose the strongest surviving evidence root for each group: a public seam where possible, an independently specified low-level invariant where necessary, and one hermetic cross-layer root for each current delivery path.
+5. Remove fixtures and test-only support with the tests they serve. Remove production code in that cluster only when separate caller, contract, history, and reachability evidence also justify it.
+6. Re-collect and run the remaining suite. Record skips and deselections, and compare worktree state before and after tests that may generate files.
+
+Do not use coverage, test count, or a test-created configuration as an owner. The output of this pass is a smaller evidence set with the same real failure domains, not a target number of tests.
+
+### Test decision contrast
+
+- **HIGH cleanup:** several tests reach the same public success branch; one asserts the exact externally visible result while the others only repeat construction, type, or non-empty checks. Keep the strongest behavioral root and remove the dominated tests plus support used only by them.
+- **PRESERVE:** one test covers successful output and another covers externally visible rejection, safety, persistence, or supported compatibility behavior. They protect different results or failure domains; do not merge or delete one merely to reduce the count.
+
+## Closed justification loops
+
+Production code does not justify a test merely because the test exercises it. A test does not justify production code merely because the production code exists. Follow justification chains outward until they reach an independent evidence root.
+
+A production/test pair is mutual-support slop only when the production construct has no independently meaningful externally observable purpose. A test of a distinct externally observable rejection, error, or supported compatibility behavior is not a closed justification loop merely because the test is its clearest executable specification. Internal checksum or receipt machinery and tests created only for that machinery can form such a loop, as can a speculative fallback and tests created only to exercise it.
+
+If a fallback exists only because a test exercises it, and that test exists only because the fallback was added, neither member is independent evidence. The same closed justification loop can include checksum logic and checksum tests, receipts/manifests and validators, wrappers and wrapper-only tests, obsolete compatibility branches and their tests, or defensive validators and tests that only exercise them. Call this **mutual-support slop**.
+
+Accept a dependency cluster only when its chain reaches a current user requirement, real external caller, public API contract, documented protocol or specification, security/trust boundary, persistence or corruption boundary, or scientific/numerical invariant. If the cluster only justifies itself, prefer deleting the whole cluster rather than preserving each member because another member depends on it.
+
+A closed loop is a finding about evidence that is present, not evidence that is absent. Failing to find a caller, configuration, document, or history inside a small or isolated scope is missing evidence: it caps the finding at MEDIUM and does not make the cluster unreachable or HIGH. A compatibility branch with its own first-class positive test or current documentation explicitly naming it as supported behavior is a preservation root; removing that behavior requires positive evidence that the compatibility promise has ended. A branch reached only through a broad catch, with no test or document of its own, is not such a root.
+
+Trace edges as well as nodes. Separately tested producers, readers, and consumers do not prove that a current production path connects them. Before removing a fixture, validator, registry entry, or wrapper that crosses layers, identify the current producer -> reader -> consumer path and preserve one hermetic integration root when that path carries real behavior.
+
+## Modes and authorization
+
+Interpret invocation from natural language; do not depend on a runtime-specific arguments variable.
+
+- **Default or `audit`:** read-only. Report candidates, evidence, confidence, closed loops, and constructs to preserve. Do not intentionally modify repository-owned content; disable or redirect tool caches and generated outputs when practical.
+- **`apply`:** modify files only within the established scope.
+- **`tests`:** prioritize test signal and mutual-support slop. Without `apply`, remain read-only.
+- **`deep`:** inspect repository-wide. Without `apply`, remain read-only; with `apply`, cleanup is allowed but redesign is not.
+- **Explicit paths:** inspect and edit those paths plus the minimum callers, contracts, and tests needed to establish independence.
+- **Current branch or no scope inside Git:** use the actual merge base and include staged, unstaged, and untracked work; never assume `main`.
+
+Only `apply` authorizes edits. Do not fetch, reset, switch branches, stage, commit, push, or create backups unless explicitly requested.
+
+## Establish evidence before editing
+
+1. Read the active host's applicable project-instruction files, such as `AGENTS.md` or `CLAUDE.md`, plus repository conventions and the requested scope.
+2. Inspect callers, tests, history, specifications, current configuration, registries, public readers, and documented verification commands.
+3. Classify the evidence chain before trusting an existing test or fallback.
+4. Put explicit current requirements first. A requirement or correction stated in the current task, or recorded in a current authoritative project document, overrides conflicting historical tests. Do not promote an inferred preference or the cleanup objective itself into a requirement.
+5. A bug fix should normally replace incorrect behavior, not preserve it behind a fallback.
+
+Prove reachability from a non-test producer such as an active config, external request, public CLI, persisted record, or hardware/runtime selection. A test-injected flag, synthetic future config, diagnostic command, or scripted dry-run does not by itself own a production branch.
+
+Inside trusted code, use a **fail-visible bias**: allow unexpected failures to surface unless there is a concrete recovery, translation, cleanup, protocol, or compatibility contract. Broad `except Exception`, catch-and-fallback, catch-log-rethrow, speculative legacy fallbacks, and compatibility branches without independent evidence are high-priority investigation targets. Do not hide bugs in the name of robustness.
+
+## Confidence and apply behavior
+
+- **HIGH:** redundant, tautological, unreachable, self-justifying, or disconnected from a real contract after the evidence chain is resolved.
+- **MEDIUM:** apparently unnecessary, but caller, history, compatibility, or boundary evidence is still missing.
+- **LOW / PRESERVE BY DEFAULT:** security, authorization, concurrency, persistence, transactions, external protocols, supported compatibility, resource limits, and scientific invariants whose purpose may be outside the local file.
+
+In apply mode:
+
+- HIGH: delete or simplify once the evidence is resolved.
+- MEDIUM: do not modify until the missing evidence question is resolved.
+- LOW: preserve unless direct contrary evidence is established.
+
+Apply authorization is permission to edit, not permission to resolve uncertainty in favor of deletion.
+
+Read only the relevant references:
+
+- [test-smells.md](references/test-smells.md) for accumulated test suites and test/production mutual-support clusters.
+- [verification-and-trust.md](references/verification-and-trust.md) for checksum, receipt, manifest, provenance, and trust-boundary clusters.
+- [code-smells.md](references/code-smells.md) for defensive, fallback, compatibility, wrapper, and abstraction candidates.
+- [scientific-code.md](references/scientific-code.md) for numerical, simulation, ML, or engineering invariants.
+- [evidence-and-reachability.md](references/evidence-and-reachability.md) when cleanup touches cross-layer fixtures, generated artifacts, active configuration, schema readers, registries/CLIs, or test hermeticity.
+
+## Subtractive workflow
+
+1. Complete the test-first evidence pass before production cleanup when tests are in scope.
+2. Trace verification machinery as a cluster, not a function. Remove serialization, digest fields, envelopes, manifests, validators, recomputation, and tests together when no independent root remains.
+3. Trace fallback branches to actual supported consumers and failure contracts. Prefer direct failure when the current contract says an operation should fail.
+4. Delete tests that exist only to keep deleted production slop green. Add a replacement test only when deleting the old test would leave a real external behavior unprotected and an independent oracle exists.
+5. Preserve real public, persistence, security, protocol, compatibility, resource, and scientific boundaries even when their code resembles a smell.
+6. Treat declared authoritative inputs as required unless the protocol explicitly marks them optional. Missing and invalid authoritative artifacts should share the same visible failure semantics.
+7. For a schema or identity change, enumerate every public reader, including CLIs, tools, visualizers, converters, and resume paths. Do not infer compatibility from a missing field or file.
+8. Keep permanent tests hermetic: use repository-managed or test-created inputs, write to temporary outputs, and skip only when the test actually crosses the optional dependency boundary.
+
+## Negative-change budget
+
+Normally reduce structural surface area. New dependencies, abstractions, wrappers, compatibility layers, cryptographic/provenance machinery, and tests have a default budget of zero. New code is acceptable only when it preserves a real behavior while removing more accumulated slop. A small current-path integration root or a direct required-input check can be justified when cleanup exposes a real protection gap. If a cleanup adds substantial production or test lines, stop and reconsider.
+
+In `deep apply`, exclude generated code, vendored dependencies, `third_party` trees, migration history, lockfiles, and externally generated snapshots or artifacts unless explicitly included or demonstrably repository-owned.
+
+## Proportional verification
+
+Run the narrowest existing checks after each meaningful semantic group and the repository's documented final checks once when feasible. Compare test collection before and after; zero surviving tests is a failure, and unexpected skips or deselections require explanation. When tests can generate files, compare the worktree before and after the suite so a green run cannot hide writes to tracked outputs. In read-only modes, use no-write options or temporary locations for caches and generated output when available, and report any incidental tool artifacts left behind. Verification should be independent of the change where possible. Do not create proof files, audit ledgers, checksum reports, or a new verification framework merely to validate a deletion. If a check cannot run without changing repository-owned content, do not run it in audit mode; state that plainly.
+
+## Final report
+
+Report the inspected scope; removed test, verification, and fallback clusters; independent evidence roots; preserved boundaries; tests removed or consolidated; before/after collection plus skips or deselections when available; checks actually run; approximate production/test size changes when useful; and uncertainty intentionally left untouched. Explicitly call out any closed justification loop that drove deletion.

package/skills/deslop/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Deslop"
+  short_description: "Audit accumulated test, verification, and fallback bloat"
+  default_prompt: "Use $deslop to audit accumulated test bloat, verification theater, and defensive/fallback machinery before applying a subtractive cleanup."
+
+policy:
+  allow_implicit_invocation: false

package/skills/deslop/references/code-smells.md

@@ -0,0 +1,80 @@
+# Code Smells
+
+Use this checklist for production code after test bloat and verification clusters have been inspected. A smell identifies where to investigate; caller, correction, and contract evidence decide whether to delete. Generic dead code and ordinary duplication are secondary unless they belong to a focused cluster.
+
+| Smell | Signal | Evidence needed | Common false positives | Preferred simplification |
+| --- | --- | --- | --- | --- |
+| Repeated validation | `None`, type, enum, shape, or schema checks repeat after parsing | Trace the true input boundary and all direct callers | Independently callable API, mutation, persisted reload, distinct invariant | Validate once at the boundary |
+| Phantom exception handling | Broad catches, catch/log/rethrow, impossible caught exception | Enumerate exceptions the operation can raise and required recovery | Cleanup, stable exception translation, documented retry policy | Remove the handler or narrow it to real recovery |
+| Fallback proliferation | Default, legacy, and “safe” paths for states callers cannot produce | Trace configuration, supported environments, and selection paths | Availability requirements, rollout, heterogeneous deployments | Keep the required path and expose invalid state normally |
+| Pass-through wrapper | Function only forwards arguments or renames a readable call | Confirm it adds no policy, lifecycle, stable seam, or representation change | Public facade, transaction boundary, instrumentation | Call the underlying operation directly |
+| Wrapper tower | Adapter-to-adapter or DTO-to-equivalent-DTO chains | Follow data end to end and identify actual boundaries | Protocol translation, generated API surface | Collapse the chain at the nearest real boundary |
+| Single-use helper | One private caller and a short obvious body | Check dynamic registration and whether the name encodes domain knowledge | Callback, recursion, framework hook, meaningful algorithm | Inline and delete helper-only tests |
+| One-implementation abstraction | Interface, factory, strategy, registry, provider, or service with one real implementation | Inspect construction sites and supported extension commitments | External plugins, platform variants, real test seam | Use the concrete behavior directly |
+| Premature utility | Generic helper unifies similar syntax through flags or callbacks | Decide whether callers share domain knowledge or only appearance | One authoritative business or protocol rule | Keep obvious local operations local |
+| Repeated canonicalization | Normalizers run throughout one trusted call graph | Identify first non-canonical input and the consumer requiring canonical form | Signing format, Unicode rule, cache key, equality identity | Canonicalize once at the representation boundary |
+| “Safe” wrapper type | `Validated`, `Canonical`, `Trusted`, or `Safe` type without a trust transition | Locate the representation or authority change it models | Capability type, protocol state, validated external input | Pass the ordinary typed value internally |
+| Redundant copy or freeze | Each layer copies or freezes values without a mutation path | Trace aliases, ownership, concurrency, and external mutation | Views, caches, concurrency, API isolation promise | Keep one clear ownership boundary |
+| Duplicate implementation | Near-identical functions or adapters accumulated across patches | Compare semantics, callers, failure modes, and ownership | Similar code with independent domain evolution | Delete the obsolete copy or use the existing direct path |
+| Dead branch or stale flag | No call sites, impossible branch, fixed flag, overwritten value | Check reflection, registration, exports, config, and supported variants | Framework hooks, serialized names, CLI entry points | Delete the branch and its plumbing |
+| Test-created reachability | A test mutates a gate, injects a future config, or calls a post-gate helper directly | Find an active config, request, persisted value, or runtime selector that reaches it | Current platform variants or staged rollouts with an owned work package | Delete the unreachable branch and its dedicated test |
+| Compatibility residue | Alias, shim, or historical fallback has no supported consumer | Check support policy, releases, public API, and history | Third-party consumers, rolling upgrades, stored data | Delete only with affirmative end-of-support evidence |
+| Product-surface loop | Registry entry, CLI command, diagnostic module, config, and tests only reference one another | Exclude the same cluster and locate a real caller, operator workflow, or external protocol | A documented and currently used public command | Delete the full inactive entry path, not one wrapper |
+| Implicit schema default | Dataclass or parser defaults a missing identity/path/count to a historical value | Check current producers and stored-data support commitments | Truly optional presentation or enrichment fields | Make current identity explicit and fail on omission |
+| Stale current documentation | PLAN, STATUS, architecture, or workflow text still promises a removed fallback or lists a completed fix as pending | Compare current callers/configs with authoritative documents | Clearly labeled history, migration guidance, or future proposals | Update the current claim while preserving labeled history |
+| Comment noise | Text narrates syntax, types, or generic intent | Ask whether it contributes information not present in clear code | External constraint, workaround, invariant, tradeoff | Delete restatement; preserve concise “why” |
+| Type workaround drift | Cast chains, ignores, and runtime probes conflict with surrounding conventions | Confirm current type contract and toolchain behavior | Broken third-party stubs, version-gated API | Express the real type directly and remove stale workarounds |
+| Inferred transformation | Date, filename, project ID, or incidental metadata silently selects a data transform | Find the authoritative caller choice and historical failure evidence | Versioned protocol fields with explicit semantics | Replace guessing with an explicit option and record it |
+
+## Fail-visible bias
+
+Inside trusted code, unexpected failures should normally surface. Robustness is not a license to hide programming errors. Investigate these patterns first:
+
+- broad `except Exception` around ordinary internal work;
+- catch-log-rethrow that adds no stable translation, cleanup, or attribution;
+- catch-and-fallback after a new path raises unexpectedly;
+- `try new behavior; otherwise run old behavior` without a supported version or protocol signal;
+- silent defaults after malformed or missing internal state;
+- compatibility branches with no reachable supported consumer;
+- repeated validation after a trusted boundary or after a typed representation is established;
+- defensive branches whose only evidence is tests created for those branches.
+
+For each branch, ask:
+
+1. What exact failure is recoverable?
+2. Does the current user requirement or protocol require recovery, translation, cleanup, or compatibility?
+3. Can ordinary runtime failure expose an internal bug more usefully?
+4. Is the fallback's test an independent contract, or part of a closed justification loop?
+5. What supported consumer would break if this branch disappeared?
+
+If the answer is only “be robust,” “future-proof,” or “keep old tests green,” prefer direct failure. A bug fix should replace incorrect behavior, not preserve it behind a fallback. Preserve narrow exception handling when it performs concrete cleanup, translates a stable public error, enforces a documented legacy protocol, or protects a real resource/transaction boundary.
+
+## Defensive clusters, not isolated lines
+
+Do not delete only the most visible helper while leaving its mutually supporting tests, validators, wrappers, or fallback branches. Follow the justification chain outward. If production code, a test, and a receipt/validator each exist only to justify one another, treat them as one deletion candidate. A cluster is preserved only when its chain reaches an independent user requirement, external caller, protocol, security boundary, persistence/corruption boundary, or scientific invariant.
+
+## Deletion Evidence
+
+Prefer concrete evidence such as:
+
+- no static, dynamic, exported, or registered consumer;
+- impossible state under the established typed contract;
+- value already validated at the actual boundary;
+- caught exception cannot originate in the protected operation;
+- wrapper adds no observable behavior;
+- fallback masks a programming or configuration error;
+- duplicate path has an identified authoritative replacement;
+- compatibility promise has explicitly ended;
+- value is overwritten before observation.
+
+Do not cite AI authorship as evidence.
+
+## Abstraction Check
+
+Before keeping an abstraction, ask what independent variation it contains today. “Could support another implementation later” is not enough. Before deleting one, check for external implementations, framework discovery, package commitments, platform variants, and tests that model a real seam rather than merely mock internals.
+
+Do not replace removed abstraction with a differently named abstraction. A few duplicated obvious lines can be clearer than a shared layer that forces navigation across files.
+
+A thin wrapper can still own a real boundary. Preserve one that bridges independently versioned formats, manages a temporary dataset or resource lifecycle, maintains a published import path, or translates a stable external contract. Thinness alone is not deletion evidence.
+
+For active-config reachability and cross-layer ownership, also read [evidence-and-reachability.md](evidence-and-reachability.md).

package/skills/deslop/references/evidence-and-reachability.md

@@ -0,0 +1,91 @@
+# Evidence and Reachability
+
+Cleanup decisions fail when the audit proves that individual pieces exist but never proves how current production reaches them. Use this reference when a deletion touches fixtures, generated artifacts, active configuration, readers, registries, CLIs, or documentation.
+
+## Prove ownership from production inputs
+
+Trace reachability forward from a non-test producer:
+
+```text
+active config / external request / public CLI / persisted record / runtime selection
+    -> producer
+    -> representation or boundary
+    -> reader
+    -> current consumer
+    -> observable result
+```
+
+A test can show that a branch executes; it cannot make the branch current. Synthetic flags, monkeypatched thresholds, future-only configs, diagnostic commands, and scripted dry-runs need a real work package or consumer before they own production behavior.
+
+Registries and CLIs require the same test. A registry entry, command, config, diagnostic module, and their tests can form one closed product-surface loop. Exclude that cluster while searching for a caller. If nothing remains except archives or plans, delete the active chain together.
+
+## Trace edges, not only nodes
+
+Local unit coverage can stay green after a production path breaks:
+
+```text
+producer test passes    reader test passes    state-machine test passes
+          \                 |                 /
+           no test proves the current identity crosses all three
+```
+
+Before retiring a cross-layer fixture, validator, wrapper, or package loader:
+
+1. Map each behavior carried by the old path to its current owner.
+2. Retire behavior with no current owner.
+3. Move surviving behavior to the lowest stable public seam that still crosses the real boundary.
+4. Keep one hermetic integration root for each current delivery path whose edges would otherwise be unprotected.
+
+Do not preserve an obsolete fixture merely because it once carried useful behavior. Do not delete current behavior merely because its old carrier is obsolete.
+
+## Keep permanent tests hermetic
+
+Permanent test inputs should come from the repository, explicit managed resources, or data created by the test. A default test that reads an untracked `outputs/` directory, one-off experiment package, or developer-local path is not a reliable integration root. Delete an orphan test/support cluster or redesign a self-contained test from the surviving behavior.
+
+Treat tracked assets as read-only during tests. A compiler may hide writes behind configuration, so search the resolved output path rather than only `write_text()` calls in test files. Redirect generated outputs to a temporary directory. When running the full suite, compare tracked and untracked worktree state before and after; identical generated bytes do not make overwriting user edits safe.
+
+Match skips to actual dependency boundaries. A fake-only test should not skip because an unused simulator or SDK is absent. Keep a precise skip when the test imports the SDK, compiles a real model, encodes through the optional codec, or otherwise crosses that boundary.
+
+Distinguish two kinds of dry-run:
+
+- Parsing, assembly, and validation dry-runs may prove that inputs form a valid request without claiming execution capability.
+- A script that invents observations, forces phases, or manufactures success cannot prove planner, hardware, or runtime capability. If its only owner is a permanent success test, remove both.
+
+## Close authority and schema boundaries
+
+Treat a declared authoritative dependency as required:
+
+```text
+package reference -> required artifact -> digest/schema check -> component data
+```
+
+Do not write `exists -> verify -> otherwise continue` unless absence is explicitly valid. A missing authority and a mismatched authority have the same failure meaning. Lower-level caches or sidecars cannot silently take over authority.
+
+For schema changes, search by format and field names to enumerate all readers, not only imports of the main loader. Include library APIs, CLIs, tools, visualizers, conversion jobs, resume paths, and validators. Current readers reject unsupported versions consistently; explicitly scoped migration readers may continue to accept them.
+
+For required identity, path, count, handedness, or source fields, check three layers:
+
+1. the declared type has no historical default;
+2. the parser requires the field instead of using `get(..., old_value)`;
+3. validation rejects malformed current data.
+
+Filesystem absence and missing keys do not select a legacy protocol. Compatibility requires an explicit version, producer, consumer, and retirement condition.
+
+## Treat current documentation as product surface
+
+Authoritative PLAN, STATUS, architecture, and workflow documents can keep a retired fallback alive or misstate an unfinished fix as complete. After cleanup, compare their current-path claims with callers and active configuration. Remove stale current claims while preserving clearly labeled history, migration notes, and future proposals.
+
+## Decision checklist
+
+Before applying a cross-layer deletion, answer:
+
+1. Which non-test input reaches this branch today?
+2. Which producer and consumer sit on opposite sides of the boundary?
+3. Does one test protect the current edge, or only its endpoints?
+4. Are every permanent input and output hermetic?
+5. Is each skipped dependency actually invoked?
+6. Is a missing artifact or field explicitly optional?
+7. Which public readers enforce the current schema?
+8. Do current docs and registries describe the same production path?
+
+Unanswered ownership or boundary questions are MEDIUM evidence. Resolve them before deletion.

package/skills/deslop/references/scientific-code.md

@@ -0,0 +1,70 @@
+# Scientific and Numerical Code
+
+Generic software robustness is not numerical correctness. In scientific, simulation, ML, and engineering code, preserve checks with a mathematical, physical, resource, or data-boundary reason; investigate enterprise-style hardening that has none.
+
+## Decision Criteria
+
+```text
+Does the check enforce a documented mathematical, physical, convergence,
+conditioning, tolerance, allocation, or external-data requirement?
+|
++-- Yes -> preserve it and keep the reason visible
+|
+`-- No
+    `-- Does it detect a concrete independent failure or trust transition?
+        +-- Yes -> preserve if the check can actually detect that failure
+        `-- No  -> likely generic hardening; simplify or delete
+```
+
+Prefer the ordinary path:
+
+```text
+typed caller input
+    -> direct readable numerical kernel
+    -> plain result
+```
+
+## Investigate Aggressively
+
+- cryptographic identity or tamper receipts for in-memory arrays;
+- `ResultEnvelope`, `VerifiedArray`, or canonical-array wrappers with no boundary;
+- finite-real and positive-real validation repeated at every layer;
+- generic stable-product, stable-ratio, or “safe arithmetic” frameworks added speculatively;
+- arbitrary overflow or underflow guards disconnected from the project's numerical model;
+- output-finiteness checks repeated after the responsible kernel already establishes the invariant;
+- defensive copies of every returned array without aliasing risk;
+- duplicate recomputation described as verification;
+- schema, provenance, or evidence files produced and consumed within one experiment process;
+- runtime type checks that restate typed internal APIs.
+
+Use ordinary floating-point computation when that is the project's intended model. Do not impose exact arithmetic, universal finiteness, or cryptographic integrity merely because they sound safer.
+
+## Preserve When Scientifically Meaningful
+
+- solver convergence and termination criteria;
+- physical domain constraints;
+- covariance symmetry or positive-semidefiniteness when mathematically required;
+- conditioning checks tied to algorithm validity;
+- documented numerical tolerances and error budgets;
+- known limiting cases and conservation laws;
+- required event or phase ordering when final state alone can hide an invalid trajectory;
+- explicit failure categories that preserve experiment denominators and diagnostic attribution;
+- finite-result checks where downstream mathematics specifically requires finiteness;
+- bounded allocation and resource constraints;
+- checks preventing invalid numerical algorithms;
+- validation of external datasets, models, checkpoints, and instrument files;
+- provenance consumed independently for reproducibility or audit.
+
+## Copies and Mutability
+
+Before deleting a copy, trace array ownership, views, aliases, mutation sites, caches, concurrency, and library calls that may mutate inputs. A new array is not automatically untrusted; a view into shared mutable storage can still require isolation.
+
+Before preserving immutability machinery, identify the reachable mutation that it prevents. “Results should be safe” is not enough.
+
+## Numerical Verification
+
+An analytical result, conservation law, independently derived implementation, calibrated reference dataset, or known limiting behavior can provide a real oracle. Repeating the same kernel with the same formula and inputs usually cannot.
+
+Do not remove a numerical check merely because it resembles ordinary defensive validation. State its mathematical purpose first; delete only when no such purpose or independent failure class exists.
+
+Do not collapse several scientifically distinct failures into one “result looks acceptable” assertion. A final target can be reached after an invalid event order, numerical instability, collision, limit violation, or rebound. Preserve separate checks when those outcomes change acceptance, the experiment denominator, or root-cause analysis.

package/skills/deslop/references/test-smells.md

@@ -0,0 +1,111 @@
+# Test Smells
+
+Tests are code and can be accumulated agent slop. Test signal matters more than test volume. Preserve the minimum sufficient set of tests that protects distinct externally meaningful behavior with an independent oracle.
+
+## Start with the oracle
+
+Ask where the expected result came from and what failure the test would expose.
+
+```text
+independent specification / known example / external caller / protocol fixture
+    -> meaningful behavior assertion
+
+same helper / same algorithm / implementation-generated expected value / mock setup
+    -> self-referential test: delete, consolidate, or find a real oracle
+```
+
+An independently implemented cross-check is useful only when it can fail differently. Repeating an implementation with different names is not independence.
+
+## Build an evidence map
+
+For a non-trivial suite, make the reasoning inspectable before deleting nodes:
+
+| Test or parameter group | Current owner | Production branch | Observable result | Oracle root | Failure domain | Stronger overlap |
+| --- | --- | --- | --- | --- | --- | --- |
+| one row per candidate | active config, caller, protocol, or none | actual branch reached | success, rejection, error, or state | independent source | what can fail differently | test that dominates it, if any |
+
+This can remain working notes; do not add a permanent audit artifact merely to prove cleanup. The map prevents three common errors: merging tests that have different failure semantics, retaining permutations that reach the same branch and result, and deleting production behavior merely because its only test was redundant.
+
+One test dominates another only when it protects the same owner, branch, result, and failure domain with an equally independent or stronger oracle. A public integration test does not automatically dominate a known numerical example, corruption test, or protocol rejection. Conversely, a long snapshot does not dominate a focused test merely because it asserts more fields.
+
+## High-priority accumulated patterns
+
+| Pattern | Suspicious signal | Preserve when | Preferred action |
+| --- | --- | --- | --- |
+| Duplicate behavior tests | Same input, path, and meaningful outcome with no distinct failure mode | Each test protects a separate contract or historical regression | Keep the strongest readable test |
+| Successive regression-test accumulation | A new near-identical test was added after every minor agent/user correction | Each correction protects a genuinely different externally visible bug | Collapse to the minimum distinct regression set |
+| Duplicate integration coverage | Several tests traverse the same public path and oracle | Different boundary, failure class, or supported environment is exercised | Remove redundant scenarios |
+| Parameter-permutation bloat | Values vary without changing a branch, equivalence class, invariant, or risk | The permutation represents a real boundary or failure mode | Keep representative cases |
+| Aggregate-plus-item duplicate | `all(...)`, count, or length restates stronger per-item behavior checks | The aggregate is a distinct collection-level contract | Delete the weaker assertion |
+| Weak type/None/length/existence check | Assertion is dominated by a stronger behavior assertion in the same test | Presence, type, or cardinality is itself public contract | Remove or keep only the independent contract |
+| Private-helper test | Test exists because an agent extracted a helper already covered through a public seam | Helper has a stable, independently specified algorithm | Delete with the helper or test publicly |
+| Implementation-detail test | Private state, helper call, exact temporary object, or harmless ordering is asserted | Detail is a protocol, transaction, concurrency, lifecycle, or resource contract | Assert the meaningful seam |
+| Exact call-count test | Count follows current implementation mechanics | Count controls billing, retry, batching, idempotency, or a documented limit | Assert external effect unless count is semantic |
+| Exact sequencing test | Harmless refactor breaks the expected order | Order is required by protocol, locks, transactions, or cleanup lifecycle | Keep only semantic ordering |
+| Mock-verifies-mock | Mock setup dictates output and verification repeats setup | Interaction with an unavailable boundary is the real contract | Reduce mocking and assert boundary behavior |
+| Wrapper-only test | Test protects a pass-through wrapper with no policy or boundary | Wrapper is a published API, external integration, or lifecycle seam | Remove wrapper and test together |
+| Defensive-machinery test | Test exists only for a validator, fallback, receipt, checksum, retry, or self-check that is itself suspect | Machinery has an independent surviving contract | Delete the mutual-support cluster |
+| Implementation-derived expected value | Expected value is recomputed by the code under test or a copied algorithm | Independent reference data or mathematical invariant exists | Use the independent oracle or delete |
+| Snapshot bloat | Large snapshots obscure a small behavioral signal | Rendered/serialized artifact is the externally reviewed contract | Replace with focused semantic assertions |
+| Fixture-tautological test | Fixture setup guarantees the asserted state and no production behavior is invoked | Fixture state is an independently established integration precondition | Delete |
+| Obsolete-behavior test | Test conflicts with an explicit current-task requirement or current authoritative project document | Supported consumers still require the old behavior | Replace the test with the corrected contract |
+| Unmanaged-artifact test | Default tests read untracked `outputs/`, a one-off run directory, or a local formal package | Input is repository-managed, test-created, or an explicitly provisioned external resource | Delete the orphan test/support cluster or rebuild a self-contained behavioral test |
+| Tracked-output test | A compiler or materializer reached through a test writes to a tracked target | The test redirects writes to a temporary path and treats tracked data as read-only input | Redirect the output; inspect deep builders, not only direct file writes |
+| Synthetic-capability test | A production dry-run invents observations or success states and a test asserts that scripted success | Dry-run only parses, assembles, or validates without claiming the backend capability | Delete the fake capability path and its test |
+| Fake-only dependency skip | A fake-backed test skips when an SDK or simulator it never calls is absent | The test actually imports, compiles, encodes, or calls the optional boundary | Remove the skip or use one consistent module-level boundary |
+| Disconnected layer tests | Producer, loader, and consumer pass separately, but no test crosses the current identity through all three | A hermetic integration root already protects that production edge | Keep or create the smallest independent current-path root before retiring the old fixture |
+| Coverage-owned branch test | A threshold mutation, future-only config, or direct post-gate helper call exists only to cover a branch | Active production input reaches the branch or an adjacent guard has distinct safety semantics | Remove the unreachable branch/test cluster after checking current configs and registries |
+
+## Closed justification loops
+
+Production code does not justify a test merely because the test exercises it. A test does not justify production code merely because the production code exists. Trace test -> production branch -> reason -> external evidence.
+
+If a test exists only to keep a defensive branch green, and the branch exists only because that test was added, the pair is mutual-support slop. Apply the same rule to checksum tests and digest code, receipt tests and receipt validators, wrapper tests and wrappers, compatibility tests and obsolete branches, and validator tests and validators. Do not preserve one member merely because the other member depends on it; delete the closed cluster when no independent root remains.
+
+Independent roots include an explicit current-task requirement, a current authoritative project document, real external caller, public API, documented protocol, security or trust boundary, persisted corruption boundary, scientific invariant, or a separately maintained reference dataset.
+
+## Keep or delete
+
+For every test, answer:
+
+1. What distinct behavior or plausible regression does it protect?
+2. Would it fail if that behavior regressed?
+3. Is the oracle independent from the implementation and its support machinery?
+4. Is stronger coverage already present?
+5. Does it observe a public or meaningful boundary?
+6. Would a harmless refactor break it while behavior stayed identical?
+7. Was it added only after a local correction, without a new failure mode?
+
+Delete or consolidate when no distinct regression remains. Preserve separate tests for distinct contracts, failure semantics, security properties, persistence/transaction behavior, concurrency, supported compatibility, resource limits, scientific invariants, known numerical results, and real prior regressions.
+
+Do not optimize for test count, assertion count, branch coverage, or line coverage. A smaller suite with independent signal is better than a larger suite that merely documents its own implementation.
+
+## Retire fixtures by behavior
+
+An obsolete fixture and the behavior once reached through it are separate decisions. Map every fixture-backed test to a current owner. Delete behavior with no owner; move surviving behavior to the lowest stable public seam. Before removing a cross-layer fixture, confirm that one hermetic test still crosses the current producer, reader, and consumer. Green endpoint unit tests do not prove that edge.
+
+Delete a fixture's private builders, fakes, compatibility fields, and helper stack when no surviving test or production path uses them. Do not restore an unmanaged experiment artifact or preserve a whole legacy package merely to keep one current assertion reachable.
+
+## Adding tests during cleanup
+
+Adding a test is not the default response. Add one only when:
+
+- a real externally meaningful behavior is otherwise unprotected;
+- the behavior is genuinely uncertain after reading callers, contracts, and history;
+- a plausible regression would fail the test;
+- the expected result has an independent source; and
+- the test observes a meaningful seam rather than cleanup details.
+
+When production slop is deleted, delete tests whose only purpose was to protect that slop in the same change. Do not add a replacement test merely because a function now lacks a unit test, coverage falls, or a model prefers symmetry. An explicit current-task requirement or current authoritative project document outranks a historical test that asserts obsolete or incorrect behavior; an inferred preference does not.
+
+## Consolidation discipline
+
+- Prefer one readable test per distinct behavior, not one per branch or helper.
+- Parameterize only genuine equivalence classes; do not hide an opaque generated matrix.
+- Keep scenario names and failure messages capable of localizing a real regression.
+- Run the remaining suite after deletion; zero remaining tests is not a passing cleanup.
+- Preserve low-level tests when low-level behavior itself is a stable contract, not merely because the code is private.
+- Count collected nodes before and after, then inspect skips and deselections; a smaller reported total can hide lost execution.
+- Fingerprint the worktree around suites that invoke compilers, materializers, exporters, or code generators.
+
+For generated inputs, current configuration, and cross-layer path checks, also read [evidence-and-reachability.md](evidence-and-reachability.md).

package/skills/deslop/references/verification-and-trust.md

@@ -0,0 +1,143 @@
+# Verification and Trust
+
+Verification adds value only when the verifier has information, authority, or a failure domain meaningfully independent from the producer. A checksum is not automatically a trust boundary, and a second function or test is not automatically an independent oracle.
+
+## Closed justification loops
+
+Trace the whole dependency cluster outward:
+
+```text
+production result
+    -> digest / receipt / manifest / validator
+    -> validator test
+    -> reason each member exists
+    -> independent evidence root?
+```
+
+Production code does not justify a test merely because the test exercises it. A test does not justify production code merely because the production code exists. If a checksum exists only because its test expects it, and that test exists only because the checksum was added, the pair is **mutual-support slop**. The same loop can contain serialization added only for hashing, digest fields, result envelopes, manifests, receipts, recomputation, wrappers, and wrapper-only tests.
+
+Delete the whole closed cluster when its chain reaches no independent root. Independent roots include:
+
+- a current user requirement or correction;
+- a real external caller or public API contract;
+- a documented wire protocol or specification;
+- a separately controlled security key or trust authority;
+- an independently supplied manifest, release digest, or content-addressed identity;
+- a persistence/readback or corruption boundary;
+- an independent consumer, regulator, reproducibility workflow, or operational system;
+- a scientific or numerical invariant with an independently derived expected result.
+
+Preserve one member only when the remaining cluster still serves such a root. Do not preserve every member because another member depends on it.
+
+## Trust-boundary decision tree
+
+```text
+Does the value cross out of the current trusted execution domain?
+|
++-- No
+|   `-- Is there concrete corruption, persistence, ownership, concurrency,
+|       or independent hardware/process failure to detect?
+|       +-- No  -> verification is probably redundant
+|       `-- Yes -> preserve only the check that can detect that failure
+|
+`-- Yes
+    `-- Is the source independently controlled or untrusted?
+        +-- Yes -> parse / validate / decode once at the boundary
+        `-- No
+            `-- Does a protocol, specification, or consumer require it?
+                +-- Yes -> preserve the required check
+                `-- No  -> identify the concrete failure model first
+```
+
+Public visibility alone does not create a trust boundary. Two services owned by the same producer can still be circular; one process can still cross a real failure domain by writing, publishing, reopening, decoding, or reading persisted output.
+
+## Declared authority is not optional enrichment
+
+When a config, package manifest, or sidecar declares an authoritative artifact, require and verify that artifact. A pattern such as `if path.exists(): verify(path)` silently changes a missing authority into compatibility mode. Missing and mismatched authoritative inputs should fail at the same boundary unless the protocol explicitly defines absence as valid.
+
+Lower-level sidecars or caches do not replace a missing package-level authority merely because they remain internally consistent. Conversely, a thumbnail, annotation, or cache marked optional by the current protocol may be absent without failure. Determine required versus optional from the contract, not from filesystem presence.
+
+## Schema and identity closure
+
+A writer and its main loader do not complete a schema migration. Enumerate every public deserialize boundary: library API, CLI, `tools/`, visualizer, converter, resume/recovery path, and validator. Each current reader should reuse the canonical validator or enforce the same shared version contract. Keep an explicit migration reader only when old data remains supported.
+
+For critical identity, source path, count, or handedness fields, align all three layers: type declaration, parser, and validation. A required annotation paired with `mapping.get(..., old_default)` remains an implicit compatibility path. Remove defaults that can reinterpret malformed current data as a historical format.
+
+## Independence test
+
+For every claimed verification, record:
+
+1. **Producer:** who created the value?
+2. **Verifier:** who checks it?
+3. **Independent knowledge:** what does the verifier know that the producer did not generate?
+4. **Independent authority:** is there a separate key, manifest, specification, identity, or consumer?
+5. **Independent failure domain:** can producer and verifier fail differently?
+6. **Action:** what meaningful response follows failure?
+
+If all inputs, logic, authority, and failure modes are shared, the check is circular even when it uses cryptography or another process.
+
+## SHA256 and checksum clusters
+
+Treat SHA256/checksum machinery as a cluster, not as one function. Search for the entire chain:
+
+```text
+canonicalization / serialization added only for hashing
+    -> digest field or checksum helper
+    -> result envelope / manifest / receipt
+    -> recomputation or validator
+    -> tests and fixtures created only for those mechanisms
+```
+
+When there is no independent expected digest, identity authority, trust transition, persistence-corruption role, content-addressing role, or external consumer, investigate and remove the whole support chain. Strong deletion candidates include hashes of local arguments, parameter objects, internal arrays, result dataclasses, self-created manifests, self-issued receipts, and evidence consumed only by the same agent or process.
+
+Do not call a local digest authentication merely because it is SHA256. A digest retained after secret redaction can be a legitimate non-secret correlation fingerprint when an independently recorded input or consumer uses it; that is provenance, not authentication, and its independent role must be explicit.
+
+## Verification-theater patterns
+
+### Recompute theater
+
+```text
+calculate result -> repeat the same calculation -> call it verified
+```
+
+Delete when both computations share algorithm, inputs, constants, and likely bugs. Preserve independently derived analytical checks, diversified implementations with a concrete safety purpose, and cheap invariants that detect a distinct failure class.
+
+### Schema and envelope theater
+
+```text
+producer emits payload -> producer-owned schema mirrors payload -> producer validates it
+```
+
+Delete when no external protocol, persisted format, or independent consumer relies on the schema. Preserve wire contracts and independently maintained schemas.
+
+### Receipt, manifest, and evidence theater
+
+```text
+operation -> evidence.json / receipt -> local validator -> local test
+```
+
+Delete ledgers and validators generated and consumed only by the same trusted workflow. Preserve records required by a separate authority, operational system, regulator, reproducibility workflow, transaction, idempotency boundary, or corruption detector.
+
+### Signature theater
+
+```text
+generate local key -> sign local result -> verify with paired local key
+```
+
+Delete when no identity, key custody, distribution boundary, or independent trust anchor exists. Preserve signatures authenticating an external publisher, protocol peer, or independently controlled key.
+
+## Persistence and readback
+
+Reopening an encoded file, archive, media object, or persisted record can be genuinely independent when it detects truncation, partial publication, codec mismatch, schema loss, or corruption across a write/read boundary. Do not collapse that into circular in-memory recomputation. Conversely, reading a value back from the same memory representation without a distinct failure domain adds little.
+
+## Defensive and fallback checks
+
+Repeated null/type/shape checks, broad catches, catch-log-rethrow, catch-and-fallback, repeated normalization, and self-validating result objects are suspicious when they add no boundary or failure domain. Preserve checks that enforce a documented safety, resource, authorization, transaction, concurrency, persistence, protocol, or numerical invariant.
+
+Prefer direct failure for unexpected internal errors. A narrow fallback for one documented missing field or supported legacy version is different from `except Exception: use_old_path()`. The former may be contractual while the compatibility window remains; the latter hides bugs unless independent evidence proves otherwise.
+
+## Preserve by default
+
+When evidence is incomplete, preserve security and authorization, real external protocols, supported compatibility, persistence and transactions, concurrency, resource limits, scientific invariants, independently supplied artifact verification, and content-addressed identity. Report the missing evidence instead of inventing a justification or deleting on aesthetic grounds.
+
+For production reachability, public-reader enumeration, and documentation/config ownership, also read [evidence-and-reachability.md](evidence-and-reachability.md).

package/skills/prototype/LOGIC.md

@@ -0,0 +1,73 @@
+# Logic Prototype
+
+A single, self-contained HTML file — a **shareable demo** — that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because the file has nothing to install, a designer, product manager, or domain expert can drive it directly. Use domain language, not implementation language.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, identify the state model, the question, and the evidence that will answer it. Put this information in a visible introduction, not only in a comment. A returning user must be able to understand the experiment without the earlier conversation.
+
+### 2. Isolate the logic in a portable module
+
+Put the logic that answers the question in one `<script>` block. Keep it in a small, pure module. The page is disposable. Treat the module as evidence for a later production implementation, not as production-ready code.
+
+The right shape depends on the question:
+
+- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick the shape that fits the question. Do not pick a shape only because it is easy to connect to the page. Keep the logic independent of the DOM: the page calls the logic, and the logic never calls the page. Reimplement or harden validated logic under the production project's normal standards.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS — no framework, no bundler, no server, everything inline so it opens by double-click and survives being emailed around. Anyone should be able to run it by opening it.
+
+Write it for a non-developer. Every label is in **domain language**, not code — buttons and state read like the business, not the reducer. Explain in plain words what's happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state** — the full relevant state, rendered as a readable panel (labeled fields, not a raw JSON dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call out what just changed.
+3. **Free-play buttons** — one button per action, always available, so anyone can poke at the model in any order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs** — a set of **scenarios**, one per tab. Each tab holds a short plain-language description of the scenario — the situation it sets up and what to watch for — and underneath it, the ordered **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same way every time.
+
+Choose scenarios that demonstrate the awkward cases — the happy path, a tricky edge case, an attempt at something that should be illegal — the ones hard to reason about on paper.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent color. No animations, no gimmicks — nothing that competes with the state and the buttons.
+
+### 4. Verify the prototype
+
+Open the file when the current environment supports local previews. Otherwise, provide its exact path and tell the user to open it in a browser.
+
+Run the happy path, one difficult edge case, and one illegal or rejected action. Confirm that each action updates the visible state. Confirm that reopening the file resets the state.
+
+### 5. Hand it over
+
+Give the user the file and name the walkthroughs. Invite feedback about impossible states, surprising transitions, and missing actions. Add a scenario only when it helps answer the original question.
+
+### 6. Capture the answer and the prototype
+
+When the prototype answers its question, record the verdict and evidence as [SKILL.md](SKILL.md) describes. Use the validated reducer, machine, or function set as input to the production implementation. Do not promote the HTML shell directly.
+
+## Anti-patterns
+
+- **Don't add a production test suite to the disposable shell.** Validate it by running the scenarios that answer the question.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
+- **Don't generalize.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button handlers, it's no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a React app or a dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimized for manual exploration. Carry the validated decision into production code and tests.

package/skills/prototype/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: prototype
+description: Build disposable code to answer one product or engineering design question. Use when the user wants to validate logic, state transitions, a data model, or API behavior, or compare structurally different UI directions before production implementation. Adapt to the current repository and agent environment. Do not require a specific model, coding agent, tool, browser, task runner, version-control host, or issue tracker.
+---
+
+# Prototype
+
+A prototype is **disposable code that answers one question**. The question determines the artifact.
+
+## Pick a branch
+
+Identify the question from the user's request and the surrounding code. Then read the matching branch before writing code:
+
+- **"Does this logic or state model feel right?"** → [LOGIC.md](LOGIC.md). Build one shareable HTML file. Let a non-developer drive difficult cases with free-play actions and guided walkthroughs.
+- **"What should this look like?"** → [UI.md](UI.md). Build several structurally different UI variants on one route. Make them switchable through a URL search parameter and a floating control.
+
+The branches produce different artifacts. If the choice is genuinely ambiguous, ask one focused question. If interaction is unavailable, infer from the surrounding code: use Logic for a backend module and UI for a page or component. State the assumption in the prototype.
+
+## Define success before coding
+
+State these points before you edit files:
+
+- the single question;
+- the evidence that will answer it;
+- the shortest way to run or open the artifact;
+- the production boundary that the prototype must not cross.
+
+Stop expanding the prototype when it can answer the question. Do not turn it into an alternative implementation project.
+
+## Adapt to the current environment
+
+- Follow project instructions, file layout, routing, framework, and styling conventions.
+- Use only capabilities that the current agent environment provides.
+- Open or render the prototype when a browser or preview tool is available. Otherwise, provide the exact file path, command, or route.
+- Use the project's normal planning and progress mechanism when one exists. Otherwise, keep a short checklist in the conversation.
+- Do not require Git, a hosted repository, an issue tracker, or an external service. Use them only when the current workflow already authorizes them.
+
+## Rules that apply to both
+
+1. **Mark it as disposable.** Put the prototype near the module or page it explores. Use `prototype` in the file, route, or directory name. Follow existing routing conventions.
+2. **Make it easy to run.** Prefer one existing project command for a UI prototype. Make a logic prototype a self-contained HTML file when possible.
+3. **Keep state in memory by default.** If the question requires persistence, use an isolated scratch store. Mark it clearly as disposable. Never use production data.
+4. **Skip production polish.** Add only the error handling needed to keep the prototype runnable. Do not add speculative abstractions or production tests for the disposable shell.
+5. **Expose relevant state.** After each logic action or UI variant switch, render the state that helps answer the question.
+6. **Protect production behavior.** Keep real mutations and production data outside the experiment. If the prototype uses an existing route, gate all prototype rendering so production ignores it.
+7. **Hand over an exact entry point.** Give the user the file path, command, route, and variant keys or scenarios. Open the artifact when the environment supports it.
+8. **Record the answer.** Record the question, verdict, and evidence in the current workflow. Preserve the prototype on a temporary branch or other archive only when requested or already authorized. Keep the main branch focused on the validated production decision.

package/skills/prototype/UI.md

@@ -0,0 +1,114 @@
+# UI Prototype
+
+Generate **several structurally different UI variants** on one route. Let the user switch variants with a floating bottom control. The user can choose one direction or combine specific parts, then discard the experiment.
+
+If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Choose the host shape
+
+A UI prototype is easier to judge beside the real application shell, data shape, and information density. Prefer an existing host page. Create a new route only when no suitable page exists.
+
+### Sub-shape A — adjustment to an existing page (preferred)
+
+The route already exists. Render variants **on the same route** behind a `?variant=` URL search parameter. Keep existing parameters and authorization. Use approved non-production data or representative fixtures. Change only the rendered subtree.
+
+If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
+
+### Sub-shape B — a new page (last resort)
+
+Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
+
+Create a **disposable route** with the project's routing convention. Do not invent a new top-level structure. Include `prototype` in the path or file name. Use the same `?variant=` pattern.
+
+Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
+
+In both sub-shapes the floating bottom bar is identical.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
+
+Write the question and plan in one line near the prototype or in a top-of-file comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
+
+Also state what difference the user should compare between the variants.
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
+- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colors. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher component on the route:
+
+```tsx
+// pseudo-code — adapt to the project's framework
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
+  </>
+);
+```
+
+For sub-shape A (existing page): keep approved non-production data fetching above the switcher. Change only the rendered subtree.
+
+For sub-shape B (new page): the disposable route under `/prototype/<name>` mounts the same switcher.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-center of the screen with three pieces:
+
+- **Left arrow** — cycles to the previous variant (wraps around).
+- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
+- **Right arrow** — cycles forward (wraps around).
+
+Behavior:
+
+- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
+- Disable the complete prototype path in production. Use the project's existing development or feature guard. The production route must ignore the variant parameter.
+
+Keep the switcher close to the prototype. Reuse an existing prototype control when one exists. Do not add a shared abstraction for one experiment.
+
+### 5. Verify and hand it over
+
+Run the project's focused build, type check, or route check when one is available. Open every variant when preview tools are available. Confirm that the URL preserves the selection and that keyboard controls do not intercept text input.
+
+Give the user the command, route, and `?variant=` keys. If the current environment cannot open the UI, say so and provide the exact manual steps.
+
+### 6. Capture the answer and clean up
+
+When a variant wins, record which parts won and why. Then follow the capture rules in [SKILL.md](SKILL.md). Implement the decision under normal production standards. Remove the prototype from the main branch when the current workflow authorizes cleanup:
+
+- **Sub-shape A** — fold the winner into the existing page; drop the losing variants and the switcher from main.
+- **Sub-shape B** — promote the winning variant to a real route; drop the disposable route and the switcher from main.
+
+If the current workflow preserves prototypes, archive the full variant set outside the main branch. Otherwise, ask before deleting the files. Do not leave losing variants or the switcher in production code.
+
+## Anti-patterns
+
+- **Variants that differ only in color or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

package/skills/prototype/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Prototype"
+  short_description: "Build disposable logic and UI prototypes"
+  default_prompt: "Use $prototype to build a disposable prototype that answers one design question."

package/skills/visual-recap/SKILL.md

@@ -73,19 +73,21 @@ State why the overall risk has that level. A new unit is not automatically high
 
 Match the visual to the review question:
 
-- Use a map for relationships and blast radius.
-- Use a flow or timeline for behavior that crosses several steps.
+- Use a Mermaid flowchart for relationships and blast radius.
+- Use a Mermaid sequence or state diagram for behavior that crosses several steps or states.
 - Use a table for exact mappings or classifications.
 - Use a side-by-side view for before and after.
 - Use interaction only when it helps the reviewer trace a path, inspect evidence, or compare states.
 
 Skip the diagram when one obvious relationship or a short table explains the change better.
 
-Prefer a native interactive surface when the current **Host Agent** can present it reliably and interaction saves review effort. Otherwise, use a rendered visual or inline Markdown. If diagrams do not render, use a compact text map.
+Use Mermaid as the default portable diagram format. It is an output representation, not a required tool. Let the current **Host Agent** render it with its native interface. Use a richer interactive surface only when it saves review effort.
+
+If the current interface does not render Mermaid, use a compact ASCII-art diagram as the first fallback. Use a Markdown table and short relationship list only when ASCII would be harder to scan or cannot express the relationship clearly.
 
 Do not require or name a product-specific tool. Do not add a dependency, deployment, or standalone application only to render the recap.
 
-Always provide a concise inline fallback. The fallback must preserve the outcome, affected units, risk, review hotspots, and evidence links.
+Always provide a concise inline summary. It must preserve the outcome, affected units, risk, review hotspots, and evidence links.
 
 ## Compose the Result