@hassangameryt/freeflow 0.7.1 → 0.7.2

package/skills/diagnose-failure/SKILL.md

@@ -1,257 +1,125 @@
 ---
 name: diagnose-failure
-description: Use when a bug, failure, regression, performance problem, or repeated unsuccessful correction lacks a supported cause.
+description: "Use when a bug, failure, regression, performance problem, or repeated unsuccessful correction lacks a supported cause."
 ---
 
 # Diagnose Failure
 
-Establish what is failing and why before selecting a correction.
+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 **diagnostic loop** is a repeatable observation that can support, contradict, or leave unresolved a hypothesis at the boundary where the failure matters.
+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.
 
-A **supported cause** is a causal explanation strong enough to distinguish meaningful alternatives and bound the next action. It does not require impossible certainty.
+## Enter For An Unsettled Cause
 
-A requested patch, plausible code path, reviewer theory, observation consistent with one hypothesis, or one favorable rerun is not a supported cause.
+Use diagnosis for unexplained bugs, failed checks, regressions, flaky or environmental behavior, contradictory observations, and corrections that repeatedly fail or expose related coordination.
 
-Diagnosis owns the hypothesis, causal interpretation, and correction boundary. It does not authorize active evidence generation or correction.
+Do not investigate an ordinary mistake when fresh evidence already establishes a clear local defect and the accepted remedy. Return that correction to [Workflow](../../skills/workflow/SKILL.md). Finding count or several bugs in one area does not establish a shared structural cause.
 
-## Enter Only When Cause Is Unsettled
+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.
 
-Use diagnosis for:
+## Establish The Failure, Not The Proposed Fix
 
-- an unexplained bug, failed test, regression, or runtime failure;
-- flaky, timing-dependent, environmental, or performance behavior;
-- contradictory evidence;
-- related corrections that keep failing;
-- patches that repeatedly expose additional state or coordination;
-- review findings whose shared cause remains unsupported.
+Identify only what the investigation needs:
 
-Do not diagnose an ordinary mistake when fresh evidence already establishes one clear local defect and accepted behavior is settled. Return that correction to [Workflow](../../skills/workflow/SKILL.md).
-
-Review count, finding count, or several bugs in one area do not by themselves prove a shared or structural cause.
-
-Diagnosis may recur inside one Slice. A new hypothesis or observation does not create a new Slice by itself. When a Working Record exists, use [Track Work](../../skills/track-work/SKILL.md) to preserve the current hypothesis, evidence, blocker, and next distinguishing action.
-
-## Establish The Failure Boundary
-
-Before generating new evidence, identify:
-
-- the failure claim;
 - accepted expected behavior and its source;
-- observed behavior and existing evidence;
-- reported input, state, environment, and reproduction path;
-- the strongest boundary currently observed;
-- differences between the reported path and available reproduction;
-- evidence that already contradicts possible explanations.
-
-Prefer the reported path, environment, and observer. A nearby failure may suggest a hypothesis but does not establish the reported failure.
+- 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.
 
-Reduced-fidelity reproduction remains diagnostic evidence only. State what it cannot prove.
+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 reproduction. A cache hit does not prove a stale-read defect when caching is permitted. A possible race in source does not explain a report until timing, traces, state, or accepted behavior connects it.
+Allowed behavior is not a bug: a cache hit does not establish 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.
 
-## State Competing Hypotheses
+Use [Decision Gate](../../skills/decision-gate/SKILL.md) when accepted behavior or source truth is unsettled. Do not invent an expectation and then diagnose why the implementation violates it.
 
-State one falsifiable leading hypothesis and only the viable alternatives the next observation must distinguish.
+## Choose A Distinguishing Observation
 
-For each, identify:
+State a falsifiable leading explanation and only the viable alternatives the next observation must distinguish:
 
 ```text
 Hypothesis:
 Predicted observation:
-Observation that would contradict it:
+What would contradict it:
 Meaningful alternative:
 ```
 
