@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/design-for-depth/references/state-and-failure-boundaries.md

@@ -1,125 +0,0 @@
-# State And Failure Boundaries
-
-Read this when correctness materially depends on canonical state, partial effects, atomic visibility, concurrency, cancellation, retries, recovery, reconciliation, or evidence of the final outcome.
-
-This reference is judgment. 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.
-
-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
-
-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.

package/skills/diagnose-failure/SKILL.md

@@ -1,140 +0,0 @@
----
-name: diagnose-failure
-description: "Use when a bug, failure, regression, performance problem, or repeated unsuccessful correction lacks a supported cause."
----
-
-# Diagnose Failure
-
-Establish what fails and why before selecting a correction. A supported cause distinguishes meaningful alternatives well enough to bound the next action; it does not require impossible certainty.
-
-A plausible path, requested patch, reviewer theory, or favorable rerun is not a supported cause. Diagnosis owns the causal question, interpretation, and correction boundary, not authority to run experiments or change production.
-
-The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
-
-## Rules
-
-- Never invent the expected behavior. When accepted behavior or source truth is unsettled, use [Decision Gate](../../skills/decision-gate/SKILL.md) before diagnosing against it.
-- Before active evidence generation, confirm that the work agreement covers the path, environment, repetition, instrumentation, cost, sensitive-data handling, and cleanup or recovery. Covered bug investigation needs no extra permission solely because it is diagnosis. Otherwise return the proposed observation and stop condition to [Workflow](../../skills/workflow/SKILL.md) 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 mitigation succeeded or the reported boundary remains unverified.
-- If a remedy changes scope, compatibility, public behavior, failure semantics, or another user-owned boundary, return its concrete consequence and alternatives through Workflow before adopting it.
-
-## Enter For An Unsettled Cause
-
-Goal: diagnose when the cause is genuinely unknown, and not otherwise.
-
-Use diagnosis for unexplained bugs, failed checks, regressions, flaky or environmental behavior, contradictory observations, and corrections that repeatedly fail or expose related coordination.
-
-Do not investigate an ordinary mistake when fresh evidence already establishes a clear local defect and the accepted remedy; return that correction to Workflow. Finding count, or several bugs in one area, does not establish a shared structural cause.
-
-Keep diagnosis within the same coherent Slice. Use [Track Work](../../skills/track-work/SKILL.md) when continuity requires preserving the hypothesis, discriminating evidence, rejected approaches, blocker, and next useful action. Do not record every trial.
-
-## Establish The Failure, Not The Proposed Fix
-
-Goal: know exactly what fails, against what expectation, at what boundary.
-
-Identify only what the investigation needs:
-
-- accepted expected behavior and its source;
-- observed symptom and available counterevidence;
-- relevant input, state, environment, timing, and reported path;
-- the strongest boundary actually observed;
-- any difference between that boundary and the reported failure.
-
-Prefer the reported path and environment. A nearby symptom may suggest a hypothesis but does not reproduce the reported defect; state reduced-fidelity limits explicitly.
-
-Allowed behavior is not a bug: a cache hit does not establish 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
-
-Goal: the next observation can tell the viable explanations apart.
-
-State a falsifiable leading explanation and only the viable alternatives the next observation must distinguish:
-
-```text
-Hypothesis:
-Predicted observation:
-What would contradict it:
-Meaningful alternative:
-```
-
-Choose a repeatable diagnostic 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 of necessity.
-
-Read [Diagnostic Loop Catalog](references/diagnostic-loop-catalog.md) when the exact loop is not obvious or several loop shapes are plausible. Read [Flaky and Performance Diagnosis](references/flaky-and-performance-diagnosis.md) when timing, randomness, environment, concurrency, or resources shape the failure.
-
-Use [Action Selection](../../skills/action-selection/SKILL.md) when tools, targets, or observers for the selected causal question remain uncertain or broad. Stop reading when adequate context supports the experiment; the objective is not exhaustive understanding of the subsystem.
-
-If no safe useful observer is available, report the smallest missing input, trace, environment, permission, or instrumentation rather than patching a guess.
-
-## Interpret One Iteration
-
-Goal: each observation moves the causal question, and its meaning is not overstated.
-
-Run one covered observation, changing one distinguishing variable at a time. Use [Verify Work](../../skills/verify-work/SKILL.md) for its claim-and-boundary method when needed; diagnosis keeps ownership of causal inference.
-
-Keep three results separate:
-
-- **Check result:** Passed, Failed, Error, or Unavailable under Verify Work's assertion-relative meanings. Observing an expected target failure can be a Passed check.
-- **Hypothesis result:** Supported, Contradicted, Inconclusive, or Unavailable at the stated observing boundary.
-- **Cause status:** Supported or Unresolved.
-
-A supported hypothesis need not establish the cause. A useful supported cause connects trigger and state through mechanism to the symptom, predicts the observations, materially weakens viable alternatives, and is sufficient to bound a correction without guessing. If only the strongest remaining hypothesis is supported, say so and name its missing causal link; one consistent observation is not certainty.
-
-Route from the result:
-
-- Check Error -> repair or replace the observer, not production.
-- Check Unavailable -> return the missing evidence or authority.
-- Hypothesis Contradicted -> preserve 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 material link or alternative.
-- Cause Supported -> return the correction boundary.
-
-Stop when the cause is sufficiently supported or no covered observation can materially improve the decision. Do not keep investigating merely because stronger certainty is imaginable.
-
-## Keep The Investigation Inside The Task
-
-Goal: the correction serves the accepted outcome, not the investigation's momentum.
-
-Before following another prerequisite, distinguish a limitation of the current observer or approach from a requirement of the accepted outcome. A failed reproduction method is not proof that production needs new infrastructure, stronger guarantees, or a host change.
-
-Choose the smallest supported correction that preserves accepted behavior. Classify only the owning cause the evidence supports:
-
-- local implementation defect;
-- invalid, stale, or inadequate check;
-- environment, dependency, data, timing, or configuration issue;
-- missing observer or evidence;
-- unsettled behavior or source conflict;
-- wrong result, scope, order, or strategy;
-- structural ownership, interface, state, or failure-unit pressure.
-
-Use [Design for Depth](../../skills/design-for-depth/SKILL.md) when causal or direct design evidence establishes structural pressure. It shapes the boundary without re-proving the cause. If design reveals an unsupported causal premise, return to diagnosis with that exact uncertainty.
-
-## Contain Harm And Keep Instrumentation Honest
-
-Goal: the investigation causes no damage and leaves no hidden residue.
-
-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 afterward.
-
-When immediate harm needs containment before diagnosis is settled, return one narrower, reversible mitigation to Workflow. It must preserve evidence, define checking and recovery, and avoid settling undefined behavior.
-
-A requested experimental patch can generate evidence when authorized as learning. It does not select production behavior or authorize continuing beyond its question.
-
-## Return A Supported Correction Boundary
-
-Goal: the next owner can correct the failure without re-diagnosing it.
-
-Return proportionately:
-
-- failure and accepted expectation at the required boundary;
-- observed diagnostic loop, check result, and hypothesis result;
-- causal chain, alternatives weakened, and remaining uncertainty;
-- owning cause and smallest coherent correction;
-- minimized regression signal and the original reported path or strongest available observer;
-- instrumentation, containment, residual effects, and authority limits.
-
-An already-covered correction can return to [Execute Work](../../skills/execute-work/SKILL.md). Preserve the diagnostic evidence and use suitable regression checks without prescribing a formal test-first sequence; use Verify Work to design or classify those checks. Use [Simplify Code](../../skills/simplify-code/SKILL.md) only for an accepted behavior-preserving removal of obsolete or workaround machinery, not as a substitute for the fix.
-
-After correction, verify the minimized regression signal and the original reported path or strongest available observer; a nearby passing test is insufficient. If the fix fails or reveals related shared-state consequences, re-enter the affected causal question before another patch.
-
-Stop with the supported correction, missing evidence, containment boundary, or unresolved decision explicit.

