@hassangameryt/freeflow 0.3.0 → 0.5.0

package/skills/design-for-depth/SKILL.md

@@ -1,90 +1,106 @@
 ---
 name: design-for-depth
-description: Use when shaping, reviewing, implementing, or diagnosing work where module/interface/seam choices affect complexity, locality, testability, future change, or repeated edge-case churn. Use for architecture direction, growing scope, shallow modules, bad seams, broad refactors, and review loops that keep finding new edge cases.
+description: Use when working with software design—especially boundaries, interfaces, ownership, state, and failure behavior.
 ---
 
 # Design For Depth
 
-Use this as a lens, not a phase.
+Reduce coordination by hiding internal decisions behind small, stable, outcome-level interfaces.
 
-Core rule: if complexity is spreading across callers, tests, docs, artifacts, or review comments, stop and classify the design pressure before patching forward.
+A **module** is anything with an interface and implementation. A **caller** is anything that uses or coordinates the module through its interface, such as application code, another service, a script, a test, a tool, or an agent. Its **interface** is every fact callers must know to use it correctly: inputs, decisions, states, ordering, errors, side effects, configuration, timing, and failure behavior. **Depth** is useful behavior and hidden complexity per unit of interface knowledge.
 
-Goal: hide useful complexity behind stable interfaces so future callers, tests, reviewers, and agents coordinate less.
+A **seam** is a boundary where behavior, dependencies, or observation can change without forcing surrounding edits. An **adapter** is a concrete implementation supplied at that seam. Add a seam for real variation or a required testing or observation boundary—not imagined flexibility.
 
-Do not add architecture ceremony when the next action is small, local, and reversible. Do not use architecture language to hide product or policy decisions.
+Use this as a compositional lens, not a mandatory phase or permission to refactor.
 
-## Load When Needed
+## Compose The Lens Early
 
-Read `references/software-design-philosophy.md` when shaping architecture direction, reviewing a design-heavy artifact, or diagnosing repeated design failure.
+Read this during design-bearing discussion before core boundaries settle. Use it while writing a Spec or Plan when ownership, interfaces, state, or failure behavior shapes the contract. Keep it available during execution, TDD, and review when the work must preserve those decisions or exposes new coordination.
 
-Read `references/design-pressure-signals.md` when reviewing code/work for shallow modules, scattered policy, edge-case churn, or refactor candidates.
+Feedback may also route here after [Diagnose Failure](../diagnose-failure/SKILL.md) establishes structural ownership, interface, state, or failure-unit pressure. Ordinary bugs, failed tests, or finding count do not prove bad design.
 
-Do not load references for every small design question. The active skill should be enough for routine routing.
+Do not force this lens onto a local change whose interface remains sound. Do not use architecture language to hide product decisions or turn reversible implementation detail into ceremony.
 
-## Language
+## Start With Outcome And Failure
 
-Use these terms consistently:
+Before choosing classes, services, states, or adapters, ask:
 
-- **Module** — anything with an interface and implementation: function, class, package, subsystem, workflow slice.
-- **Interface** — everything a caller, user, test, or future agent must know: types, invariants, ordering, errors, configuration, performance, side effects, and policy context.
-- **Implementation** — details hidden behind the interface.
-- **Depth** — leverage at the interface. Deep modules hide useful behavior behind a smaller interface.
-- **Shallow module** — interface is nearly as complex as implementation, or callers coordinate details the module should own.
-- **Seam** — where behavior, ownership, or variation can change without editing surrounding work.
-- **Adapter** — a concrete thing satisfying an interface at a seam.
-- **Locality** — changes, bugs, decisions, and verification stay near one module.
-- **Leverage** — future work gets more behavior from less interface knowledge.
+- What complete outcome should the caller request?
+- Which decisions genuinely belong to the caller?
+- Which ordering, policy, storage, retry, cleanup, or provider details can the module own?
+- What counts as complete and visible success?
+- If it fails, who observes it, what state or evidence is written, and what must never happen?
+- Does failure stop, fail closed, fail open, degrade, retry, escalate, or require recovery?
+- What is safe to restart, and what evidence establishes recovery?
+- Which likely-changing decision should remain local?
 