-Do not create a hypothesis around the requested patch and then use that hypothesis to prove the patch is necessary.
-
-When accepted behavior, source truth, or a user-owned choice is unsettled, use [Decision Gate](../../skills/decision-gate/SKILL.md) rather than diagnosing an invented expectation.
-
-## Choose One Distinguishing Loop
-
-Choose the smallest observation whose possible outcomes differ between the meaningful hypotheses at the required boundary.
-
-When the exact loop is not obvious, or several loop shapes remain plausible, read the [Diagnostic Loop Catalog](references/diagnostic-loop-catalog.md).
-
-When timing, randomness, environmental variance, concurrency, or resource behavior shapes the failure, also read [Flaky and Performance Diagnosis](references/flaky-and-performance-diagnosis.md) before selecting or running the loop.
-
-When several tools or observers could execute the same selected loop, or the likely interaction is broad, use [Action Selection](../../skills/action-selection/SKILL.md). It selects the interaction; Diagnose Failure retains the hypothesis and causal question.
-
-Before an active observation, confirm that the authority envelope covers:
-
-- the exact path and environment;
-- mutation, repetition, instrumentation, and cost;
-- evidence collection and sensitive-data handling;
-- cleanup, rollback, or recovery.
-
-Otherwise return the loop's purpose, expected distinguishing evidence, and stop condition to Workflow and wait.
-
-When no safe useful loop exists, stop with the smallest missing evidence: failing input, command, trace, log window, seed, timestamp, environment, permission, or isolated instrumentation.
-
-## Run And Interpret One Iteration
-
-Run one covered observation and change one distinguishing variable at a time.
-
-Apply [Verify Work](../../skills/verify-work/SKILL.md) when the observation requires its full claim-and-boundary method. Diagnosis retains ownership of causal inference after verification returns the evidence.
-
-Keep three results separate.
-
-### Check Result
-
-How did the selected observation's defined assertion execute?
+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.
 
-Use Verify Work's check-result semantics:
+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.
 
-- **Passed:** the observation executed validly and its assertion held.
-- **Failed:** the observation executed validly and its assertion did not hold.
-- **Error:** the observer or execution was invalid.
-- **Unavailable:** the observation could not be attempted safely or reliably.
+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.
 
-A target path may intentionally fail while the diagnostic check Passes. An Error or Unavailable observer says nothing about the production cause.
+Before active evidence generation, confirm that the 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 and wait.
 
-### Hypothesis Result
+If no safe useful observer is available, report the smallest missing input, trace, environment, permission, or instrumentation rather than patching a guess.
 
-What does the evidence establish about the tested hypothesis?
+## Interpret One Iteration
 
-- **Supported:** direct evidence establishes the hypothesis at its stated boundary.
-- **Contradicted:** evidence shows the hypothesis is false.
-- **Inconclusive:** the observation cannot distinguish it from meaningful alternatives.
-- **Unavailable:** the required evidence cannot currently be obtained.
+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 retains ownership of causal inference.
 
-### Cause Status
+Keep three results separate:
 
-- **Supported:** the evidence establishes a useful causal explanation.
-- **Unresolved:** one or more causal links or meaningful alternatives remain open.
+- **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 does not automatically establish a Supported cause.
+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.
 
-A cause is Supported only when the evidence:
+If only the strongest remaining hypothesis is supported, say so and identify its missing causal link. Do not claim certainty from one consistent observation.
 
-1. establishes the relevant failure or strongest available observer;
-2. behaves as the causal explanation predicts;
-3. materially weakens meaningful alternatives;
-4. connects trigger and state through mechanism to the observed symptom;
-5. is sufficient to bound a correction or other next action without guessing.
+Route from the result:
 
-If evidence supports only the strongest remaining hypothesis, report it as such and identify the observation that would confirm or refute the missing causal link.
+- 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.
 
-## Route From The Iteration
+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.
 
