@hassangameryt/freeflow 0.5.0 → 0.7.0

package/skills/diagnose-failure/SKILL.md

@@ -1,72 +1,168 @@
 ---
 name: diagnose-failure
-description: Use when a bug, failure, regression, performance problem, or repeated unsuccessful fix 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.
 
-A **diagnostic loop** is a repeatable check or observation that can reproduce, support, or contradict the failure claim or current hypothesis at the boundary where it matters. A **supported cause** is a causal explanation strong enough to distinguish meaningful alternatives and choose 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 requested patch, plausible code path, reviewer theory, or one favorable rerun is not a supported cause.
+A **supported cause** is a causal explanation strong enough to distinguish meaningful alternatives and bound the next action. It does not require impossible certainty.
 
-## Follow The Diagnostic Route
+A requested patch, plausible code path, reviewer theory, observation consistent with one hypothesis, or one favorable rerun is not a supported cause.
+
+Diagnosis owns the hypothesis, causal interpretation, and correction boundary. It does not authorize active evidence generation or correction.
+
+## Enter Only When Cause Is Unsettled
+
+Use diagnosis for:
+
+- 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.
+
+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.
+
+Reduced-fidelity reproduction remains diagnostic evidence only. State what it cannot prove.
+
+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.
+
+## State Competing Hypotheses
+
+State one falsifiable leading hypothesis and only the viable alternatives the next observation must distinguish.
+
+For each, identify:
 
 ```text
-[Failure without a supported cause]
--> [Establish expected and observed behavior]
--> [Choose the smallest diagnostic loop]
--> [Reproduce or capture the failure]
--> [State a falsifiable hypothesis]
--> [Run one distinguishing observation]
--> [Route from evidence]
-   -> hypothesis contradicted -> refine or replace it -> observe again
-   -> evidence unavailable -> stop with the smallest missing evidence
-   -> cause supported -> return cause and correction boundary to Workflow
-   -> user-owned behavior or source conflict -> Decision Gate
-   -> structural cause -> Design for Depth
-   -> active harm before cause -> propose bounded containment
+Hypothesis:
+Predicted observation:
+Observation that would contradict it:
+Meaningful alternative:
 ```
 
-Diagnosis may recur inside one Track Work slice. A new hypothesis, observation, or owning-skill route does not create a new slice by itself.
+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.
 
-## Enter Diagnosis Deliberately
+## Run And Interpret One Iteration
 
-Use this method for unexplained bugs, failed tests, regressions, flaky behavior, performance problems, unexpected runtime behavior, or related corrections that keep failing.
+Run one covered observation and change one distinguishing variable at a time.
 
-Use it for repeated workflow trouble only when evidence suggests an unclear shared cause: related findings keep appearing, verification contradicts successive corrections, edge-case patches expose more states, or coordination spreads through shared ownership. Reaching a review cap alone is not diagnostic evidence.
+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.
 
-If fresh direct evidence already establishes one clear local defect and intended behavior is settled, return the correction to [Workflow](../workflow/SKILL.md). Do not manufacture diagnosis around an ordinary mistake.
+Keep three results separate.
 
-## Establish The Failure And Loop
+### Check Result
 
-Before changing behavior:
+How did the selected observation's defined assertion execute?
 
-1. establish expected behavior from accepted intent and source truth;
-2. reproduce or capture the reported failure at its required boundary;
-3. state a falsifiable hypothesis;
-4. change or observe one distinguishing variable at a time;
-5. trace the causal chain from trigger and state to the observed result;
-6. preserve evidence that contradicts the leading hypothesis.
+Use Verify Work's check-result semantics:
 
-Prefer the reported path, input, environment, and observer. A nearby failure may suggest a hypothesis but does not prove the reported failure. Reduced-fidelity reproduction is diagnostic evidence only; name what it cannot establish.
+- **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.
 
-Read [the diagnostic-loop catalog](references/diagnostic-loop-catalog.md) when the best loop is unclear. Read [flaky and performance diagnosis](references/flaky-and-performance.md) when timing, randomness, environment variance, or resources shape the failure.
+A target path may intentionally fail while the diagnostic check Passes. An Error or Unavailable observer says nothing about the production cause.
 
-Allowed behavior is not a reproduction. A cache hit does not prove a stale-read bug when caching is permitted. A possible race in source does not explain a report until timing, traces, steps, logs, or an existing expectation connect it.
+### Hypothesis Result
 
-Do not invent a check around the requested patch and use that check to prove the patch was needed. Do not rewrite tests, Specs, policies, thresholds, or expected behavior merely to make the signal red or green.
+What does the evidence establish about the tested hypothesis?
 
-When no safe useful loop is possible, stop and name the smallest missing evidence: a command, failing input, trace, log window, timestamped screenshot, environment boundary, or permission for isolated instrumentation. Leave the cause unresolved.
+- **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.
+
+### Cause Status
+
+- **Supported:** the evidence establishes a useful causal explanation.
+- **Unresolved:** one or more causal links or meaningful alternatives remain open.
+
+A Supported hypothesis does not automatically establish a Supported cause.
+
+A cause is Supported only when the evidence:
+
+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.
+
+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.
+
+## Route From The Iteration
+
+- **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.
+
+Do not continue because diagnosis started. Stop when no safe observation can materially improve the route.
 
 ## Protect Diagnostic Evidence
 
