npm - @hassangameryt/freeflow - Versions diffs - 0.7.3 → 0.9.0 - Mend

@hassangameryt/freeflow 0.7.3 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (426) hide show

package/skills/design-for-depth/references/software-design-philosophy.md DELETED Viewed

@@ -1,202 +0,0 @@
-# Software Design Philosophy
-Read this when structural pressure is supported but the likely-changing decision or missing information-hiding boundary cannot yet be named.
-Use only the principle that identifies the missing ownership. Do not produce a literature review, pattern catalog, or system-wide redesign.
-## Complexity Is Coordination
-Complexity is not line count. It appears as:
-- **Change amplification:** one behavior change requires many surrounding edits.
-- **Cognitive load:** callers must remember many facts to use the module correctly.
-- **Obscurity:** important rules or ownership are difficult to discover.
-- **Dependency burden:** safe change requires understanding unrelated modules.
-- **Unknown unknowns:** a caller cannot tell what else it must inspect.
-A large implementation can be simple to use. A small helper can be complex when every caller must know its quirks.
-Ask:
-- What must a future caller or maintainer know?
-- How many locations must change together?
-- Which important facts are difficult to discover?
-- Which dependencies must be inspected before a safe change?
-## Deep Modules
-A deep module provides substantial coherent behavior through a small interface.
-Callers state the outcome they need. The module owns:
-- sequencing;
-- likely-changing policy;
-- internal state transitions;
-- cleanup;
-- provider mechanics;
-- internal failure handling.
-A wrapper is not deep merely because it hides lines. It is deep when callers stop knowing concepts or coordinating protocol.
-Depth is not breadth. A god module hiding unrelated decisions is not deep.
-## Strategic And Tactical Design
-A tactical change makes the current patch fit.
-A strategic change spends proportionate effort so that the next likely change remains local and correct use remains simple.
-Do not redesign everything in anticipation of the future. Do stop when the current patch clearly:
-- spreads a likely-changing decision;
-- adds caller protocol;
-- exposes internal state;
-- creates another required workaround;
-- makes the next accepted change materially harder.
-Strategic design is proportionate investment, not maximal architecture.
-## Hide Likely-Changing Decisions
-Organize modules around decisions likely to change, not merely processing steps.
-Instead of exposing:
-```text
-parse -> validate -> retry -> send -> log -> clean up
-```
-look for the decision those steps implement:
-```text
-notification delivery policy
-```
-Ask:
-- What decision would cause the most surrounding edits if it changed?
-- Which callers currently know it?
-- Who should own it?
-- What outcome-level interface would let callers stop knowing it?
-- Is the decision accepted or still user-owned?
-Failure and recovery policy are often likely-changing decisions.
-## Preserve Conceptual Integrity
-A module should express one coherent model of its outcome, state, and failure behavior.
-Pressure exists when:
-- the same concept has different names or rules across callers;
-- several modules partially own the same decision;
-- one module exposes unrelated mental models;
-- callers translate between incompatible representations;
-- each feature adds another exception to the shared concept.
-Prefer one clear ownership model over several locally convenient but incompatible ones.
-Conceptual integrity does not mean one module or one abstraction. It means related behavior follows one coherent set of decisions.
-## Use Seams And Enabling Points For Real Leverage
-A seam allows behavior, dependencies, or observation to change without editing surrounding code.
-An enabling point supplies the variation:
-- adapter;
-- provider;
-- fake;
-- clock;
-- probe;
-- policy;
-- migration implementation.
-Good seams correspond to:
-- demonstrated provider or environment variation;
-- known migration;
-- dependency control required by tests;
-- observation or fault injection;
-- policy that changes independently from infrastructure.
-Weak seams:
-- wrap one stable call;
-- add factories without ownership;
-- expose provider quirks through generic names;
-- exist only to mock internals while the caller interface remains awkward.
-## Separate Policy From Infrastructure
-When infrastructure details leak into product or domain policy, use a boundary where:
-```text
-policy requests outcome
--> adapter performs provider mechanics
-```
-Examples:
-- billing policy should not depend on payment-provider error names;
-- notification policy should not be repeated in each provider call;
-- permission semantics should not depend on database representation;
-- user-flow state should not depend on browser event plumbing.
-Do not add ports and adapters around every stable library call. The boundary is useful only when it hides policy, variation, or mechanics callers should not own.
-## Treat Observable Facts As Contracts
-Callers may depend on any observable:
-- flag;
-- path;
-- state;
-- error;
-- timing rule;
-- fallback;
-- ordering behavior;
-- filename;
-- retry count.
-Expose a fact only when:
-- the caller owns the decision;
-- correct use requires it;
-- it is stable enough to support;
-- its compatibility cost is understood.
-Public flexibility has lasting coordination cost. Prefer one outcome-level operation over a toolkit that requires callers to reconstruct the lifecycle.
-## Separate Required Capability From Speculation
-Classify proposed mechanisms as:
-- **Trust:** required to know the result is valid.
-- **Safety:** prevents damage, leakage, or runaway behavior.
-- **Efficiency:** saves time, requests, or money.
-- **Scale:** supports concurrency or volume.
-- **Portability:** supports additional environments or providers.
-Required trust and safety cannot be deferred merely to simplify the design.
-Efficiency, scale, and portability require accepted requirements or observed pressure. Do not turn imagined future variation into present interface cost.
-## Name The Missing Boundary
-Use supported evidence to state:
-```text
-Outcome:
-Coordination currently spread across:
-Likely-changing decision:
-Current owners:
-Proposed owner:
-What callers would stop knowing:
-Failure unit:
-Evidence still missing:
-```
-If the decision cannot yet be named, define one bounded learning question. Do not create a generic abstraction as a substitute for understanding.
-Stop once the missing decision or boundary is named—or evidence shows no worthwhile boundary change is supported.

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

@@ -1,136 +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.
-Do not apply this reference 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:
-- canonical state and owner;
-- material invariants;
-- transition and visibility boundary;
-- failure unit;
-- forbidden partial outcomes;
-- retry, resume, replay, and recovery capabilities actually required;
-- evidence and remaining uncertainty;
-- narrowest supported route.
-Stop when state and failure ownership are sufficient for the current design decision. Do not design every theoretical failure mode.

package/skills/diagnose-failure/SKILL.md DELETED Viewed

@@ -1,125 +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.
-## Enter For An Unsettled Cause
-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](../../skills/workflow/SKILL.md). 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
-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 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.
-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.
-## Choose A Distinguishing Observation
-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.
-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.
-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
-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.
-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 identify its missing causal link. Do not claim certainty from one consistent observation.
-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
-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 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.
-Classify only the owning cause supported by evidence:
-- 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.
-## Protect Evidence And Contain Harm
-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.
-Temporary instrumentation must distinguish hypotheses. Keep it isolated and state its observer, mutation/performance impact, 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. Report mitigation as containment, not resolution.
-A requested experimental patch can generate evidence when authorized as learning. It does not automatically select production behavior or authorize continuing beyond its question.
-## Return A Supported Correction Boundary
-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 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](../../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.
-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. Do not claim fixed when only mitigation succeeded or the reported boundary remains unverified.

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

@@ -1,48 +0,0 @@
-# Diagnostic Loop Catalog
-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
-- **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 DELETED Viewed

@@ -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.
-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.
-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.
-## 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.