-- **Check Error:** repair or replace the observer; do not change production code.
-- **Check Unavailable:** stop with the missing evidence or authority.
-- **Hypothesis Contradicted:** preserve the evidence, then refine or replace the hypothesis.
-- **Hypothesis Inconclusive:** choose a sharper distinguishing loop.
-- **Hypothesis Supported, cause Unresolved:** test the remaining causal link or alternative.
-- **Cause Supported:** return the causal explanation and correction boundary to Workflow.
-- **Behavior or source conflict:** use Decision Gate.
-- **Supported structural pressure:** apply [Design for Depth](../../skills/design-for-depth/SKILL.md) under the current owner.
-- **Active harm before cause:** return one bounded containment option to Workflow.
+## Keep The Investigation Inside The Task
 
-Do not continue because diagnosis started. Stop when no safe observation can materially improve the route.
+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.
 
-## Protect Diagnostic Evidence
+Choose the smallest supported correction preserving accepted behavior. If the remedy changes scope, compatibility, public behavior, failure semantics, or another user-owned boundary, return the concrete consequence and alternatives through Workflow before adopting it.
 
-Treat logs, traces, payloads, screenshots, dumps, production samples, and browser state as potentially sensitive. Minimize and sanitize them. Do not expose credentials, tokens, unrestricted personal data, or private payloads.
-
-Bound repetition by time, cost, side effects, and environment safety. Do not repeatedly exercise mutating production behavior without explicit authority and an understood recovery boundary.
-
-Temporary instrumentation must distinguish hypotheses. Keep it isolated and state:
-
-- what it observes;
-- mutation or performance impact;
-- cleanup and removal condition;
-- whether it remains after diagnosis.
-
-Preserve contradictory and unfavorable evidence. Do not rerun until it disappears.
-
-## Identify The Owning Cause
-
-Classify only what evidence supports:
+Classify only the owning cause supported by evidence:
 
 - local implementation defect;
 - invalid, stale, or inadequate check;
-- environment, dependency, data, timing, or configuration cause;
-- missing observer or insufficient evidence;
+- environment, dependency, data, timing, or configuration issue;
+- missing observer or evidence;
 - unsettled behavior or source conflict;
-- wrong result, scope, order, or execution strategy;
+- wrong result, scope, order, or strategy;
 - structural ownership, interface, state, or failure-unit pressure.
 
-Diagnosis determines whether observed pressure is causal.
-
-Use Design for Depth only after diagnosis establishes structural pressure, or when direct design evidence independently establishes caller coordination, distributed policy, unowned state, interface leakage, or failure-unit pressure. Design for Depth shapes the supported ownership boundary; it does not re-prove the cause.
-
-If design work exposes an unsupported causal assumption that changes the boundary choice, re-enter diagnosis with that exact assumption and the alternatives it must distinguish.
-
-## Contain Harm Without Claiming A Fix
-
-When immediate harm must be limited before cause is Supported, return one bounded containment option to Workflow.
-
-Containment must:
+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.
 
-- reduce immediate harm;
-- remain narrower and more reversible than a guessed correction;
-- preserve diagnostic evidence;
-- define verification and recovery;
-- avoid settling unresolved behavior;
-- be reported as mitigation, not resolution.
+## Protect Evidence And Contain Harm
 
-A requested patch may instead be an authorized learning action. Its result can strengthen or weaken a hypothesis; it does not become selected production behavior automatically.
+Logs, traces, payloads, dumps, screenshots, and browser state may be sensitive. Minimize and sanitize them; do not expose credentials or unnecessary private data. Bound repetitions by time, cost, effects, and environment safety. Preserve unfavorable evidence rather than rerunning until it disappears.
 
-## Return The Correction Boundary
+Temporary instrumentation must distinguish hypotheses. Keep it isolated and state its observer, mutation/performance impact, removal condition, and whether it remains afterward.
 
-When cause is Supported, return:
+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. Report mitigation as containment, not resolution.
 
-- failure claim and required boundary;
-- diagnostic loop and observation;
-- check result and hypothesis result;
-- causal chain;
-- alternatives weakened and uncertainty remaining;
-- owning cause;
-- smallest coherent correction boundary;
-- minimized regression signal;
-- original reported path or strongest available observer.
+A requested experimental patch can generate evidence when authorized as learning. It does not automatically select production behavior or authorize continuing beyond its question.
 