package/skills/diagnose-failure/references/diagnostic-loop-catalog.md

@@ -1,50 +0,0 @@
-# Diagnostic Loop Catalog
-
-Read this when the exact distinguishing loop is not obvious or several loop shapes remain plausible.
-
-This reference is judgment: adapt it to the failure in front of you.
-
-Use it to select the smallest observation whose possible outcomes differ between meaningful hypotheses at the required boundary.
-
-## Common Loops
-
-- **Failing test:** use when 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.
-
-## Predict Before Running
-
-Record only outcomes capable of distinguishing the viable hypotheses:
-
-```text
-Observation outcome | Effect on leading hypothesis | Effect on alternative
-```
-
-If every likely outcome leaves the same hypotheses plausible, the loop is not distinguishing enough. Sharpen the observer or choose another loop before generating evidence.
-
-## Improve The Loop
-
-Prefer a loop that is:
-
-- **Sharper:** observes the reported symptom or hypothesis rather than generic failure.
-- **More representative:** preserves the relevant input, state, environment, and observing boundary.
-- **More distinguishing:** can support one plausible cause while contradicting another.
-- **More deterministic:** pins time, randomness, dependencies, filesystem, or network only when doing so preserves the failure.
-- **Faster:** removes unrelated setup without narrowing the claim.
-- **Safer:** isolates mutation, sanitizes sensitive evidence, and has bounded cleanup or recovery.
-
-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.
-
-## Boundary Examples
-
-- A UI save remains pending: exercise the browser path and inspect the request, console, and rendered state; a reducer unit test does not prove the reported boundary.
-- A registered callback allegedly never runs: invoke or observe the registered entrypoint; calling its helper directly proves only helper behavior.
-- A failure appears only in CI: compare the same input across local and CI configuration before changing timing or adding retries.
-- Two causes fit one symptom: choose an observation whose outcomes differ between them; another generic failure is not distinguishing evidence.
-
-Stop once one loop is selected with predicted distinguishing outcomes. Return it to the main skill; do not execute it from this reference.