-Avoid using “architecture” as a vague quality claim. Name the module, interface, hidden decision, seam, adapter, locality, or leverage.
+The answers form the **failure contract**: failure modes, observers, written state, forbidden outcomes, retry or degradation behavior, recovery, and proof. The **failure unit** is the smallest outcome treated as one success, failure, and recovery boundary. Failure behavior is part of the interface even when its mechanism remains private.
 
-## Signals
+When these answers change product behavior, public interfaces, compatibility, permissions, security, privacy, billing, data loss, migration direction, or another user-owned outcome, use [Decision Gate](../decision-gate/SKILL.md). This lens surfaces the decision; it does not make it silently.
 
-Use this lens when evidence shows:
+## Hide Coordination
 
-- one concept requires many unrelated file, test, doc, or reviewer-comment changes;
-- callers know ordering, flags, retries, cleanup, cache, auth, billing, migration, privacy, permissions, or compatibility policy;
-- tests reach past the interface to assert normal behavior;
-- review findings become a stream of edge-case patches;
-- the same conditional or policy appears in multiple callers;
-- a module is mostly pass-through naming around another module;
-- a seam exists only for theoretical future variation;
-- a spec or plan encodes detailed implementation guesses before evidence exists;
-- the agent can only explain correctness by listing coordinated steps across modules.
+Prefer interfaces where callers ask for an outcome and the module owns internal protocol.
 
-Do not use this lens just because work is “important.” Use it when interface shape changes the next action.
+Before exposing a flag, state, path, filename, ordering rule, retry, timing behavior, or error, ask:
 
-## Tests
+- Does the caller own this choice?
+- Does exposing it make correct use easier?
+- Is it stable enough to become a contract?
+- Could one outcome-level operation hide it?
 
-Use the smallest test that changes the route:
+Keep caller-owned outcomes and decisions public. Keep internal sequencing, storage, cleanup, provider mechanics, integrity publication, and optimization private unless correct use requires caller control.
 
-- **Deletion test:** if deleting the module makes complexity vanish, it may be pass-through ceremony. If complexity reappears across callers, tests, docs, or review comments, it was earning its keep.
-- **Interface test surface:** callers and tests should exercise normal behavior through the same interface. If tests bypass it, mock internals, or duplicate setup, the module shape may be wrong.
-- **Variation test:** one adapter is a hypothetical seam. Two adapters, a real test double, or a known upcoming variation justify a seam better.
-- **Locality test:** one behavior change should not scatter policy, error handling, retries, logging, auth, billing, compatibility, docs, and tests across unrelated places.
-- **Decision-hiding test:** design decisions likely to change should live behind modules, not in every caller or artifact.
-- **Obscurity test:** if a fresh agent must read many files to learn a simple rule, the design may be obscure even if each file is small.
+Read [software design philosophy](references/software-design-philosophy.md) when the reason a design is shallow or coordination-heavy is unclear.
 
-## Route
+## Recognize Structural Pressure
 
-If the current direction spreads complexity, do not patch forward silently.
+Structural pressure exists when evidence shows that:
 
-Classify the pressure:
+- each correction adds caller knowledge, public states, flags, retries, or recovery rules;
+- one policy or behavior requires unrelated edits across callers;
+- callers or tests duplicate lifecycle choreography;
+- tests need many owned internals or production hooks created only for testing;
+- a bounded outcome requires an unplanned subsystem because no current seam can own it;
+- correctness depends on coordinated steps that no module owns.
 
-- **Local fix:** same interface, complexity stays hidden; continue in the current phase.
-- **Plan defect:** slice boundary, check, or implementation path is wrong; revise the plan.
-- **Spec gap:** behavior, scope, or acceptance is unclear; revise the spec or return to discovery.
-- **Owner decision:** public API, compatibility, security, privacy, billing, data-loss, permissions, migration, or hard-to-reverse architecture changes; use the interview gate.
-- **Refactor candidate:** current behavior is valid but the module is shallow; propose a bounded deepening path before editing.
-- **Stop/defer:** design pressure is real but not worth solving in this scope; record or defer it explicitly.
+These signals justify design attention, not automatic refactoring. Read [design pressure signals](references/design-pressure-signals.md) when code, artifacts, tests, or reviews show complexity spreading.
 