-The evidence supports the route but does not authorize correction.
+## Return A Supported Correction Boundary
 
-Return an authorized correction to [Execute Work](../../skills/execute-work/SKILL.md). Use [TDD](../../skills/tdd/SKILL.md) when the diagnostic loop supplies a stable failing behavior check. Use [Simplify Code](../../skills/simplify-code/SKILL.md) only when the supported cause shows that obsolete or workaround machinery can be removed without changing accepted behavior. Do not use cleanup in place of correcting the supported failure or while its evidence remains unresolved.
+Return proportionately:
 
-After correction, use Verify Work to check both:
+- 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 original reported path or strongest available observer;
+- instrumentation, containment, residual effects, and authority limits.
 
-1. the minimized regression signal;
-2. the original reported path or strongest available observer.
+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](../../skills/verify-work/SKILL.md) 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.
 
-If correction fails, or exposes related shared-state consequences, re-enter diagnosis before another patch.
-
-Do not claim fixed when only containment succeeded, a nearby check passed, or the original boundary remains unavailable.
-
-## Report Proportionately
-
-For one unresolved iteration:
-
-```text
-Failure @ boundary:
-Diagnostic loop:
-Check result:
-Hypothesis result:
-Cause status: Unresolved
-Next distinguishing evidence:
-```
-
-For a supported cause, containment, conflicting evidence, or a route handoff:
-
-```text
-Failure claim:
-Required boundary:
-Expected / observed:
-Diagnostic loop and evidence:
-Check result:
-Hypothesis result:
-Cause status:
-Causal explanation or strongest remaining hypothesis:
-Alternatives weakened / unresolved:
-Containment or instrumentation:
-Correction boundary or next evidence:
-Post-correction verification:
-```
+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.
 
-Omit fields that do not apply. Stop when the supported route, missing evidence, containment boundary, or unresolved decision is explicit.
+Stop with the supported correction, missing evidence, containment boundary, or unresolved decision explicit. Do not claim fixed when only mitigation succeeded or the reported boundary remains unverified.

package/skills/discuss/SKILL.md

@@ -1,175 +1,116 @@
 ---
 name: discuss
-description: "Use when the user is exploring, challenging, or revisiting what to build or how to proceed, or when assumptions, alternatives, or new evidence leave the next sound action materially uncertain."
+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.
+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. It may shape recommendations, proposed work, and checkpoints. It does not authorize active evidence generation, mutation, delivery, or a user-owned decision.
+Discuss owns exploration, alternatives, assumptions, and direction. It does not turn conversation, a recommendation, or a recorded proposal into execution authority.
 
-## Enter Or Exit Cleanly
+## Start From The User's Intent
 
-Use Discuss when:
+Respond to the substance before steering the process.
 
-- the outcome, boundary, approach, or acceptance remains materially open;
-- several meaningful paths remain viable;
-- an assumption or earlier direction needs reconsideration;
-- new evidence makes the next route uncertain.
+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. Do not treat convergence as permission to implement.
 
-Do not turn every interaction into a discussion phase. If the user asks a direct factual question, provides a clear bounded request, or gives feedback that does not reopen direction, answer or return the request to Workflow.
+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](../workflow/SKILL.md).
 
-When one known user-owned choice or source conflict blocks progress, use [Decision Gate](../decision-gate/SKILL.md). When a failure lacks a supported cause or keeps recurring, use [Diagnose Failure](../diagnose-failure/SKILL.md).
+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.
 
-## Discuss Like A Collaborator
+## Separate Outcome From Approach
 
-Respond to the user’s substance before steering the conversation.
+Identify which understanding is missing:
 