package/skills/diagnose-failure/references/flaky-and-performance-diagnosis.md

@@ -1,51 +0,0 @@
-# Flaky And Performance Diagnosis
-
-Read this before selecting or running a diagnostic observation when timing, randomness, environmental variance, concurrency, or resource behavior shapes the failure.
-
-This reference is judgment, with one Rule of its own: 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 is supported.
-
-## 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;
-- 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. State the planned stop condition before running. Preserve every unfavorable result.
-
-One green rerun does not contradict an intermittent-failure hypothesis. One red rerun may establish the symptom but not its cause. Use the aggregate pattern or captured distinguishing event to classify the hypothesis.
-
-Do not loop mutating production behavior merely to improve reproduction.
-
-## Performance Problems
-
-Measure the reported path before optimizing it.
-
-Useful causal evidence includes:
-
-- baseline timing or resource use for the representative workload;
-- slow input, dataset, concurrency, cache, and dependency state;
-- profiler, flamegraph, query plan, allocation profile, or browser trace;
-- old-versus-new comparison under matched conditions;
-- a benchmark that exercises the dominant work identified by evidence.
-
-A microbenchmark can test a hypothesis but does not explain the reported slowdown unless the isolated operation materially determines the real path. Repeated calls with one object justify memoization only when the reported workload repeats that object and measurement shows the repeated work dominates.
-
-Sanitize production traces and payloads. When safe production evidence is unavailable, use representative non-production evidence and downgrade the claim.
-
-## Boundary Examples
-
-- Twenty green reruns after widening a timeout: the failure was suppressed or became rarer; its cause remains unresolved.
-- A parser microbenchmark improves while the representative trace is dominated by database waiting: the benchmark does not explain the reported slowdown.
-- Median latency improves while tail latency or memory crosses the accepted boundary: the performance claim remains contradicted or incomplete.
-
-After an authorized correction, verify that the representative baseline improves and required behavior remains correct. Report variance and relevant resource tradeoffs 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. Return the evidence and limit to the main skill.

package/skills/discuss/SKILL.md

