@hassangameryt/freeflow 0.5.0 → 0.7.0

package/skills/design-for-depth/references/design-pressure-signals.md

@@ -1,314 +1,182 @@
 # Design Pressure Signals
 
-Use this reference when reviewing code, artifacts, or work for shallow modules and complexity spread.
+Read this when observed coordination could change the next route and an equivalent design-route classification is not already supported.
 
-The goal is not to find every smell. The goal is to notice pressure that changes the next route.
+Do not count smells. Identify the pressure that changes the next action, or conclude that none does.
 
-## Quick Classifier
+## Classify The Evidence
 
 Ask:
 
-1. What is the module?
-2. What is the interface?
-3. What details are callers forced to know?
-4. What decision is likely to change?
-5. Where would that decision be localized?
-6. Would solving this now fit the approved scope?
+1. What caller outcome and interface are affected?
+2. What facts must callers know or coordinate?
+3. Did the current change add to that knowledge?
+4. What policy, dependency, state transition, or failure behavior is spreading?
+5. Is the cause supported?
+6. Can the issue be resolved inside accepted scope and authority?
 
-Then classify:
+Choose the narrowest supported route:
 
-- **Continue:** no design pressure that changes the next action.
-- **Local fix:** improve within current module/interface.
-- **Plan revision:** slice boundary or verification path is wrong.
-- **Discuss or revise a Spec:** behavior, scope, or acceptance is unclear.
-- **Owner decision:** public API, compatibility, security, privacy, billing, data loss, permissions, migration, or hard-to-reverse architecture.
-- **Deferred deepening:** real design pressure, but not worth solving in this scope.
+- **Continue:** current boundary remains sound.
+- **Local correction:** defect remains within one module and contract.
+- **Diagnosis:** failure is repeated or unexplained and cause is unsupported.
+- **Spec or Plan revision:** behavior, acceptance, or execution boundary is incomplete.
+- **User decision:** resolving pressure changes a user-owned outcome.
+- **Learning:** evidence cannot distinguish viable boundaries.
+- **Deepening:** supported information-hiding improvement fits accepted scope.
+- **Deferred deepening:** pressure is real but not worth resolving now.
 
-## Signals And What They Usually Mean
+## Change Amplification
 
-### Shotgun Surgery
+Pressure exists when one policy change requires unrelated edits across callers.
 
-Signal: one concept requires many unrelated edits.
-
-Examples:
-
-- retry policy added to every route;
-- permission check copied into API, UI, and job worker;
-- billing grace-period logic repeated in webhook, email, and dashboard;
-- cache freshness flags threaded through callers.
-
-Likely issue: a likely-changing decision is not hidden behind a module.
-
-Route:
-
-- If behavior or scope is unsettled: Discuss or revise the owning Spec.
-- If behavior is settled but slice spreads edits: plan revision or refactor candidate.
-
-### Caller Choreography
-
-Signal: callers must perform steps in the right order.
-
-Examples:
+Example:
 
 ```text
-open connection -> set retry -> register cleanup -> call provider -> translate error -> log metric
+Changing retry policy requires edits in API routes, workers,
+UI state, and tests.
 ```
 
-Likely issue: interface exposes implementation sequence.
+Name the decision causing the edits. Do not merely move the same choreography into one helper.
+
+## Caller Protocol Growth
 
-Better interface asks for outcome:
+Pressure exists when callers must perform internal lifecycle steps:
 
 ```text
-deliverNotification(invitation)
+configure -> open -> retry -> translate error -> clean up -> publish evidence
 ```
 