-Carry your share of the thinking:
-
-- interpret what the current evidence and intent imply;
-- expose consequential assumptions and tradeoffs;
-- challenge claims when evidence or engineering judgment warrants it;
-- recommend a direction when one is better supported;
-- revise your position plainly when new reasoning or evidence changes it.
-
-Ask only questions whose answers could materially change the route and which available evidence cannot answer. Ask the user about intent, priorities, constraints, and tradeoffs they own. Do not make the user answer factual questions that existing sources can resolve.
-
-Keep one consequential uncertainty in focus. Do not conduct a questionnaire, manufacture alternatives, repeat accepted context, or continue arguing for a rejected path without new evidence.
-
-## Follow The Discussion Loop
-
-```text
-Orient from what remains true
--> respond to the current substance
--> focus the uncertainty that could change the route
--> inspect facts, ask about intent, or compare meaningful paths
--> determine what is now supported
-   -> continue discussion
-   -> learn through bounded action
-   -> decide continuity
-   -> route the supported result
-```
-
-Use this as a feedback loop, not a user-facing checklist.
-
-## Orient Without Restarting
+- **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.
 
-Identify only what the next decision needs:
+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.
 
-- the goal and current direction;
-- supported facts and explicit decisions;
-- tentative assumptions or viable alternatives;
-- open questions capable of changing the route;
-- evidence that still matters.
+Keep supported facts and explicit decisions distinct from hypotheses, proposed mechanisms, and unresolved choices. Do not turn an assistant recommendation into a requirement because it is repeated or recorded.
 
-Keep these distinctions available:
+When reopening discussion, name what changed and preserve unaffected understanding. A new local obstacle does not reopen the whole task.
 
-- **Settled:** supported fact or explicit decision.
-- **Tentative:** live hypothesis or provisional direction.
-- **Open:** unresolved and capable of changing the next action.
+## Gather Context To Answer A Question
 
-Use those labels in the response only when they make a transition or summary clearer. Do not turn every discussion turn into a status report.
+Before inspecting the environment, identify the missing fact and how its answer could change the discussion. Check whether current evidence already supplies it.
 
-When discussion reopens after implementation, feedback, verification, review, or failure, preserve what still holds and revisit only the affected assumption, decision, or direction.
+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.
 
-When a Working Record exists, read [Track Work](../track-work/SKILL.md) before any record operation. Recover the relevant current state, reconcile it with current user direction and live evidence, and return to the question that actually changed. Memory does not override contradictory evidence or current intent.
+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.
 
-## Resolve What Conversation Can Resolve
+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.
 
-Inspect existing code, tests, documentation, policies, artifacts, repository state, supplied material, or current primary sources when they can answer a factual question without exercising target behavior or changing state.
+## Collaborate And Recommend Proportionately
 
-When several observations could answer the same question, or the likely inspection is broad, use [Action Selection](../action-selection/SKILL.md) to choose the smallest discriminating observation.
+Carry your share of the thinking:
 
-When materially different paths remain viable:
+- 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.
 
-1. compare only the paths that could realistically be chosen;
-2. state what each optimizes and what it sacrifices;
-3. identify the assumptions on which each path depends;
-4. recommend the best-supported direction;
-5. state what evidence or changed priority would alter that recommendation.
+Ask about priorities, behavior, constraints, and tradeoffs the user owns. Keep one consequential uncertainty in focus; do not conduct a questionnaire or manufacture alternatives for ordinary choices.
 
-When architecture, interfaces, ownership, state, or failure behavior shapes the direction, use [Design for Depth](../design-for-depth/SKILL.md) as a lens.
+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. Do not weaken required behavior to make an approach look simpler.
 
-Converge when the next sound action no longer depends on unresolved direction. Do not continue discussion merely because more detail could be explored.
+Use [Design for Depth](../design-for-depth/SKILL.md) when ownership, interfaces, state, dependencies, or failure behavior materially shape the choice. A lens is not a reason to design a broader system.
 
-## Learn Through Bounded Action
+## Frame And Assess A Learning Action
 
-Do not keep reasoning about an empirical uncertainty when a small, reversible experiment can discriminate between the remaining hypotheses.
+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.
 
-Use a Learning action when:
+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.
 