-## Non-Goals
+Diagnose repeated or unexplained failure before redesigning. Direct design work is appropriate when structural pressure is already observable or an important boundary must be chosen before implementation.
 
-Do not:
+## Shape The Interface
 
-- introduce abstractions for imagined future variation;
-- hide product or policy decisions inside architecture wording;
-- rewrite source truth to make a design cleaner;
-- turn every feature into upfront architecture design;
-- broaden a narrow fix into a refactor without user approval;
-- treat line count, file count, indirection, or pattern names as proof of quality;
-- claim a design is better without evidence from code, tests, review, usage, or an explicit owner decision.
+When pressure changes the next action:
+
+1. Name the complete outcome and settled behavior.
+2. Choose the success and failure unit.
+3. Inventory what callers, tests, reviewers, and future agents must know.
+4. Keep caller-owned decisions public and move internal protocol behind the module.
+5. Separate required trust and safety from speculative efficiency, scale, or portability.
+6. For a structural or hard-to-reverse choice, compare materially different ownership or seam placements—not cosmetic variants.
+7. Prefer the design with less caller knowledge, better locality, safer failure behavior, easier correct use, and proportionate evidence cost.
+
+Read [the interface design loop](references/interface-design-loop.md) when materially different interfaces must be compared, evidence cannot yet choose one, or authority, canonical state, atomic visibility, replay, cancellation, or post-commit recovery affects correctness.
+
+Do not force multiple designs for an obvious local choice. If source inspection cannot distinguish viable designs, propose one bounded learning slice with a question, competing designs, evidence, cost boundary, and discard-or-promote condition.
+
+## Tests And Evidence
+
+The intended interface is the normal test surface. If tests must bypass it, reproduce caller choreography, or mock many owned internals, question the module shape before adding test machinery.
+
+Architecture-bearing tests should protect accepted behavior, observed failure, or a settled failure contract. Tests that exist only to protect unnecessary machinery do not justify that machinery.
+
+Exploratory code may produce design evidence. It does not become production architecture without deliberate selection through [Workflow](../workflow/SKILL.md), implementation as an authorized slice, and verification at the required boundary.
+
+## Boundary Examples
+
+- A core operation is being discussed, but partial failure is unspecified → define the failure unit and surface any owner decision before settling the interface.
+- Every caller coordinates retry, storage, cleanup, and error translation → consider an outcome-level module that owns the protocol.
+- One isolated condition is wrong while callers and the interface remain valid → make a local correction; do not redesign.
+- Related failures repeatedly add shared states and caller rules → diagnose the common cause, then use this lens only when structural pressure is supported.
+
+## Return The Route
+
+Return the structural evidence, affected boundary, materially different options when needed, recommendation, and unresolved owner decisions to Workflow. Recommend the narrowest route: continue, run a learning slice, revise a Spec or Plan, use Decision Gate, propose a bounded deepening slice, defer, or stop.
+
+A design recommendation does not authorize implementation. Do not expose speculative variation, broaden accepted scope, or refactor merely because a deeper design is possible. Freeze a supported design boundary instead of pursuing architectural completeness.

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

@@ -20,7 +20,7 @@ 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.
-- **Spec/discovery:** behavior, scope, or acceptance is unclear.
+- **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.
 
@@ -41,7 +41,7 @@ Likely issue: a likely-changing decision is not hidden behind a module.
 
 Route:
 
-- If behavior/scope is unsettled: discovery or spec.
+- 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
@@ -94,6 +94,55 @@ 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.
@@ -107,8 +156,8 @@ Likely issue: review is exposing missing behavior ownership, not isolated bugs.
 Route:
 
 - classify findings;
-- stop at review cap;
-- diagnose whether discovery, spec, plan, source truth, module shape, or reviewer context is wrong.
+- 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
 
@@ -128,7 +177,7 @@ Options:
 
 - delete it if it hides nothing;
 - deepen it by moving real policy behind it;
-- keep it only if it expresses a stable domain interface that will soon hide behavior.
+- keep it only when it expresses a stable domain or compatibility interface with a source-backed reason to exist.
 
 ### Leaky Interface
 