-while the module owns retry, fallback, logging, cleanup, and provider errors.
-
-### Scattered Policy
-
-Signal: product or operational rules appear in many places.
-
-Examples:
-
-- billing downgrade timing in UI, webhook, worker, and tests;
-- notification fallback rules in every route;
-- authorization rules in frontend and backend separately;
-- migration compatibility gates inside individual callers.
-
-Likely issue: policy is not localized.
-
-Stop if changing it would alter product, security, privacy, billing, permissions, public API, compatibility, or data-loss behavior.
-
-### Test Knows Too Much
-
-Signal: tests assert implementation sequencing instead of behavior.
-
-Examples:
-
-- tests assert `sendEmail` then `logFailure` then `sendSms` in every route;
-- tests mock five helpers to verify one user-visible behavior;
-- tests duplicate retry counts and provider error types;
-- tests need private methods or internal state.
-
-Likely issue: the production interface is not the right test seam.
-
-Do not automatically add mocks. Ask whether the module interface should own the behavior.
-
-### Missing Failure Contract
-
-Signal: the happy path is planned, but failure modes, observers, state writes, fail-open/closed/degrade/escalate/retry behavior, recovery, or proof are left to each caller or implementer.
-
-Likely issue: failure behavior is part of the interface but has not been designed.
-
-Route:
-
-- If behavior changes product, security, privacy, billing, permissions, public API, compatibility, or data loss: owner decision.
-- If behavior is within scope but scattered: plan/spec revision or refactor candidate.
-- If proof is missing: verification gap before completion claims.
-
-### Caller-Knowledge Growth
-
-Signal: each fix adds another flag, state, path, ordering rule, retry instruction, cleanup step, or recovery fact that callers and tests must know.
-
-Likely issue: the interface is growing with the implementation instead of hiding it.
-
-Route:
-
-- stop adding contract detail;
-- inventory caller knowledge;
-- design materially different outcome-level interfaces;
-- use a learning slice if evidence cannot choose between them.
-
-### Contract-Surface Explosion
-
-Signal: an internal lifecycle becomes a public protocol of attempts, manifests, orphan states, retry links, grade modes, cache identities, or integrity steps.
-
-Likely issue: caller-owned outcome and internal protocol have been confused.
-
-Ask whether one operation can own the complete success/failure unit and publish diagnostics without exposing recovery choreography.
-
-### Tests Legitimize Machinery
-
-Signal: test count grows quickly, but most new tests protect states and mechanisms introduced by recent patches rather than accepted behavior.
+Related signals:
 
-Likely issue: passing tests are making accidental complexity look required.
+- every correction adds another state or flag;
+- recovery steps become ordinary caller behavior;
+- callers depend on paths, filenames, provider errors, or queue names;
+- a complete outcome becomes a public protocol of attempts and temporary states.
 
-Every architecture-bearing test should name its accepted requirement or measured failure. If deleting the mechanism also deletes its tests without weakening acceptance, the tests do not justify it.
+Ask whether one operation can own the complete success and failure unit while publishing diagnostics separately.
 
-### Scope And Remaining-Work Growth
+## Scattered Policy
 
-Signal: completed slices increase the estimated remaining work, pull deferred capabilities into scope, require an unplanned subsystem, or invalidate earlier evidence.
-
-Likely issue: the milestone or plan has been invalidated even if each local change remains technically in scope.
-
-Return the evidence and options to Workflow: keep, simplify, split, defer, revise the owning Plan or Spec, or stop for owner direction.
-
-### Edge-Case Patch Stream
-
-Signal: each review pass finds another special case.
-
-Examples:
-
-- “also handle null phone”; then “also handle email bounce”; then “also handle duplicate invite”; then “also handle retry telemetry.”
-
-Likely issue: review is exposing missing behavior ownership, not isolated bugs.
-
-Route:
-
-- classify findings;
-- respect the review cap;
-- diagnose only when related findings suggest an unclear shared cause in discussion, source truth, the Spec or Plan, module shape, or reviewer context.
-
-### Pass-Through Wrapper
-
-Signal: a module mostly renames another call.
+Pressure exists when one product or operational decision is encoded in several places.
 
 Example:
 