-Treat logs, traces, payloads, screenshots, dumps, and production samples as potentially sensitive. Minimize and sanitize them. Do not expose credentials, tokens, unrestricted personal data, or private payloads.
+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.
 
-Bound repeated checks by time, cost, side effects, and environment safety. Do not repeatedly exercise a mutating production path without explicit authority and an understood recovery boundary.
+Temporary instrumentation must distinguish hypotheses. Keep it isolated and state:
 
-Temporary instrumentation must distinguish hypotheses. Keep it isolated, identify its removal condition, and report whether it remains.
+- 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
 
@@ -80,26 +176,82 @@ Classify only what evidence supports:
 - wrong result, scope, order, or execution strategy;
 - structural ownership, interface, state, or failure-unit pressure.
 
-Use [Decision Gate](../decision-gate/SKILL.md) when correction requires a user-owned behavior, risk, compatibility, security, privacy, billing, data-loss, or hard-to-reverse decision.
+Diagnosis determines whether observed pressure is causal.
 
-Use [Design for Depth](../design-for-depth/SKILL.md) only when diagnosis establishes a structural cause or direct evidence already shows caller coordination, state, ownership, interface, or failure-unit pressure. Ordinary bugs and finding count do not prove bad architecture.
+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 evidence supports only the strongest remaining hypothesis, report it as such and name the observation that would confirm or refute it.
+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 harm must be limited before the cause is supported, return one bounded containment option to Workflow. Apply it only when already authorized or explicitly approved.
+When immediate harm must be limited before cause is Supported, return one bounded containment option to Workflow.
+
+Containment must:
 
-Containment must reduce immediate harm without destroying evidence, remain narrower and more reversible than a guessed correction, define verification and recovery, preserve unsettled behavior, and be reported as mitigation rather than resolution.
+- 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.
 
 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.
 
-## Return The Supported Result
+## Return The Correction Boundary
+
+When cause is Supported, return:
 
-When evidence supports a cause, return the failure boundary, diagnostic loop, causal explanation, regression signal, and smallest coherent correction to Workflow. Return an authorized implementation correction to [Execute Work](../execute-work/SKILL.md); use [TDD](../tdd/SKILL.md) when the diagnostic loop provides a failing behavior check that should guide it. Use [Simplify Code](../simplify-code/SKILL.md) when the supported cause shows that obsolete, duplicated, or workaround machinery can be removed while preserving accepted behavior. Mess left by unsuccessful attempts is not enough: settle any behavior or contract change through Workflow first, and do not use cleanup in place of correcting the supported failure or while its evidence remains unresolved. The correction may remain in the current Track Work slice while that slice still has one coherent result.
+- 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.
 
-After correction, use [Verify Work](../verify-work/SKILL.md) to rerun both the minimized regression signal and the original reported path or strongest available observer. If correction fails or exposes related shared-state consequences, re-enter diagnosis before another patch.
+The evidence supports the route but does not authorize correction.
 
-Do not claim fixed when only containment succeeded, a minimized check passed, or the original boundary remains unavailable.
+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.
+
+After correction, use Verify Work to check both:
+
+1. the minimized regression signal;
+2. the original reported path or strongest available observer.
+
+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:
+```
 
-Report the failure claim, required boundary, diagnostic loop and observations, supported cause or strongest remaining hypothesis, active containment or instrumentation, recommended route, verification status, and missing evidence.
+Omit fields that do not apply. Stop when the supported route, missing evidence, containment boundary, or unresolved decision is explicit.

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

@@ -1,6 +1,8 @@
 # Diagnostic Loop Catalog
 
-Read this when the smallest useful diagnostic loop for a reported failure or current hypothesis is unclear.
+Read this when the exact distinguishing loop is not obvious or several loop shapes remain plausible.
+
+Use it to select the smallest observation whose possible outcomes differ between meaningful hypotheses at the required boundary.
 
 ## Common Loops
 
@@ -13,6 +15,16 @@ Read this when the smallest useful diagnostic loop for a reported failure or cur
 - **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:
@@ -28,9 +40,9 @@ An observer must sit on the real path and cover the complete operation. A manual
 
 ## 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.
+- 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.
 
-If no safe useful loop is possible, identify the smallest missing artifact or access: command, logs, trace, failing input, timestamped screenshot, environment boundary, or permission for isolated temporary instrumentation. Leave the cause unresolved rather than substituting a weaker claim.
+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.md → flaky-and-performance-diagnosis.md}

@@ -1,6 +1,8 @@
 # Flaky And Performance Diagnosis
 
-Read this when timing, randomness, environment variance, or resource behavior makes the failure difficult to reproduce or explain.
+Read this before selecting or running a diagnostic observation when timing, randomness, environmental variance, concurrency, or resource behavior shapes the failure.
+
+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
 
@@ -14,7 +16,11 @@ Use, when safe and representative:
 - 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 failure rate. Preserve every unfavorable result. Do not loop mutating production behavior merely to improve reproduction.
+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.
 
 Do not stabilize a flake with arbitrary 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.
 
@@ -36,8 +42,10 @@ Sanitize production traces and payloads. When safe production evidence is unavai
 
 ## Boundary Examples
 
-- Twenty green reruns after widening a timeout → the failure was suppressed or became rarer; its cause is still 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.
+- 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.