@@ -1,140 +0,0 @@
----
-name: discuss
-description: "Use when exploring, clarifying, or revisiting what to accomplish or how to approach it, especially when user collaboration, alternatives, assumptions, or new evidence could change the next action."
----
-
-# Discuss
-
-Build enough shared understanding to choose the next sound action. Discussion can establish both what to accomplish and how to approach it; it need not end at requirements or continue until every implementation detail is known.
-
-Discuss owns exploration, alternatives, assumptions, and direction.
-
-The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
-
-## Rules
-
-- Conversation, convergence, a recommendation, or a recorded proposal never authorizes execution. Begin implementation only under an execution agreement established through [Workflow](../workflow/SKILL.md).
-- Keep supported facts and explicit decisions distinct from hypotheses, proposed mechanisms, and unresolved choices. An assistant recommendation never becomes a requirement because it is repeated or recorded.
-- Leave priorities, behavior, constraints, and tradeoffs the user owns to the user; ask rather than decide them.
-- Never weaken required behavior to make an approach look simpler.
-- A successful demonstration is not production acceptance; promotion must be deliberately selected and its effects authorized.
-
-## Start From The User's Intent
-
-Goal: the conversation serves what the user is actually trying to do, at the depth they asked for.
-
-Respond to the substance before steering the process.
-
-A request to discuss keeps the user involved as understanding develops. Gather relevant existing facts when needed, explain what they imply, and return at the next meaningful question or supported conclusion.
-
-A direct action request may already settle the outcome and delegate approach selection. Do not force a discussion phase when existing evidence can resolve the remaining facts and reversible local choices. Return clear covered work to Workflow.
-
-Use [Decision Gate](../decision-gate/SKILL.md) for one known blocking user-owned choice or source conflict. Use [Diagnose Failure](../diagnose-failure/SKILL.md) when a reported or recurring failure needs a supported cause rather than broader option discussion.
-
-## Separate Outcome From Approach
-
-Goal: know which understanding is missing, what or how, and establish only that.
-
-Identify which understanding is missing:
-
-- **What:** the problem or opportunity, desired result, accepted behavior, constraints, non-goals, and what would count as success.
-- **How:** the mechanism, dependencies, affected boundaries, tradeoffs, and evidence needed to produce that result in the actual environment.
-
-Use [Design for Depth](../design-for-depth/SKILL.md) when representation, identity, ownership, interfaces, algorithms, state, dependencies, or failure behavior materially shape the choice. If unresolved choices could materially change a technical recommendation or invalidate significant dependent work, read its Implementation Decisions method before recommending a mechanism. Use it to explain the differences that matter between viable approaches, not to turn ordinary discussion or a supported local change into an architecture exercise.
-
-These questions can be answered together. Reuse what remains supported instead of running two compulsory discovery passes. A detailed request may settle what while leaving how open; an investigation may reveal that the initial problem description was wrong.
-
-When reopening discussion, name what changed and preserve unaffected understanding. A new local obstacle does not reopen the whole task.
-
-## Gather Context To Answer A Question
-
-Goal: answer the question the discussion needs with the smallest observation that can answer it.
-
-Before inspecting the environment, identify the missing fact and how its answer could change the discussion. Check whether current evidence already supplies it.
-
-Use [Action Selection](../action-selection/SKILL.md) for uncertain or broad inspection. Prefer a focused source, caller, contract, or observation over a repository survey. Read more only when the result leaves a material question unresolved.
-
-Existing code, tests, documentation, policies, artifacts, repository state, supplied material, and current primary sources may settle factual questions. Inspect them rather than asking the user to supply facts available to the agent. Source inspection cannot establish unobserved runtime behavior.
-
-Stop gathering when sufficient evidence supports the next decision. Do not collect every later dependency, reconstruct exhausted history, or prepare an exact implementation plan while the outcome is still open.
-
-## Collaborate And Recommend Proportionately
-
-Goal: the user gets your real judgment, with the tradeoffs that matter, and keeps the choices they own.
-
-Carry your share of the thinking:
-
-- explain what the evidence and intent imply;
-- challenge unsupported claims and consequential assumptions;
-- compare only materially different paths that could realistically be chosen;
-- state what each sacrifices and the assumptions it needs;
-- recommend the best-supported direction and what would change it;
-- revise your position when evidence changes.
-
-Keep one consequential uncertainty in focus; do not conduct a questionnaire or manufacture alternatives for ordinary choices.
-
-Before recommending a new obligation, distinguish a requirement from a limitation of the current approach. Explain consequences in user terms: "requires changing and distributing a patched host," not merely "needs a provenance interface." Include a simpler in-scope alternative when one is supported.
-
-## Frame And Assess A Learning Action
-
-Goal: when evidence cannot settle a question, the smallest experiment that can settle it, and an honest reading of what it showed.
-
-Use an experiment or prototype when existing evidence cannot settle a material question and exercising behavior can distinguish the remaining answers. A separate prototype should isolate the uncertainty more safely or economically than changing production; unfamiliarity alone does not require one.
-
-If the work is an accepted useful outcome regardless of what it teaches, treat it as Delivery or Deepening rather than disguise implementation as Learning. Incidental learning does not change its authority or acceptance boundary.
-
-Frame the action before proposing execution:
-
-- the question and its consequence for the accepted outcome or approach;
-- plausible answers and the observation that would distinguish them;
-- the smallest adequate prototype or observer;
-- permitted effects, environment, and production exclusion;
-- expected evidence and return conditions: question answered, observing limit reached, or further work requiring a different question or expanded scope;
-- what would justify discarding, revising, or proposing promotion.
-
-Add a time or cost boundary when repetition or setup could grow; do not demand an exact token prediction. If no adequate observer is available within scope, state the limitation rather than inventing a proof.
-
-Return the framed action to Workflow for authority and, when needed, [Track Work](../track-work/SKILL.md) preservation, then [Execute Work](../execute-work/SKILL.md) for execution. Existing authority may already cover the experiment; its name does not create another approval gate.
-
-Assess returned evidence against the original question. Negative or inconclusive evidence is a valid result; one failed technique does not prove every alternative impossible. If a new prerequisite is reported, distinguish a limitation of the observer or chosen approach from a requirement of the intended outcome before recommending more work.
-
-Revise only the affected understanding. Preserve the consequence for the task, remaining uncertainty, and exploratory-artifact disposition when continuity matters. Stop assessment when the supported next direction or unresolved decision is clear.
-
-## Preserve A Useful Route When Needed
-
-Goal: when the likely work becomes clear, the route and the understanding behind it survive for whoever continues.
-
-When the likely work becomes clear enough, propose coherent outcomes and their dependencies. Keep near-term work concrete and later work directional. A rough route need not wait for a formal Plan; its order may change as evidence arrives.
-
-Ask whether losing the current understanding, decisions, evidence, proposals, or next action would risk misalignment. If not, keep it in conversation.
-
-If continuity matters, read [Discussion Continuity](references/discussion-continuity.md), then Track Work before record operations. Preserve the state that made memory necessary, not an empty shell or transcript. Keep the outcome separate from the current approach and retain material uncertainty instead of describing proposals as settled work.
-
-Once a record exists, use it as working memory during the discussion, updating it at meaningful boundaries: accepted choices, open questions, options still under consideration, material the user supplies, and the route as it emerges. Track Work describes how.
-
-```text
-Discuss establishes supported meaning
--> Track Work preserves material state
--> Discuss continues or returns the direction to Workflow
-```
-
-The record does not select work or grant authority. When the route includes a commit, a publication, a review, a user decision, or a planned handoff, propose it as a Checkpoint on the route rather than as a separate Slice; Workflow selects it.
-
-## Converge And Return
-
-Goal: end the discussion when the next sound action no longer depends on it, and hand over only what that action needs.
-
-End the current discussion when the next sound action no longer depends on unresolved direction, or when a bounded learning action, missing user decision, wait, or stop is clear. Do not continue merely because more detail could be explored.
-
-When the user requests execution, return to Workflow to establish its outcome, scope, and user-facing return condition. If the user delegates the remaining investigation and implementation, do not require them to finish planning it. Context gathered during discussion counts toward preparing the route; do not repeat it, and gather what the route still needs before the first production change.
-
-Return only what the next route needs: supported understanding, tentative approach, material open questions, relevant evidence, recommended or accepted next action, continuity, and authority state.
-
-- Stable accepted content needing a durable source -> [Write Spec](../write-spec/SKILL.md).
-- A supported ordered strategy needing a durable artifact -> [Write Plan](../write-plan/SKILL.md).
-- Covered concrete work -> Workflow and Execute Work.
-- One blocking owner choice -> Decision Gate.
-- Unsupported failure cause -> Diagnose Failure.
-- No action needed -> answer or stop.
-
-Neither an artifact nor a planning milestone is mandatory. Stop recommending or preserving once the agreed discussion result is supported.