@@ -228,7 +277,7 @@ Pressure:
 Better direction:
 
 ```text
-Stop at interview gate. Decide billing policy first. Then localize policy behind a billing-state transition module if implementation spreads.
+Stop at the decision gate. Decide billing policy first. Then localize policy behind a billing-state transition module if implementation spreads.
 ```
 
 ### Cache Freshness
@@ -248,7 +297,7 @@ Pressure:
 Better direction:
 
 ```text
-Discover expected freshness boundary. If source truth supports it, hide invalidation/freshness rules behind a cache-aware read interface.
+Discuss the expected freshness boundary. If source truth supports it, hide invalidation and freshness rules behind a cache-aware read interface.
 ```
 
 ## False Positives

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.

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

@@ -56,7 +56,7 @@ Freeflow translation:
 
 - Do not redesign everything up front.
 - Do stop when the local patch clearly makes the next slice, review, or bug fix harder.
-- Route backward when the plan is tactical but the work is becoming structural.
+- Return the structural evidence to [Workflow](../../workflow/SKILL.md) when a tactical patch is becoming structural work.
 
 ## Parnas: Information Hiding
 
@@ -76,9 +76,14 @@ notification delivery policy: provider choice, retry, fallback, telemetry, failu
 
 A good module hides the unstable decision.
 
+For consequential systems, failure behavior is often the unstable decision. Hide the contract in the module before callers invent their own retries, fallbacks, state writes, escalation paths, or graceful-failure claims.
+
 Ask:
 
 - What decision would cause the most edits if it changed?
+- What can fail, who observes it, what state is written, and what must not happen?
+- Does the system fail closed, fail open, degrade, escalate, retry, or stop?
+- What recovery path and evidence prove graceful handling?
 - Which callers currently know that decision?
 - Can one module own it?
 - What interface would let callers stop knowing it?
@@ -148,6 +153,28 @@ Do not over-apply ports/adapters:
 - a single stable library call may not need an adapter;
 - wrapping an SDK without hiding policy or provider quirks is often shallow.
 
+## Public Contract Cost
+
+Hyrum's Law applies beyond public HTTP APIs: every observable flag, path, state, ordering rule, filename, error, timing behavior, and fallback can become depended upon.
+
+Expose a fact only when the caller owns it or correct use requires it. Internal protocols may remain detailed and independently tested without becoming public seams.
+
+A useful split:
+
+- **Public:** caller-owned outcome, decisions, stable invariants, and observable failure semantics.
+- **Internal:** storage layout, provider mechanics, retries, cleanup, integrity publication, temporary states, and optimization machinery.
+
+Public flexibility has permanent coordination cost. One outcome-level operation is often deeper than a toolkit that lets callers reconstruct the module's lifecycle.
+
+## Maturity And Learning
+
+Classify mechanisms before adding them:
+
+- required trust and safety cannot be deferred merely to simplify the design;
+- efficiency, scale, and portability require accepted requirements or observed pressure.
+
+When the best interface cannot be known from source inspection, use a bounded learning slice. Name the question, competing designs, evidence, cost boundary, and discard-or-promote rule. Code can answer a design question without becoming the production design automatically.
+
 ## Refactoring Pressure
 
 Design pressure often appears as ordinary implementation pain:
@@ -171,7 +198,7 @@ Classify it:
 
 ## Applying The Philosophy In Freeflow
 
-### In discovery
+### In discussion
 
 Use design ideas to ask better questions, not to freeze architecture.
 
@@ -202,7 +229,9 @@ Requirement: implement NotificationDeliveryPortFactoryStrategy.
 
 ### In plans
 
-Plan around vertical behavior and interfaces.
+Use [Write Plan](../../write-plan/SKILL.md) only when the ordered strategy can be stated without guessing. When later direction remains provisional, keep it in [Track Work](../../track-work/SKILL.md) or return the evidence to [Workflow](../../workflow/SKILL.md) rather than freezing it as a Plan.
+
+For consequential systems, make failure behavior explicit before implementation choices harden. Do not leave it as an implementer guess after planning only the happy path.
 
 A good slice can be verified through the intended interface. If the slice requires broad caller choreography, revise the slice.