-```ts
-function sendTeamInviteEmail(email, subject, options) {
-  return sendEmail(email, subject, options);
-}
+```text
+billing transition timing appears separately in webhook,
+dashboard, email, and worker behavior.
 ```
 
-Likely issue: shallow wrapper.
-
-Options:
-
-- delete it if it hides nothing;
-- deepen it by moving real policy behind it;
-- keep it only when it expresses a stable domain or compatibility interface with a source-backed reason to exist.
-
-### Leaky Interface
-
-Signal: callers know provider/database/cache internals.
-
-Examples:
-
-- callers catch Stripe-specific errors;
-- UI code knows database enum transitions;
-- API callers pass cache invalidation flags;
-- tests assert internal queue names.
-
-Likely issue: implementation detail leaked through interface.
+Do not centralize behavior until the policy is accepted. When it is user-owned or conflicting, stop for a decision.
 
-Route to design if leakage blocks safe change or verification.
+## Unowned State Or Failure
 
-### God Module
+Pressure exists when no module owns:
 
-Signal: one file owns unrelated responsibilities.
+- canonical state and its visibility point;
+- forbidden partial outcomes;
+- retry, degradation, or escalation;
+- cancellation and reconciliation;
+- recovery after partial completion;
+- evidence proving the final state.
 
-Examples:
+Do not design architecture around an invented failure policy.
 
-- route file validates input, applies policy, calls providers, logs metrics, and formats UI copy;
-- workflow module owns routing, vaulting, parsing, rendering, and config mutation.
+## Contract-Surface Growth
 
-Likely issue: missing internal modules or seams.
+Pressure exists when each patch adds public:
 
-Do not split by file type alone. Split around hidden decisions and interfaces.
+- flags;
+- temporary states;
+- manifest fields;
+- retry links;
+- recovery instructions;
+- provider-specific errors;
+- cache or integrity controls.
 
-### Speculative Seam
+Ask whether callers own those facts or are being forced to understand internal protocol.
 
-Signal: interface/adapters/factory exist for only imagined future variation.
+## Distorted Tests
 
-Examples:
+Pressure exists when tests:
 
-- `PaymentProviderAdapterFactoryRegistry` when only Stripe exists and no migration is planned;
-- strategies for every small formatting function;
-- generic repository around a single simple query.
+- reproduce caller choreography;
+- mock many helpers to verify one outcome;
+- depend on private lifecycle states;
+- protect machinery introduced by recent patches;
+- prove rejection without checking forbidden writes;
+- make provider mechanics look like domain requirements.
 
-Likely issue: indirection without leverage.
+Do not automatically add mocks or test-only seams. First inspect whether the production boundary owns the complete behavior.
 
-Use the variation test: one adapter is hypothetical; two adapters or known upcoming variation justify a seam better.
+An intentional internal test is not a defect merely because it observes internals.
 
-### Premature Artifact Detail
+## Edge-Case Patch Streams
 
-Signal: spec or plan chooses exact classes, factories, tables, or algorithms before evidence exists.
+Pressure exists when related fixes repeatedly add conditions, states, or caller rules.
 
-Likely issue: artifact is hiding uncertainty as implementation detail.
-
-Better:
-
-```text
-Tentative: likely need a policy-owning module if retry/fallback rules spread.
-Open: whether provider variation is real in this scope.
-Stop: revisit plan if slice requires touching every caller.
-```
-
-## Before / After Examples
-
-### Notification Retry
-
-Bad direction:
+Example:
 
 ```text
