@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/execute-work/references/design.md

@@ -0,0 +1,271 @@
+# Design
+
+Read this when a design choice could make later work wrong or harder, at the section the situation names: building on a representation, identity, ownership or algorithm choice that dependent work would redo if wrong, or writing one into a Spec, recommendation or delegation contract (Settle The Choices); a new or changed interface between parts, or choosing which part owns a decision (Interfaces); module cycles, layering, dependency direction, or extracting shared code (Modules And Dependencies); the same change keeps touching many places, or each fix adds another flag, state or caller rule (Pressure Signals); state that must survive a failure: partial effects, retries, concurrent writers, recovery (State And Failure).
+
+This reference is judgment, with four Rules of its own below. It is a lens under the current activity, not a mandatory phase, an architecture owner, or permission to refactor. Read the section you need; the first three sections apply to all of them. Do not turn its lists into obligations unrelated to the accepted result.
+
+Hide coherent, likely-changing decisions behind small, stable, outcome-level interfaces, so callers need less knowledge and coordination for the same accepted outcome. A module is anything with an interface and an implementation. Its interface includes every fact a caller needs for correct use: operations, decisions, inputs, state, ordering, effects, errors, dependencies, timing, and recovery. A module is **deep** when it provides much useful, coherent behavior per unit of caller knowledge; depth is not fewer methods or more responsibilities, and a god module hiding unrelated decisions is not deep.
+
+## Rules
+
+- A design recommendation is not implementation authority, and this lens never enlarges a task by itself.
+- Never remove required correctness, trust, or safety to make a design smaller, and never turn hypothetical lifecycle completeness into a production requirement.
+- Never design around an invented product or failure policy. When a boundary would settle a user-owned choice, as [Discuss Work](../../discuss-work/SKILL.md) defines it, take its concrete consequences and supported alternatives there.
+- Do not invent APIs, files, or stronger guarantees to make a design look complete; name the missing observation or choice instead.
+
+## Start With The Required Outcome
+
+Goal: know whether the change touches a boundary worth designing, before designing anything.
+
+Understand enough to state the caller's complete outcome, source-backed behavior and non-goals, the decisions the caller genuinely owns, accepted constraints, the current interface, dependencies, canonical state, and the relevant success and failure boundary. Do not begin from existing flags, storage paths, classes, or temporary states; they may be symptoms of the current design. Do not survey the whole system or settle future variations without a present question. Ask:
+
+1. What outcome is changing?
+2. What must callers currently know or coordinate?
+3. Does the change spread policy, state, dependency choices, or lifecycle knowledge?
+4. Would the current boundary make correct use or the next likely change materially harder?
+
+For a local, source-backed, reversible change that leaves these boundaries sound, apply the lens silently and continue: generate no alternatives and add no abstraction because another shape is imaginable. A large mechanical change may need no design; a one-line change may need it when it changes permissions, public behavior, canonical state, or consequential failure semantics.
+
+Once a boundary is supported, do not reopen it because this lens is still in context. Re-enter when evidence shows growing caller coordination, scattered policy, exposed internal states, fragile test choreography, unclear dependency or failure ownership, or an invalidated design assumption. Ordinary bugs, duplication, test awkwardness, finding count, and preference do not establish structural pressure. When failures repeat without a supported cause, [diagnose](diagnose.md) first; this lens consumes a structural finding rather than inventing one.
+
+## Bound Success And Failure Proportionately
+
+Goal: the failure behavior that matters is owned, and nothing more is built.
+
+Before choosing classes, services, packages, flags, or states, name the caller and complete accepted outcome; caller-owned decisions and observable success and failure; the likely-changing coordination the module could hide; and the **failure unit**: what must succeed, fail, and recover as one coherent boundary, including whether partial reuse is required or merely an optimization. Where effects or partial state are consequential, establish the failure contract (observer, canonical and diagnostic state, forbidden outcomes, stop, degrade, fail or retry behavior, and supported recovery) with [State And Failure](#state-and-failure). Include cancellation, concurrency, or reconciliation only where required behavior or observed reachability makes them material.
+
+Classify each proposed mechanism by what it is for: **trust** (knowing the result is valid), **safety** (preventing damage, leakage, or runaway behavior), **efficiency**, **scale**, or **portability**. Trust and safety cannot be deferred to simplify a design; efficiency, scale, and portability need an accepted requirement or observed pressure before they shape it. A module owning a failure unit does not automatically need durable replay, rollback, universal provenance, or every recovery mechanism.
+
+## Settle The Choices
+
+Goal: the choices that could change correctness, complexity or failure behavior, or force dependent work to be redone, are settled before that work starts; ordinary mechanics stay free.
+
+Name the actual question, not a generic demand for more design. Deciding which occurrence identifies a source matters more than choosing a map or an array; deciding what survives a failed transfer matters more than choosing a retry helper. For each consequential unknown, take one route:
+
+- **Evidence supports a mechanism:** select it and say why it fits.
+- **An environmental fact is missing:** find the observation that distinguishes the alternatives before dependent work.
+- **A user-owned choice is unsettled:** take it to Discuss Work.
+- **Only ordinary mechanics remain:** leave them to implementation.
+
+Make explicit only what the question needs:
+
+- **Representation and identity:** domain objects and their independent lifetimes; what counts as the same occurrence; what must stay distinct.
+- **Algorithm and cost:** the essential steps; collection keys and relationships; update and invalidation rules; work repeated as input grows. Naming a data structure without its keys, meaning, and maintenance rules is not useful direction.
+- **Ownership, effects and modules:** the sections below.
+
+When you pass a decision on to another implementer or your later context, give the decision, why it fits, the invariant it protects, the plausible wrong approach and the observation that tells them apart, and which parts are required versus local freedom. Do not prescribe every loop or helper, or reproduce the whole program in prose. Reuse design decisions already supplied the same way; a path to a design is not its content.
+
+Weak and useful direction, for example:
+
+- Weak: "Use a Map and avoid repeated scans." Useful: "Keep native occurrence IDs as source identity. Equal bodies may identify several candidates; do not merge their occurrences. Let the source owner maintain the result-to-exchange relationship, and rebuild affected indexes after ancestry replacement. Check repeated equal bodies, late attribution, and a branch change; measure the repeated preparation path rather than only an isolated lookup. Helper layout is local. Reconsider the index if the source does not provide the assumed stable identity."
+- Weak: "Make persistence idempotent and robust." Useful: "The append owner distinguishes observed acknowledgment from an uncertain attempt; an equal entry in memory does not resolve an earlier failure. Validate before mutation; publish accepted state only at the supported acknowledgment boundary. Test append advancing memory then failing, followed by the identical operation: uncertainty must remain until supported reconciliation. Also test an acknowledged duplicate, so not every retry is rejected. Do not infer filesystem durability from readback."
+
+When an unfamiliar boundary could invalidate substantial later work, build the first coherent path that can disagree with the design, often across several files and a failure case, before expanding dependent work; a skeleton, happy-path result, or green summary alone may not exercise the decision. Compare the actual ownership, identity, ordering, and failure behavior with the decision, not its suggested filenames or helpers. A precise sketch can be wrong: keep accepted behavior, stop dependent effects when the mechanism is invalidated, and settle the affected choice before continuing. Supported local corrections need no design restart.
+
+## Interfaces
+
+Goal: callers request outcomes; the module owns the protocol, with the smallest honest contract.
+
+List only the facts callers must know that could affect the boundary: operations and inputs, caller-owned decisions, ordering and lifecycle states, configuration and provider details, dependencies, errors and failure semantics, compatibility and migration, and recovery, cost and performance expectations. For each, and before exposing any flag, path, state, ordering rule, retry, provider detail, or recovery step, ask whether the caller genuinely owns it, whether the module could, whether it is stable enough to become a supported contract with an understood compatibility cost, and whether changing it would force surrounding edits.
+
+Keep public: caller-owned outcomes and decisions, necessary inputs and stable invariants, observable success and failure, and information required for correct recovery. Keep internal unless callers genuinely control it: sequencing, storage layout, dependency construction, provider mechanics, retries, cleanup, temporary states, caches, optimization machinery, and diagnostic details. Every observable fact is a contract callers may come to depend on.
+
+A **seam** lets behavior, a dependency, or an observer change without coordinated surrounding edits; the adapter, clock, provider, or probe that plugs into it is what varies. Add one for demonstrated variation, a known migration, a required observer, or a dependency needing control, not for imagined flexibility.
+
+When materially different ownership choices remain viable, design two or three interfaces that change seam placement, not only terminology. For each show ordinary caller usage, caller-owned decisions, the hidden internal protocol, the failure unit and observable behavior, the dependency and adapter strategy, the evidence needed, and the material cost. Compare only on criteria that could change the choice: behavior per interface fact, locality of likely change, cohesion and ownership clarity, correct-use ergonomics, misuse and hidden-decision risk, dependency direction, failure honesty and recovery, contract stability, test surface, reversibility, maturity fit, and implementation and evidence cost. Do not manufacture alternatives for a local, reversible, source-backed choice.
+
+Prefer the boundary that removes concepts and coordination over one that centralizes the same protocol behind new terminology or another helper. Do not centralize unrelated responsibilities to reduce interface count, or scatter an old protocol into callers while claiming an abstraction was removed.
+
+The intended interface should normally be the behavior and test surface. Question the design when callers or tests must bypass it, coordinate private lifecycle steps, replace many internals, or know dependency construction the module should own. An internal test inspecting internals is not itself a defect; the concern is callers needing hidden knowledge, or a fixture manufacturing the behavior it claims to observe. Tests that protect accidental machinery do not justify keeping it, and production architecture should not imitate the test framework.
+
+## Modules And Dependencies
+
+Goal: modules own coherent decisions and dependencies point toward stable policy; do not reorganize the codebase for conceptual purity, or because it has many files.
+
+A module should own one coherent outcome, policy, state boundary, or failure unit. Do not split only by processing step, file type, framework convention, size, or a wish for more abstractions; ask which behavior changes together, which decision has one reason to change, which state and failure behavior belong together, and what callers should stop coordinating. Pressure exists when one module owns unrelated policies, one policy is spread across many modules, state transitions sit apart from their invariants, failure handling is detached from the operation it protects, or callers assemble the real behavior from helpers.
+
+Policy should not depend directly on volatile infrastructure that can change independently: stable outcome or policy, then a small dependency interface, then the infrastructure adapter. A **port** is an outcome or capability policy requires; an **adapter** supplies the concrete infrastructure. Use them for provider variation, a known migration, infrastructure details leaking into policy, or tests that need safe dependency control; not when one stable implementation exists, the wrapper hides no decision, the generic interface keeps provider quirks, or caller complexity does not drop. Do not add interfaces around every concrete implementation.
+
+A dependency cycle usually means responsibilities are divided wrongly, shared policy or state has no single owner, an interface exposes implementation details, or modules must know each other's lifecycle. Do not break it by moving imports or adding a neutral-looking utility while the conceptual cycle stays; name the shared decision and give it an owner. A layer earns its place when it hides a distinct level of decision; it is shallow when it forwards calls, renames types, exposes lower-layer errors and states, makes callers understand both layers, or exists only to satisfy a pattern.
+
+A shared helper can centralize syntax while policy ownership stays scattered. Before extracting shared code, ask whether it is one concept that should evolve together, who owns its behavior and failure contract, whether callers still make the same decision independently, and whether extraction removes coordination or only moves code. Some duplication is cheaper than a shared abstraction with unclear ownership.
+
+## Pressure Signals
+
+Goal: identify the pressure that changes the next action, or conclude that none does; do not count smells or redesign the system.
+
+Ask what caller outcome and interface are affected, what callers must know or coordinate, whether the current change added to it, what policy, dependency, state transition or failure behavior is spreading, whether the cause is supported, and whether it can be resolved inside accepted scope and authority.
+
+Complexity is coordination, not line count; a large implementation can be simple to use, and a small helper complex when every caller must know its quirks: change amplification (one change needs many surrounding edits), cognitive load (callers must remember many facts), obscurity (important rules are hard to find), dependency burden (a safe change needs unrelated modules understood), and unknown unknowns (a caller cannot tell what else to inspect). Signals:
+
+- **Change amplification:** one policy change needs edits across unrelated callers. Name the decision causing them; do not merely move the same choreography into one helper.
+- **Caller protocol growth:** callers perform internal lifecycle steps, each correction adds a state or flag, recovery becomes ordinary caller behavior, or callers depend on paths, filenames, provider errors, or queue names. Ask whether one operation can own the whole success and failure unit and publish diagnostics separately.
+- **Scattered policy:** one product or operational decision is encoded in several places. Do not centralize it until the policy is accepted; stop for a decision when it is user-owned or conflicting.
+- **Unowned state or failure:** no module owns canonical state and its visibility point, forbidden partial outcomes, retry or escalation, cancellation and reconciliation, recovery after partial completion, or the evidence proving the final state.
+- **Contract-surface growth:** each patch adds public flags, temporary states, manifest fields, retry links, recovery instructions, provider-specific errors, or cache and integrity controls.
+- **Distorted tests:** tests reproduce caller choreography, mock many helpers to verify one outcome, depend on private lifecycle states, protect machinery from recent patches, prove rejection without checking forbidden writes, or make provider mechanics look like domain requirements. First check whether the production boundary owns the complete behavior; do not add mocks or test-only seams automatically.
+- **Edge-case patch streams:** related fixes keep adding conditions, states, or caller rules. Diagnose whether they share one missing contract, state owner, or failure unit; finding count alone is not architecture.
+- **Scope growth:** a bounded result unexpectedly needs a subsystem, pulls in deferred capabilities, invalidates earlier evidence, or requires unrelated callers to change.
+- **Wrong edits that look right:** assume the next contributor knows only the files it has open, imitates the closest existing code, and stops at the first change that builds. That edit goes wrong when one piece of state has two writers and the edit reaches only one, when two supported ways do one task and each copy spreads the one found first, when outside code can import a module's internals and so turns them into interface, or when lists of the same items are kept in step by hand. Look for the boundary that makes the obvious local edit correct everywhere: one writer, one way, unreachable internals, and lists derived from one source or checked against it.
+- **Interface mismatches:** a pass-through wrapper that hides no policy (keep it only for a real domain, compatibility, or observation boundary); a leaky interface exposing infrastructure details; a god module; a speculative seam; a dependency cycle; a Spec or Plan freezing classes, tables, or algorithms before evidence supports the boundary.
+
+Do not escalate when stable repetition is small and local, broad edits are mechanical and source-backed, a one-off script needs no abstraction, a wrapper keeps a real compatibility contract, one condition is wrong but the interface is sound, an internal test deliberately checks an internal module, or resolving the pressure would exceed the user's goal without blocking it.
+
+Choose the narrowest supported route: continue (the boundary is sound); a local correction (the defect stays within one module and contract); diagnosis (the failure is repeated or unexplained); a Spec or Plan revision (behavior, acceptance, or the execution boundary is incomplete); a user decision (resolving it makes a user-owned choice); learning (evidence cannot distinguish viable boundaries); deepening (a supported information-hiding improvement fits accepted scope); or deferred deepening (real but not worth resolving now).
+
+When pressure is supported, find the decision the module should hide. Organize modules around decisions likely to change, not processing steps: instead of exposing `parse -> validate -> retry -> send -> log -> clean up`, look for the policy those steps implement: ask which decision would cause the most surrounding edits if it changed, which callers know it now, who should own it, and what outcome-level interface would let callers stop knowing it. A wrapper is not deep because it hides lines; it is deep when callers stop knowing concepts or coordinating protocol. Failure and recovery policy are often that decision. Keep one coherent model of the outcome, state, and failure behavior; pressure exists when a concept has different names or rules across callers, several modules partly own one decision, or callers translate between incompatible representations. Stop the current patch when it clearly spreads a likely-changing decision, adds caller protocol, exposes internal state, creates another required workaround, or makes the next accepted change materially harder. Name the boundary:
+
+```text
+Outcome:
+Coordination currently spread across:
+Likely-changing decision:
+Current owners:
+Proposed owner:
+What callers would stop knowing:
+Failure unit:
+Evidence still missing:
+```
+
+If the decision cannot yet be named, define one bounded learning question rather than a generic abstraction.
+
+## State And Failure
+
+Use this section when state must survive a failure: correctness materially depends on canonical state, partial effects, atomic visibility, concurrent writers, cancellation, retries, recovery, reconciliation, or evidence of the final outcome. Do not apply it to a simple local value change whose state owner and failure behavior are already sound.
+
+### Name Canonical State
+
+Identify:
+
+- canonical source of truth;
+- who may create, replace, or invalidate it;
+- visible states and invariants;
+- commit or visibility point;
+- diagnostic versus authoritative records;
+- what callers may safely cache or infer.
+
+Do not let several modules each behave as the source of truth.
+
+A log, cache, temporary file, UI projection, or recovery marker is not canonical merely because it is observable.
+
+### Define State Transitions
+
+For every material transition, establish:
+
+```text
+precondition
+-> accepted operation
+-> commit or visibility point
+-> resulting canonical state
+-> evidence
+```
+
+Name forbidden transitions and partial states.
+
+Prefer one owner for transition policy. Callers should not reproduce state-machine rules independently.
+
+### Bound Partial Effects
+
+When an operation affects several resources or can fail midway, establish:
+
+- which effects may occur before commitment;
+- which effects are forbidden before commitment;
+- what must be rolled back, reconciled, or retained;
+- what prior accepted state must survive;
+- how partial outcomes are detected;
+- what result is safe to expose.
+
+Atomicity may come from transactions, staging, replacement, versioning, or explicit reconciliation. Do not claim atomic behavior from intention alone.
+
+### Separate Retry, Resume, And Replay
+
+These are different capabilities:
+
+- **Retry:** attempt the same operation again.
+- **Resume:** continue incomplete work from preserved state.
+- **Replay:** apply an event or request again.
+- **Idempotency:** repeated application has one supported effect.
+- **Recovery:** restore a safe supported state.
+- **Reconciliation:** compare and resolve divergent state.
+
+Supporting one does not imply the others.
+
+Expose them only when required by accepted behavior or observed failure.
+
+### Design Concurrency Deliberately
+
+When operations can overlap, identify:
+
+- shared state;
+- ordering and visibility;
+- lost-update or duplicate-effect risk;
+- serialization or conflict rule;
+- cancellation behavior;
+- stale-read policy;
+- observer capable of proving the required outcome.
+
+Before serializing writers, ask whether they need one shared target at all. When each publishes its own facts, give each its own file, key, or record and combine them where they are read; two workers updating different fields of one state file still share it. Serialize, with a lock, a queue, or a single writer, only when one shared target is itself required.
+
+Do not add locks, queues, retries, or optimistic versions without naming the invariant they protect.
+
+### Define Failure And Recovery
+
+For the failure unit, state:
+
+- who observes failure;
+- canonical state after failure;
+- diagnostic evidence;
+- forbidden partial effects;
+- fail-open, fail-closed, degrade, stop, retry, or escalation behavior;
+- safe restart or recovery operation;
+- evidence proving recovery.
+
+A graceful error response does not prove graceful state handling.
+
+### Keep Recovery Out Of Ordinary Callers
+
+Callers should normally request an outcome and receive supported success or failure.
+
+Do not require every caller to know:
+
+- cleanup order;
+- retry schedule;
+- temporary paths;
+- partial-state markers;
+- provider error translation;
+- reconciliation commands.
+
+Publish diagnostics without exposing recovery choreography unless callers genuinely own recovery.
+
+### Test State And Failure Through Observable Invariants
+
+Tests should verify:
+
+- accepted final state;
+- preserved prior state;
+- forbidden writes;
+- composed failures;
+- retry or replay behavior when required;
+- cancellation and recovery;
+- evidence at the real observing boundary.
+
+A passing happy-path test does not prove partial-failure safety.
+
+### Return For State And Failure
+
+Return the canonical state and owner, material invariants, the failure unit and its forbidden partial outcomes, the retry, resume, replay, and recovery capabilities actually required, and remaining uncertainty. Stop when state and failure ownership are sufficient for the current decision; do not design every theoretical failure mode.
+
+## Return The Smallest Supported Change
+
+When evidence cannot choose between viable boundaries, answer that question with a bounded learning action rather than building the future system:
+
+```text
+Question:
+Competing boundaries:
+Smallest prototype or observation:
+Evidence required:
+Time or cost boundary:
+Discard-or-promote rule:
+Return condition:
+```
+
+The experiment must answer the design question; if its next prerequisite is future production infrastructure, reassess before building it. Working exploratory code is evidence, not production architecture. Compare alternatives only when they are real. Recommend the simplest supported boundary that preserves required behavior, with the structural evidence, the decision it hides, its caller contract and failure behavior, its principal cost, and what would invalidate it: keeping the existing design, a local correction, diagnosis, an artifact revision, a learning action, an accepted deepening, explicit deferral, or a stop for the user's direction. When the selected result is behavior-preserving reduction, use [simplify](simplify.md). Freeze a sufficiently supported boundary instead of pursuing architectural completeness.

package/skills/execute-work/references/diagnose.md

@@ -0,0 +1,117 @@
+# Diagnose
+
+Read this when a failure has no known cause, or two fixes did not hold: an unexplained bug, failed check, regression, slowdown, flaky or environmental behavior, or contradictory observations.
+
+This reference is judgment, with the Rules below and one more under Flaky And Performance Failures. It adds the loop and its routing to Execute Work's [Diagnose Before Fixing](../SKILL.md#diagnose-before-fixing), which already holds the essentials: a plausible line is a hypothesis, the explanation must cover the whole symptom, and two failed fixes mean the diagnosis is wrong.
+
+Establish what fails and why before selecting a correction. A supported cause distinguishes the meaningful alternatives well enough to bound the next action; it does not require impossible certainty. A requested patch, a reviewer's theory or a favorable rerun is not a supported cause.
+
+## Rules
+
+- Never invent the expected behavior. When accepted behavior or source truth is unsettled, settle it through [Discuss Work](../../discuss-work/SKILL.md) before diagnosing against it.
+- Before active evidence generation, confirm the work agreement covers its path, environment, repetition, instrumentation, cost, sensitive data, and cleanup. Covered bug investigation needs no extra permission; otherwise propose the observation and its stop condition to the user and wait.
+- Preserve unfavorable evidence. Never rerun until a failure disappears, and never drop a contradicting observation.
+- Minimize and sanitize logs, traces, payloads, dumps, screenshots, and browser state; never expose credentials or unnecessary private data.
+- Report a mitigation as containment, not resolution; never claim fixed when only a mitigation succeeded or the reported boundary is unverified.
+- When a remedy makes a user-owned choice, as Discuss Work defines it, take its concrete consequence and alternatives there before adopting it.
+
+## Enter Only For An Unsettled Cause
+
+When fresh evidence already shows a clear local defect and the remedy, correct it under [Execute Work](../SKILL.md) instead. Several bugs in one area do not establish a shared structural cause. Keep diagnosis inside the current Slice; when continuity needs it, record the hypothesis, the evidence that decides it, rejected approaches and the next action through [Track Work](../../track-work/SKILL.md), not every trial.
+
+## Establish The Failure, Not The Proposed Fix
+
+Identify only what the investigation needs: the expected behavior and its source; the observed symptom and any counterevidence; the relevant input, state, environment, timing and path; and the strongest boundary actually observed, with any gap between it and the reported failure. A nearby symptom suggests a hypothesis but does not reproduce the reported defect; state reduced fidelity.
+
+Allowed behavior is not a bug: a cache hit is not a stale-read failure when caching is permitted. A possible race in source is not the cause without evidence connecting its timing and state to the symptom.
+
+## Choose A Distinguishing Observation
+
+State a falsifiable leading explanation and only the alternatives the next observation must tell apart:
+
+```text
+Hypothesis:
+Predicted observation:
+What would contradict it:
+Meaningful alternative:
+```
+
+Choose a repeatable loop whose possible results differ between those explanations. Do not build a hypothesis around the requested patch and then treat consistency with it as proof. When timing, randomness, environmental variance, concurrency, or resource behavior shapes the failure, read Flaky And Performance Failures below before selecting or running an observation.
+
+Common loops, smallest first that reaches the reported boundary:
+
+- **Failing test:** an existing stable interface or test boundary reaches the reported behavior.
+- **Reproduction command:** one CLI, package task, or script with representative fixture input.
+- **HTTP or protocol script:** the smallest real request sequence that crosses the affected boundary.
+- **Browser path:** the user flow with relevant DOM, console, network, and visual observations.
+- **Captured trace:** a sanitized log window, HAR, event payload, seed, timestamped screenshot, dump, or production sample replayed safely.
+- **Throwaway harness:** a minimal script around the real module when no test framework reaches it.
+- **Differential loop:** the same input through old and new code, configuration, dataset, dependency, or environment.
+- **Instrumented run:** targeted probes at boundaries that distinguish competing hypotheses.
+
+Before running, write down only the outcomes that tell the hypotheses apart:
+
+```text
+Observation outcome | Effect on leading hypothesis | Effect on alternative
+```
+
+If every likely outcome leaves the same hypotheses plausible, sharpen the observer or choose another loop before generating evidence. Prefer a loop that is sharper (observes the symptom, not generic failure), more representative (keeps the relevant input, state, environment and boundary), more distinguishing, more deterministic (pins time, randomness, dependencies, filesystem or network only when that preserves the failure), faster without narrowing the claim, and safer (isolated mutation, sanitized evidence, bounded cleanup).
+
+An observer must sit on the real path and cover the complete operation; a manual counter beside the path, a helper call, or a nearby mocked flow does not prove the reported boundary ran. A UI save that stays pending needs the browser path with its request, console and rendered state, not a reducer unit test. A callback said never to run needs its registered entrypoint invoked or observed, not its helper called directly. A failure only in CI needs the same input compared across local and CI configuration before any timing change or retry.
+
+## Flaky And Performance Failures
+
+Rule: never stabilize a flaky failure with sleeps, retries, wider timeouts, swallowed errors, or disabled checks unless evidence shows that mechanism addresses the causal timing or availability contract. Suppressing observation is not correction.
+
+Diagnostic measurement explains why variance or resource behavior occurs; after correction, Verify Work establishes whether the representative behavior or performance claim holds.
+
+**Flaky failures.** The goal is not one lucky rerun: raise the reproduction rate or capture the distinguishing event until the failure can be explained. Use, when safe and representative, bounded repetition of the exact failing path; captured seeds, time, timezone, locale, viewport, browser, runtime and dependency versions; controlled scheduling, fake clocks, CPU pressure, network delay or concurrency; console, network, event-order, scheduler, screenshot or video traces; and old-versus-new, local-versus-CI or headed-versus-headless differential runs. Choose the repetition count from runtime, cost, side effects and the estimated failure rate, and state the stop condition before running. One green rerun does not contradict an intermittent-failure hypothesis; one red rerun may establish the symptom but not its cause. Classify from the aggregate pattern or the captured event. Do not loop mutating production behavior to improve reproduction. Twenty green reruns after widening a timeout mean the failure was suppressed or became rarer; its cause is still unresolved.
+
+**Performance problems.** Measure the reported path before optimizing it. Useful causal evidence includes a baseline for the representative workload; the slow input, dataset, concurrency, cache and dependency state; a profiler, flamegraph, query plan, allocation profile or browser trace; an old-versus-new comparison under matched conditions; and a benchmark of the dominant work the evidence identified.
+
+Reduce a large profile, trace, or heap snapshot to a form you can query before reading it, such as one row per sample, frame, or node in SQLite. Then query for the frames holding the most time, or follow the retainer chain from the leaked object to a root. A hot frame without a source mapping is not yet a diagnosis: resolve its symbols, or say the artifact lacks them. One capture supports the strongest remaining hypothesis; a matched before-and-after capture or another distinguishing observation is needed to support the cause.
+
+A microbenchmark can test a hypothesis but does not explain the reported slowdown unless the isolated operation determines the real path: a parser benchmark that improves while the trace is dominated by database waiting explains nothing. Repeated calls with one object justify memoization only when the reported workload repeats that object and measurement shows the repeated work dominates. Median latency improving while tail latency or memory crosses the accepted boundary leaves the claim contradicted or incomplete.
+
+When choosing the correction for the dominant work, try the cheapest kind first and stop at the first that meets the target: drop work whose result nothing uses, stop repeating it, do less of it, defer it, move it off the path someone waits on, run it concurrently, and only then make it faster. Sanitize production traces and payloads; when safe production evidence is unavailable, use representative non-production evidence and downgrade the claim. After an authorized correction, verify that the representative baseline improves and required behavior stays correct, and report variance and resource trade-offs rather than one favorable run.
+
+Stop when the loop has produced a distinguishing pattern or event, the planned repetition or cost boundary is reached, or the required representative evidence is unavailable.
+
+Stop reading once the context supports the experiment. If no safe, useful observer exists, report the smallest missing input, trace, environment, permission, or instrumentation rather than patching a guess.
+
+## Interpret One Iteration
+
+Run one covered observation, changing one distinguishing variable at a time. [Verify Work](../../verify-work/SKILL.md) owns what a check result means; diagnosis owns the causal inference. Keep three results apart:
+
+- **Check result:** Passed, Failed, Error, or Unavailable, as Verify Work defines them. Observing an expected target failure can be a Passed check.
+- **Hypothesis result:** Supported, Contradicted, Inconclusive, or Unavailable at the stated boundary.
+- **Cause status:** Supported or Unresolved.
+
+A supported cause connects trigger and state through a mechanism to the symptom, predicts the observations, weakens the viable alternatives, and bounds a correction without guessing. A supported hypothesis need not establish the cause: if only the strongest remaining hypothesis is supported, say so and name its missing link.
+
+- Check Error -> repair or replace the observer, not production.
+- Check Unavailable -> return the missing evidence or authority.
+- Hypothesis Contradicted -> keep the result and revise the explanation.
+- Hypothesis Inconclusive -> choose a sharper observer if one is useful and covered.
+- Hypothesis Supported, cause Unresolved -> test the remaining link or alternative.
+- Cause Supported -> return the correction boundary.
+
+Stop when the cause is sufficiently supported or no covered observation can improve the decision; do not keep investigating because stronger certainty is imaginable.
+
+## Keep The Correction Inside The Task
+
+A failed reproduction method is not proof that production needs new infrastructure, a stronger guarantee, or a host change. Choose the smallest correction that preserves accepted behavior, and classify only the owning cause the evidence supports: a local defect; an invalid, stale or inadequate check; an environment, dependency, data, timing or configuration issue; a missing observer; unsettled behavior or a source conflict; the wrong result, scope, order or strategy; or structural ownership, interface, state or failure-unit pressure.
+
+Before adding a guard that lets the failing state pass, such as a check, default, retry or caught error, ask whether accepted behavior allows that state. If it should never exist, the guard hides the defect; correct what produced it. Once the cause is supported, look for the same fault wherever the same mechanism recurs; correct instances inside the agreed boundary and report the rest.
+
+When the evidence establishes structural pressure, read [design](design.md); it shapes the boundary without re-proving the cause. If design reveals an unsupported causal premise, come back here with that exact uncertainty.
+
+## Contain Harm And Keep Instrumentation Honest
+
+Bound repetitions by time, cost, effects, and environment safety. Temporary instrumentation must distinguish hypotheses; keep it isolated and state its observer, its mutation or performance impact, its removal condition, and whether it remains. When immediate harm needs containment before the cause is settled, propose one narrow, reversible mitigation to the user that preserves evidence, defines its check and recovery, and settles no undefined behavior. An experimental patch can generate evidence when authorized as learning; it does not select production behavior.
+
+## Return A Supported Correction Boundary
+
+Return proportionately: the failure and expectation at the required boundary; the loop, check result and hypothesis result; the causal chain, alternatives weakened and remaining uncertainty; the owning cause and smallest correction; a minimized regression signal; when the deciding fact took deep digging, a cheap always-on signal (a log line, assertion or metric) that would have shown it at first look; and instrumentation, containment, residual effects and authority limits.
+
+A covered correction continues under Execute Work. Use [simplify](simplify.md) only for an accepted removal of obsolete or workaround machinery, not as a substitute for the fix. After correction, verify the minimized signal and the original reported path or the strongest available observer; a nearby passing test is not enough. If the fix fails or reveals related shared-state consequences, return to the causal question before another patch.

package/skills/execute-work/references/migration.md

@@ -0,0 +1,108 @@
+# Migration
+
+Read this when moving users, data or traffic to a replacement, or removing an old path: a new implementation, schema, service, configuration form, dependency or platform that consumers in use must move to safely.
+
+This reference is judgment about moving consumers, state or traffic without losing compatibility, evidence or recovery options; its "do not" lines and the authority Rule below are binding.
+
+A replacement existing does not prove that consumers moved. A migration unit may be complete while the old path remains under an accepted support contract. Removal is a separate claim with separate evidence and authority.
+
+## Establish Authority And Scope
+
+Rule: loading this reference, discussing a migration, or approving a general implementation Plan does not authorize migration, deprecation, cutover, destructive cleanup, or removal. Carry out only the stages and units explicitly requested or separately approved.
+
+Take to [Discuss Work](../../discuss-work/SKILL.md) whatever remains unresolved among: maintaining, deprecating or removing the old behavior; advisory versus compulsory migration, deadlines or support windows; compatibility, public API, data conversion, downtime, permissions, billing, security, privacy or data-loss behavior; irreversible cutover, destructive cleanup or rollback limits.
+
+Do not manufacture a migration because code looks old: inspect ownership, supported consumers, runtime use, source truth, incidents, maintenance cost, and current value. When replacement behavior, interfaces, ownership or failure semantics remain unsettled, settle them first: Discuss Work for a user-owned choice, [design](design.md) for a design-bearing boundary, [Write Docs](../../write-docs/SKILL.md) when the accepted migration behavior needs a durable contract.
+
+## Define The Migration Contract
+
+Before moving anything, establish:
+
+```text
+Old contract and current value:
+Replacement contract and known differences:
+Consumers / callers / data / traffic:
+Compatibility promise and support window:
+Migration unit and ordering:
+State written during transition:
+Verification for each unit:
+Rollback or forward-recovery path:
+Removal proof:
+Owner decisions and stop conditions:
+Approved stages and scope:
+```
+
+Treat undocumented observable behavior as a possible consumer dependency until evidence says otherwise. Do not preserve every quirk automatically; surface consequential differences for decision.
+
+Choose the smallest shape that preserves accepted compatibility, safety, and evidence; do not force every migration through one sequence:
+
+- **Code or API:** add the new contract, migrate callers in bounded groups, remove the old contract.
+- **Configuration:** support old and new forms temporarily, migrate stored and generated config, reject the old form only after compatibility obligations end.
+- **Traffic:** route bounded cohorts to the new path, compare behavior and operational signals, expand only when the advance criteria hold.
+- **Data:** expand the schema, backfill or transform, move reads and writes, reconcile, then contract the old representation.
+- **Dependency:** introduce the replacement, verify compatibility at owning seams, migrate packages or consumers, remove the old dependency and its transitive assumptions.
+- **Feature:** define replacement or removal behavior, migrate users and documentation, observe usage, then remove code and operational surfaces.
+
+Inventory consumers from static references and dependency graphs; runtime traffic, logs, metrics, traces or audit records; generated clients, plugins, scripts, jobs and configuration; external teams, independently deployed services, offline clients and dormant accounts; package download or version-support data; and owner attestations where observation is impossible. Classify unknowns: missing telemetry is unavailable evidence, not zero use. For the static part, Execute Work's [touch-map](../scripts/touch-map.mjs) lists entry points, readers, writers and covering tests for each old symbol or file, and what it did not search.
+
+## Prepare The Replacement
+
+When an additive or replacement stage is approved:
+
+- prove the replacement through the real caller path or interface;
+- keep old and new ownership explicit;
+- add adapters, flags, aliases, translation, or dual reads and writes only when the migration contract requires them;
+- do not add features to the old path unless safety or an explicit support decision requires it.
+
+Adapters, aliases, dual writes, translation, flags, and shims are migration tools, not permanent architecture. For each, record:
+
+```text
+Purpose:
+Consumers protected:
+Observable differences:
+Owner:
+Exit condition:
+Removal evidence:
+Failure behavior:
+```
+
+If a shim grows harder to remove with each consumer, or starts spreading caller knowledge, public states or exceptions, take the structural evidence to [design](design.md#pressure-signals) rather than building a second permanent system.
+
+Before moving data, settle the authoritative source in each phase; idempotency and restart; duplicate, partial, invalid and late records; read and write ordering and reconciliation; privacy, retention, permissions and audit; rollback versus forward-only recovery; and backup, restore and destructive-cleanup proof. A reversible schema change does not imply reversible data semantics.
+
+An emergency migration without a viable replacement may be necessary for security or data safety, but it needs explicit owner direction, bounded impact, and a documented failure and recovery contract.
+
+## Move Bounded Units
+
+Move one accepted consumer, cohort, traffic segment, configuration set, or data partition at a time:
+
+1. capture the relevant pre-migration state or baseline;
+2. apply the migration through the intended path;
+3. verify behavior, data, errors, permissions, and operational signals at the required boundary;
+4. confirm rollback or forward recovery remains possible;
+5. preserve evidence and account for remaining units.
+
+Decide each next step by criteria set before the unit began, using the advance, hold and abort vocabulary in Deliver Work's [launch](../../deliver-work/references/launch.md); the owner decides consequential thresholds and acceptable degradation.
+
+Code search alone cannot prove completion when runtime, external, dormant, generated, offline, or independently deployed consumers may exist. Stop and report the evidence, taking any choice it leaves to the user through Discuss Work, when replacement behavior diverges, unknown consumers appear, a new owner decision is needed, data cannot be reconciled, recovery assumptions fail, compatibility machinery spreads, or the next safe unit is unclear. Keep completed units; do not restart the whole migration.
+
+## Remove The Old Path
+
+Remove or disable the old path only when that stage is explicitly authorized and the removal proof holds, combining the strongest available evidence:
+
+1. no supported consumer, active or dormant, still requires the old contract;
+2. runtime, telemetry or owner evidence covers consumers static analysis cannot see;
+3. data and configuration are reconciled;
+4. compatibility, support-window, observation and rollback obligations have ended;
+5. the replacement stays verified with the old path disabled or absent;
+6. old code, adapters, flags, tests, docs, alerts, dashboards, secrets, jobs and configuration are classified for removal or retention, and removal erases no required history, audit evidence or recovery material.
+
+If a consumer class cannot be observed, state the uncertainty and obtain the owning decision before destructive removal. Do not delete source truth or historical migration evidence to make searches clean. When current docs or contracts would become false, report them, and update them when the approved scope includes them.
+
+## Verify, Deliver And Report
+
+Use [Verify Work](../../verify-work/SKILL.md) for each unit, compatibility, reconciliation and absence claim: "the new path passes" does not prove "the old path is unused". Propose an independent review through Review Work when the migration changes public contracts, moves consequential data, crosses security or privacy boundaries, affects many consumers, or performs an irreversible cutover or cleanup.
+
+Publishing the replacement as a versioned artifact, and any stage that changes production traffic, data, configuration or exposure, including the rollout and the old path's removal from production, go through [Deliver Work](../../deliver-work/SKILL.md), each within its own yes.
+
+Report the approved scope and completed units; replacement and compatibility status; remaining consumers, state, traffic or observation windows; verification and operational evidence; rollback or forward-recovery status; legacy parts removed and deliberately kept; unresolved decisions and residual risk; and the next approved unit, removal boundary, deferral or stop. Removal is complete only when its separate authorization and proof are satisfied.

package/skills/execute-work/references/simplify.md

@@ -0,0 +1,65 @@
+# Simplify
+
+Read this when behavior-preserving cleanup, refactoring or deletion is the agreed result.
+
+This reference is judgment: adapt it to the code in front of you. It supplies a behavior-preserving transformation under Execute Work; it does not define behavior, authorize redesign, or turn nearby cleanup into accepted work.
+
+Remove one named source of complexity while preserving accepted behavior. Judge simplicity by the concepts and coordination a reader must hold, not by line, file, or abstraction count.
+
+## Establish What Must Stay True
+
+Before editing, identify:
+
+- the accepted behavior, relevant callers, and failure semantics;
+- a reliable baseline that would detect a change;
+- the complexity or coordination to remove;
+- why the current structure exists, including compatibility, platform, performance, migration, and recovery constraints.
+
+If expected behavior is unclear or should change, settle it through [Discuss Work](../../discuss-work/SKILL.md); if current behavior or a failure is unexplained, [diagnose](diagnose.md) first. Do not characterize an invented expectation. When protection is missing, establish the smallest useful observation of behavior before transforming it ([Test Design](../../verify-work/references/test-design.md) when you design that check). Characterization protects required stable behavior, not every accidental implementation detail.
+
+Take a change to interfaces, ownership, public state, or failure behavior to Discuss Work, with [design](design.md) as the lens. Do not disguise a redesign as cleanup.
+
+## Select One Coherent Transformation
+
+Name the actual complexity: a confusing expression, name, branch or temporary state; a pass-through wrapper that hides no decision; generalized machinery with no accepted variation; a scattered concept that can have one owner without changing its contract; an unused, superseded, unreachable or impossible path; or structural pressure that needs a separately agreed boundary change.
+
+Choose the smallest complete transformation that removes it, and keep related edits together even across files. Incidental local cleanup inside implementation needs no separate method; this one applies when reducing complexity is itself the agreed result. Fewer helpers are not better if their removal spreads lifecycle or error-handling knowledge into callers.
+
+Candidate patterns, to compare against the named complexity rather than to apply because they exist:
+
+- **Control flow:** guard clauses where exits are truly equivalent; one named path for duplicate branches; an explicit model or dispatcher when the same shape is branched on across callers; a named intermediate for a dense expression. Keep straightforward branching when a lookup table or hierarchy would add concepts.
+- **Locality:** move behavior toward the state or policy it owns; gather scattered validation, normalization or failure handling behind one stable seam; separate orchestration from business rules when each then reads and tests on its own; reuse a canonical helper instead of a near-duplicate. Do not centralize unrelated behavior because its syntax looks alike.
+- **Indirection:** question pass-through wrappers, one-use factories and strategy layers, aliases that no longer protect compatibility, helpers whose interface is as complex as their body, extension points with no accepted variation, and adapters that outlived a migration. Keep indirection that hides a volatile dependency, enforces policy, preserves a real compatibility contract, or creates real test and change locality.
+- **Names and types:** rename generic or misleading terms to the domain's language; make an invariant explicit at a type or interface boundary when that removes downstream checks; remove casts, optionality and silent fallbacks only after proving the stronger invariant.
+- **Duplication:** harmful when one behavior must change in several places and can drift. First confirm two snippets are the same concept that should evolve together; a little explicit repetition can be simpler than an abstraction with flags, callbacks or hidden coupling.
+
+## Apply And Observe
+
+Within the existing agreement:
+
+1. State which concepts or coordination will disappear.
+2. Make the complete behavior-preserving change.
+3. Run focused behavior and failure checks.
+4. Inspect the real caller path and the resulting code.
+5. Compare the required coordination before and after.
+6. Keep the supported result, or return a failed transformation for correction or covered rollback.
+
+Preserve inputs and outputs, side effects and ordering, errors and recovery, relevant timing and resources, permissions, compatibility, and externally visible state. Follow repository conventions, not personal style. Do not combine feature work, bug fixes, new edge-case behavior, public contract changes, broad modernization, or unrelated cleanup with the transformation.
+
+## Read Checks Without Protecting Accidental Machinery
+
+Use [Verify Work](../../verify-work/SKILL.md) for what the observations establish; a green suite cannot prove unchanged behavior it did not exercise. When an implementation-detail check fails while caller behavior looks unchanged, establish whether the detail is contractual, the check is stale or over-coupled, the transformation changed behavior, or the observer is inadequate. Do not infer the answer from the cleanup you want, and do not rewrite a valid behavioral assertion to make the refactor pass. Retain or add independent checks where needed, and inspect the changed behavior rather than report only test counts.
+
+## Delete Only With Supported Absence
+
+Before removing code, establish its purpose and current consumers through source, runtime registration, configuration, generated callers, tests, history, and compatibility obligations. Execute Work's [touch-map](../scripts/touch-map.mjs) lists the local ones for each symbol or file, with what it did not search. An empty local search does not establish the absence of external or dormant consumers.
+
+Truly dead local code may go within the agreed boundary. Supported legacy behavior, and compatibility, fallback, platform, migration, audit or recovery behavior that only looks redundant, needs consumer evidence first; read [migration](migration.md) when removal carries consumer, state or compatibility obligations. Historical docs and evidence are not dead code; do not delete them to make a search clean. Commented-out code normally belongs in version history, unless it is an intentional operational instruction.
+
+## Judge The Result And Stop
+
+Ask whether there are fewer concepts and branches to coordinate, clearer ownership, fewer related edit locations, visible failure semantics, a smaller or unchanged public interface, and tests focused on behavior rather than internal choreography. If the result is shorter but harder to understand, test, or change, complexity was relocated rather than reduced.
+
+Stop and return the changed boundary when unchanged behavior is unsupported, public or failure semantics changed, a resource trade-off is unmeasured, source truth conflicts, or each correction exposes another ownership or edge-case problem. Do not extend cleanup to rescue a failing approach.
+
+When the named complexity is gone and the behavior boundary is supported, report the protected behavior, the concepts removed, before and after evidence and its limits, comment changes, and complexity deliberately kept. Begin no further cleanup and claim no broader modernization from this result.