-- accepted evidence and passive inspection cannot answer a material question;
-- exercising behavior, building a prototype, testing an assumption, or writing disposable code can answer it;
-- the expected information can change the direction;
-- the action can be bounded by evidence and a stop condition.
+Frame the action before proposing execution:
 
-Propose:
+- 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.
 
-```text
-Question or hypothesis:
-Smallest discriminating action:
-Reversible effects and production boundary:
-Expected evidence:
-Stop and return when:
-Discard, revise, or propose promotion when:
-```
+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.
 
-A learning proposal does not authorize execution. Before returning it to Workflow, decide whether its context needs durable preservation. Workflow confirms authority and routes covered work through [Track Work](../track-work/SKILL.md) when needed and then [Execute Work](../execute-work/SKILL.md).
+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.
 
-Return the result to Discuss. Treat prototypes, tests, benchmarks, sketches, and working behavior as evidence—not automatic approval of their design or promotion into production.
+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.
 
-If the work remains valuable as an accepted outcome regardless of what it teaches, propose a Delivery or Deepening result instead of disguising it as Learning.
+Revise only the affected understanding. Preserve the consequence for the task, remaining uncertainty, and exploratory-artifact disposition when continuity matters. A successful demonstration is not production acceptance; promotion must be deliberately selected and its effects authorized. Stop assessment when the supported next direction or unresolved decision is clear.
 
-## Decide Continuity Before Leaving
+## Preserve A Useful Route When Needed
 
-Before discussion hands off a supported direction, ask:
+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.
 
-> Would losing the current understanding, decisions, evidence, proposals, or next action risk later misalignment?
+Ask whether losing the current understanding, decisions, evidence, proposals, or next action would risk misalignment. If not, keep it in conversation.
 
-If no, keep the state in conversation.
-
-If yes, read [Discussion Continuity](references/discussion-continuity.md) before choosing or preserving the durable destination. When a Working Record is appropriate:
+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.
 
 ```text
-Discuss
--> material supported state
--> Track Work update
--> Discuss
--> Workflow
+Discuss establishes supported meaning
+-> Track Work preserves material state
+-> Discuss continues or returns the direction to Workflow
 ```
 
-Discuss decides what the state means and whether it needs continuity. Track Work owns the Working Record and its lifecycle. A record update does not end discussion, authorize work, select a proposal, or change the owning route.
-
-Do not create a Working Record for a short disposable exchange or one clear direct result merely because discussion occurred. Reconsider the decision if a small task develops durable decisions, several outcomes, repeated feedback, checkpoints, or context-loss risk.
-
-## Shape Checkpoints Sparingly
-
-Recommend a user decision, independent review, local commit, or continuity checkpoint only when crossing that boundary unresolved could materially endanger dependent work.
-
-Discussion may propose a checkpoint. Workflow selects it. Track Work preserves it when durable memory is needed. A recommendation or recorded checkpoint does not authorize the action it describes.
-
-## Return Supported Direction
+The record does not select work or grant authority. Propose independent review, a local commit, a user decision, or a continuity checkpoint only when it protects a material boundary; Workflow selects it.
 
-Return to [Workflow](../workflow/SKILL.md) with the concepts the next route needs:
+## Converge And Return
 
-- current shared understanding;
-- settled and tentative direction;
-- open questions that still change the route;
-- recommended next action or bounded proposal;
-- continuity decision;
-- authority state and selected checkpoint, when any.
+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.
 
-Use natural prose unless structured state materially improves continuity.
+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.
 
-Route narrowly:
+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.
 
-- one user-owned choice or source conflict -> Decision Gate;
-- unexplained or repeated failure -> Diagnose Failure;
-- stable accepted content -> [Write Spec](../write-spec/SKILL.md);
-- stable ordered strategy -> [Write Plan](../write-plan/SKILL.md);
-- covered bounded work -> Workflow and Execute Work;
-- no action needed -> answer or stop.
+- 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.
 
-If work is recommended but not authorized, state the exact proposal and wait.
+Neither an artifact nor a planning milestone is mandatory. Stop recommending or preserving once the agreed discussion result is supported; do not begin implementation without the execution agreement.