-Add retryCount to each route that sends notifications.
+handle missing contact
+-> handle fallback
+-> handle duplicate delivery
+-> handle retry telemetry
+-> expose another state to callers
 ```
 
-Pressure:
+Do not infer architecture from finding count alone. Diagnose whether the cases share one missing contract, state owner, or failure unit.
 
-- callers know retry policy;
-- fallback and telemetry are duplicated;
-- tests assert provider sequencing;
-- adding another provider touches every caller.
+## Scope Growth
 
-Better direction:
+Pressure exists when a bounded result unexpectedly:
 
-```text
-Introduce a notification delivery module whose interface accepts the notification intent and owns retry, fallback, provider errors, and telemetry.
-```
+- requires a subsystem;
+- expands remaining work;
+- pulls deferred capabilities into scope;
+- invalidates earlier evidence;
+- requires unrelated callers to change.
 
-Still ask owner decisions before changing user-visible delivery semantics.
+Return the evidence. The correct route may be simplify, split, revise an artifact, learn, defer, or stop.
 
-### Billing Grace Period
+## Common Interface Mismatches
 
-Bad direction:
+### Pass-through wrapper
 
-```text
-Patch webhook to downgrade immediately, update email text, adjust dashboard copy.
-```
+Renames a call without hiding policy or provider behavior.
 
-Pressure:
+Keep only when it preserves a real domain, compatibility, or observation boundary.
 
-- billing policy spread across systems;
-- likely source-truth conflict with docs/tests;
-- user-owned billing behavior.
+### Leaky interface
 
-Better direction:
+Callers know infrastructure-specific details.
 
-```text
-Stop at the decision gate. Decide billing policy first. Then localize policy behind a billing-state transition module if implementation spreads.
-```
+### God module
 
-### Cache Freshness
+Unrelated decisions are collected behind one interface.
 
-Bad direction:
+### Speculative seam
 
-```text
-Thread forceRefresh through every caller.
-```
+Indirection exists only for imagined variation.
 
-Pressure:
+### Dependency cycle
 
-- callers know cache invalidation policy;
-- tests must set timing flags;
-- source truth may allow caching.
+Modules cannot change independently because their responsibilities point at each other.
 
-Better direction:
+### Premature artifact detail
 
-```text
-Discuss the expected freshness boundary. If source truth supports it, hide invalidation and freshness rules behind a cache-aware read interface.
-```
+A Spec or Plan freezes classes, factories, tables, or algorithms before evidence supports the boundary.
 
 ## False Positives
 
-Do not overreact when:
+Do not escalate when:
 
-- a small repeated pattern is stable and local;
-- a one-off script does not need long-term depth;
-- a wrapper exists for public compatibility;
+- stable repetition remains small and local;
 - broad edits are mechanical and source-backed;
-- tests inspect internals only for an internal module whose interface is intentionally internal;
-- deeper design would expand scope beyond the user's goal.
+- a one-off script does not need long-term abstraction;
+- a wrapper preserves a real compatibility contract;
+- an isolated condition is wrong but the interface remains sound;
+- an internal test intentionally verifies an internal module;
+- resolving the pressure would exceed the user’s goal without blocking it.
 
-When in doubt, classify as deferred design pressure rather than silently refactoring.
+Stop once the route is classified. Return evidence and classification; do not redesign automatically.

package/skills/design-for-depth/references/interface-design-loop.md

@@ -1,156 +1,136 @@
 # Interface Design Loop
 
-Use this when structural pressure makes the current interface suspect. The goal is to choose an outcome-level module shape, not add detail to the first plausible design.
+Read this before comparing materially different interfaces or settling an important correctness boundary where ownership is consequential.
 
-## 1. Frame The Outcome
+Use only evidence and criteria capable of distinguishing viable boundaries. Do not emit a full checklist unless the artifact itself requires one.
 
-State:
+## 1. Frame The Complete Outcome
+
+Orient broadly enough to state:
 
 - caller and complete outcome;
 - source-backed behavior and non-goals;
 - decisions the caller genuinely owns;
 - dependencies and current constraints;
-- why the current seam is under pressure.
-
-Do not begin from existing flags, storage paths, or lifecycle states. Those may be symptoms of the current shape.
+- material state and failure boundaries;
+- why the current seam requires attention.
 
-## 2. Choose The Failure Unit
+Do not begin from existing flags, storage paths, classes, or temporary states. They may be symptoms of the current design.
 
-Name the atomic unit before designing retries or resume:
+## 2. Define The Failure Unit
 
-- operation;
-- slice;
-- comparison;
-- session;
-- published result;
-- another outcome specific to the domain.
+Name the coherent outcome treated as one success, failure, and recovery boundary.
 
-Define:
+Define material:
 
-- terminal states;
-- observers;
-- state or evidence written;
+- terminal states and observers;
+- canonical and diagnostic state;
+- evidence written;
 - forbidden partial outcomes;
-- safe restart unit;
-- recovery proof;
-- whether partial reuse is a requirement or only an optimization.
-
-When authority, integrity, canonical persistence, or proof validity materially affects correctness, also define:
+- safe restart and recovery;
+- required proof;
+- whether partial reuse is required or merely an optimization.
 
-- trust anchor and which actors can replace it;
-- mutable state and canonical versus diagnostic records;
-- authority or capability binding and replay scope;
-- commit and visibility point;
-- behavior when cancellation, integrity failure, or reconciliation failure occurs after an awaited or committed boundary.
+When correctness materially depends on canonical state, partial effects, atomic visibility, concurrency, cancellation, retries, recovery, reconciliation, or evidence of the final outcome, read [State And Failure Boundaries](state-and-failure-boundaries.md).
 
-Retry, resume, caching, continuation, and partial reuse are separate capabilities. Durability does not automatically require them.
+## 3. Inventory Material Caller Knowledge
 
-## 3. Inventory Caller Knowledge
+List only facts callers must know and that could affect the boundary:
 
-List every fact a caller, test, reviewer, or future agent must know to use the module correctly:
-
-```text
-commands / methods
-parameters and flags
-ordering
-states and transitions
-paths and filenames
-roles and ownership
-retries and cleanup
-configuration
-errors and failure semantics
-compatibility and migration
-cost and performance expectations
-recovery
-```
+- operations and inputs;
+- caller-owned decisions;
+- ordering and lifecycle states;
+- configuration and provider details;
+- dependencies;
+- errors and failure semantics;
+- compatibility and migration;
+- recovery, cost, and performance expectations.
 
 For each fact ask:
 
-- Does the caller own this decision?
-- Could the module own it instead?
+- Does the caller own it?
+- Could the module own it?
 - Is it stable enough to expose?
 - Would changing it force surrounding edits?
-- Did a recent fix or review add this knowledge?
-
-A growing list is direct evidence of a shallow interface.
 
-## 4. Classify Maturity
+The goal is not zero interface knowledge. It is the smallest honest contract.
 
-Classify proposed capabilities:
+## 4. Classify Capability Maturity
 
-- **Trust:** needed to know the outcome is valid.
-- **Safety:** prevents damage, leakage, or runaway work.
-- **Efficiency:** saves time, requests, or money.
-- **Scale:** supports concurrency or volume.
-- **Portability:** supports additional hosts, providers, or environments.
+Separate:
 
-Required trust and safety cannot be deferred merely to simplify the design. Efficiency, scale, and portability need accepted requirements or observed pressure.
+- required trust and safety;
+- accepted efficiency or scale;
+- demonstrated portability;
+- speculative flexibility.
 
-## 5. Design It Twice
+Do not defer required correctness to obtain a simpler-looking interface. Do not promote hypothetical efficiency, scale, or portability into present architecture.
 
-Produce two or three materially different interfaces. Change seam placement or ownership, not only names.
+## 5. Produce Alternatives Only When Real
 
-Useful design constraints:
+When materially different ownership choices remain viable, design two or three interfaces that change seam placement—not only terminology.
 
-- **Outcome-first:** caller asks for one complete result; module owns sequencing.
-- **Minimal contract:** expose the fewest stable decisions possible.
-- **Common-case:** make the primary caller path trivial while preserving failure honesty.
-- **Real variation:** design around two concrete adapters or environments when variation actually exists.
+For each show:
 
-For each design show:
-
-1. interface and usage;
+1. ordinary caller usage;
 2. caller-owned decisions;
 3. hidden internal protocol;
-4. failure unit and behavior;
-5. dependency/adapters strategy;
-6. evidence needed to trust it;
-7. costs and limitations.
+4. failure unit and observable behavior;
+5. dependency and adapter strategy;
+6. evidence needed;
+7. material cost or limitation.
+
+When module decomposition, cohesion, dependency direction, cycles, layering, policy-versus-infrastructure ownership, or change propagation materially affects the design, read [Module And Dependency Design](module-and-dependency-design.md).
 
-Do not force multiple designs when the change is local, reversible, and source-backed.
+Do not manufacture alternatives for a local, reversible, source-backed choice.
 
-## 6. Compare
+## 6. Compare On Discriminating Criteria
 
-Compare designs by:
+Use only criteria that could change the recommendation:
 
-- depth: behavior gained per interface fact;
-- locality: where future changes land;
+- behavior per interface fact;
+- locality of likely change;
+- cohesion and ownership clarity;
 - correct-use ergonomics;
 - misuse and hidden-decision risk;
-- failure behavior and recoverability;
-- contract stability when callers depend on observable details;
-- test surface quality;
+- dependency direction;
+- failure honesty and recovery;
+- contract stability;
+- test surface;
 - reversibility;
 - maturity fit;
 - implementation and evidence cost.
 
-Prefer the design that removes concepts and coordination, not the one that centralizes the same choreography behind more terminology.
+Prefer the boundary that removes concepts and coordination, not one that centralizes the same protocol behind additional terminology.
 
 ## 7. Learn Before Freezing
 
-If evidence cannot distinguish the designs, define one bounded learning slice:
+When evidence cannot distinguish viable boundaries, define one bounded learning slice:
 
 ```text
 Question:
-Competing designs:
-Prototype boundary:
-Evidence to capture:
-Time / cost boundary:
+Competing boundaries:
+Smallest prototype or observation:
+Evidence required:
+Time or cost boundary:
 Discard-or-promote rule:
 Return condition:
 ```
 
-The experiment should answer the design question, not quietly implement the whole subsystem.
+The learning slice answers the design question. It does not quietly implement the whole subsystem.
 
-## 8. Return To Workflow
+## 8. Return The Supported Boundary
 
-Return the structural evidence, compared designs, recommendation, unresolved owner decisions, and one narrow route:
+Return:
 
-- continue with the selected interface;
-- discuss or ask an owner decision;
-- revise the owning Spec or Plan;
-- run the bounded learning slice;
-- propose a bounded deepening slice;
-- defer or stop because no worthwhile safe design fits the current scope.
+- structural evidence;
+- selected boundary and hidden decision;
+- caller-owned contract;
+- module and dependency implications;
+- failure unit and material failure behavior;
+- rejected alternatives and discriminating reason, when alternatives were real;
+- unresolved user-owned decisions;
+- assumptions and required evidence;
+- narrowest next route.
 
-Do not edit merely because one design is recommended. Recommendation is direction; Workflow owns selection and approval boundaries.
+Stop once a boundary is supported or a bounded learning question is identified. Recommendation does not authorize implementation.