@hassangameryt/freeflow 0.2.0 → 0.4.0

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

@@ -0,0 +1,314 @@
+# Design Pressure Signals
+
+Use this reference when reviewing code, artifacts, or work for shallow modules and complexity spread.
+
+The goal is not to find every smell. The goal is to notice pressure that changes the next route.
+
+## Quick Classifier
+
+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?
+
+Then classify:
+
+- **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.
+
+## Signals And What They Usually Mean
+
+### Shotgun Surgery
+
+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:
+
+```text
+open connection -> set retry -> register cleanup -> call provider -> translate error -> log metric
+```
+
+Likely issue: interface exposes implementation sequence.
+
+Better interface asks for outcome:
+
+```text
+deliverNotification(invitation)
+```
+
+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.
+
+Likely issue: passing tests are making accidental complexity look required.
+
+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.
+
+### Scope And Remaining-Work Growth
+
+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.
+
+Example:
+
+```ts
+function sendTeamInviteEmail(email, subject, options) {
+  return sendEmail(email, subject, options);
+}
+```
+
+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.
+
+Route to design if leakage blocks safe change or verification.
+
+### God Module
+
+Signal: one file owns unrelated responsibilities.
+
+Examples:
+
+- route file validates input, applies policy, calls providers, logs metrics, and formats UI copy;
+- workflow module owns routing, vaulting, parsing, rendering, and config mutation.
+
+Likely issue: missing internal modules or seams.
+
+Do not split by file type alone. Split around hidden decisions and interfaces.
+
+### Speculative Seam
+
+Signal: interface/adapters/factory exist for only imagined future variation.
+
+Examples:
+
+- `PaymentProviderAdapterFactoryRegistry` when only Stripe exists and no migration is planned;
+- strategies for every small formatting function;
+- generic repository around a single simple query.
+
+Likely issue: indirection without leverage.
+
+Use the variation test: one adapter is hypothetical; two adapters or known upcoming variation justify a seam better.
+
+### Premature Artifact Detail
+
+Signal: spec or plan chooses exact classes, factories, tables, or algorithms before evidence exists.
+
+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:
+
+```text
+Add retryCount to each route that sends notifications.
+```
+
+Pressure:
+
+- callers know retry policy;
+- fallback and telemetry are duplicated;
+- tests assert provider sequencing;
+- adding another provider touches every caller.
+
+Better direction:
+
+```text
+Introduce a notification delivery module whose interface accepts the notification intent and owns retry, fallback, provider errors, and telemetry.
+```
+
+Still ask owner decisions before changing user-visible delivery semantics.
+
+### Billing Grace Period
+
+Bad direction:
+
+```text
+Patch webhook to downgrade immediately, update email text, adjust dashboard copy.
+```
+
+Pressure:
+
+- billing policy spread across systems;
+- likely source-truth conflict with docs/tests;
+- user-owned billing behavior.
+
+Better direction:
+
+```text
+Stop at the decision gate. Decide billing policy first. Then localize policy behind a billing-state transition module if implementation spreads.
+```
+
+### Cache Freshness
+
+Bad direction:
+
+```text
+Thread forceRefresh through every caller.
+```
+
+Pressure:
+
+- callers know cache invalidation policy;
+- tests must set timing flags;
+- source truth may allow caching.
+
+Better direction:
+
+```text
+Discuss the expected freshness boundary. If source truth supports it, hide invalidation and freshness rules behind a cache-aware read interface.
+```
+
+## False Positives
+
+Do not overreact 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;
+- 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.
+
+When in doubt, classify as deferred design pressure rather than silently refactoring.

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

@@ -0,0 +1,156 @@
+# 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.
+
+## 1. Frame The Outcome
+
+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.
+
+## 2. Choose The Failure Unit
+
+Name the atomic unit before designing retries or resume:
+
+- operation;
+- slice;
+- comparison;
+- session;
+- published result;
+- another outcome specific to the domain.
+
+Define:
+
+- terminal states;
+- observers;
+- state or 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:
+
+- 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.
+
+Retry, resume, caching, continuation, and partial reuse are separate capabilities. Durability does not automatically require them.
+
+## 3. Inventory Caller Knowledge
+
+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
+```
+
+For each fact ask:
+
+- Does the caller own this decision?
+- Could the module own it instead?
+- 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
+
+Classify proposed capabilities:
+
+- **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.
+
+Required trust and safety cannot be deferred merely to simplify the design. Efficiency, scale, and portability need accepted requirements or observed pressure.
+
+## 5. Design It Twice
+
+Produce two or three materially different interfaces. Change seam placement or ownership, not only names.
+
+Useful design constraints:
+
+- **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 design show:
+
+1. interface and 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.
+
+Do not force multiple designs when the change is local, reversible, and source-backed.
+
+## 6. Compare
+
+Compare designs by:
+
+- depth: behavior gained per interface fact;
+- locality: where future changes land;
+- correct-use ergonomics;
+- misuse and hidden-decision risk;
+- failure behavior and recoverability;
+- contract stability when callers depend on observable details;
+- test surface quality;
+- 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.
+
+## 7. Learn Before Freezing
+
+If evidence cannot distinguish the designs, define one bounded learning slice:
+
+```text
+Question:
+Competing designs:
+Prototype boundary:
+Evidence to capture:
+Time / cost boundary:
+Discard-or-promote rule:
+Return condition:
+```
+
+The experiment should answer the design question, not quietly implement the whole subsystem.
+
+## 8. Return To Workflow
+
+Return the structural evidence, compared designs, recommendation, unresolved owner decisions, and one narrow route:
+
+- 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.
+
+Do not edit merely because one design is recommended. Recommendation is direction; Workflow owns selection and approval boundaries.