@hassangameryt/freeflow 0.5.0 → 0.7.0

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

@@ -1,106 +1,252 @@
 ---
 name: design-for-depth
-description: Use when working with software design—especially boundaries, interfaces, ownership, state, and failure behavior.
+description: Use during coding and software design to keep boundaries, interfaces, ownership, state, dependencies, and failure behavior simple and proportionate.
 ---
 
 # Design For Depth
 
-Reduce coordination by hiding internal decisions behind small, stable, outcome-level interfaces.
+Reduce coordination by hiding coherent, likely-changing decisions behind small, stable, outcome-level interfaces.
 
-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.
+A **module** is anything with an interface and implementation. A **caller** is anything that uses it. The **interface** is every fact callers must know to use it correctly: operations, inputs, decisions, states, ordering, errors, side effects, dependencies, configuration, timing, and recovery.
 
-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.
+**Depth** is useful coherent behavior and hidden complexity per unit of caller knowledge.
 
-Use this as a compositional lens, not a mandatory phase or permission to refactor.
+Use this as a compositional lens under the active activity. It is not a mandatory phase, authority source, architecture owner, or reason to refactor.
 
-## Compose The Lens Early
+## Orient Broadly, Deepen Narrowly
 
-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.
+Use breadth of understanding before depth of intervention.
 
-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.
+Before deepening a design, understand only the material breadth:
 
-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.
+- complete caller outcome;
+- caller-owned decisions;
+- existing interface and dependencies;
+- canonical state and visible transitions;
+- success, failure, and recovery boundary;
+- current constraints and accepted non-goals;
+- evidence capable of changing the design route.
 
-## Start With Outcome And Failure
+Then deepen only the decision, seam, state boundary, or failure unit whose ownership could materially change the result.
 
-Before choosing classes, services, states, or adapters, ask:
+Do not broaden the task merely to complete the survey. Do not discuss every design topic, inspect every dependency, generate every alternative, or design the whole system.
 
-- 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?
+## Start Shallow
 
-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.
+For any coding or design task, ask:
 
-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.
+1. What complete outcome is changing?
+2. What must callers currently know or coordinate?
+3. Does this change add caller knowledge, spread policy, alter dependency direction, or change state or failure ownership?
+4. Would keeping the current boundary make correct use or the next likely change materially harder?
 
-## Hide Coordination
+When the change is local, source-backed, reversible, and leaves the interface, dependencies, state, and failure unit sound:
 
-Prefer interfaces where callers ask for an outcome and the module owns internal protocol.
+- apply this lens silently;
+- preserve accepted behavior;
+- do not load references;
+- do not present architectural alternatives;
+- do not widen the task.
 
-Before exposing a flag, state, path, filename, ordering rule, retry, timing behavior, or error, ask:
+A large mechanical change may need no design escalation. A one-line change may require it when permissions, canonical state, public behavior, compatibility, or consequential failure changes.
 
-- Does the caller own this choice?
+An abstraction is not required merely because code is duplicated, tests are awkward, or another design is imaginable.
+
+## Enter Early Or Re-enter From Evidence
+
+Use this lens early when ownership, interface, state, dependency, or failure decisions could harden into caller contracts before implementation.
+
+Early design may support:
+
+- discussion;
+- a Spec or Plan;
+- an API or module boundary;
+- a state transition;
+- a consequential integration;
+- test-seam selection.
+
+During implementation, testing, and review, preserve a supported boundary without reopening it merely because this lens remains in context.
+
+Re-enter later only when direct evidence shows:
+
+- caller coordination growing;
+- policy or state spreading;
+- repeated patches adding flags or lifecycle knowledge;
+- tests reproducing internal choreography;
+- dependencies or failures crossing unclear ownership;
+- prior boundary assumptions becoming false.
+
+When repeated or unexplained failure lacks a supported cause, use [Diagnose Failure](../diagnose-failure/SKILL.md) first. Diagnosis owns causal investigation. This lens consumes supported structural evidence without recreating the diagnosis.
+
+## Establish The Outcome And Failure Unit
+
+Before choosing classes, services, packages, adapters, or states, name:
+
+- caller and complete outcome;
+- caller-visible success and failure;
+- decisions the caller genuinely owns;
+- coordination or likely-changing policy the module could hide;
+- the **failure unit**: the coherent outcome treated as one success, failure, and recovery boundary.
+
+When the boundary has side effects, can leave partial state, or makes failure materially consequential, establish its **failure contract**:
+
+- who observes failure;
+- canonical and diagnostic state written;
+- forbidden partial outcomes;
+- stop, fail-open, fail-closed, degrade, retry, or escalation behavior;
+- cancellation and concurrency behavior when relevant;
+- safe restart, recovery, and reconciliation;
+- evidence required to prove the outcome.
+
+Failure behavior is part of the interface even when its mechanism remains private.
+
+Depth is not breadth. A deep module owns one coherent decision or failure unit. It does not collect unrelated responsibilities merely to reduce method count.
+
+Use [Decision Gate](../decision-gate/SKILL.md) when the boundary changes product behavior, public interfaces, compatibility, permissions, security, privacy, billing, data-loss behavior, migration direction, or another user-owned outcome.
+
+## Hide Coordination And Likely-Changing Decisions
+
+Prefer interfaces where callers request an outcome and the module owns its internal protocol.
+
+Before exposing a flag, path, state, ordering rule, retry, provider detail, timing behavior, dependency choice, or recovery step, ask:
+
+- Does the caller genuinely own this choice?
 - Does exposing it make correct use easier?
-- Is it stable enough to become a contract?
+- Is it stable enough to become a supported contract?
+- Which surrounding edits would occur if it changed?
 - Could one outcome-level operation hide it?
 
-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.
+Keep public:
+
+- caller-owned outcomes and decisions;
+- stable invariants;
+- necessary inputs;
+- observable success and failure semantics;
+- information required for correct recovery.
+
+Keep private unless callers genuinely control them:
+
+- sequencing;
+- storage layout;
+- provider mechanics;
+- retries and cleanup;
+- temporary states;
+- cache and optimization machinery;
+- diagnostic implementation;
+- dependency construction.
+
+A **seam** is a boundary where behavior, dependencies, or observation can change without forcing surrounding edits. An **enabling point** is where an adapter, test implementation, clock, probe, provider, or migration path enters that seam.
 
-Read [software design philosophy](references/software-design-philosophy.md) when the reason a design is shallow or coordination-heavy is unclear.
+Add a seam for demonstrated variation, a known migration, a required observation boundary, or a dependency that must be controlled in tests—not imagined flexibility.
 
 ## Recognize Structural Pressure
 
-Structural pressure exists when evidence shows that:
+Structural pressure is evidence that the current boundary is increasing coordination or hiding no useful decision.
+
+Pressure may appear as:
+
+- change amplification across unrelated callers;
+- caller lifecycle choreography;
+- scattered policy;
+- unowned canonical state or failure behavior;
+- growing flags, temporary states, retries, or recovery rules;
+- tests coupled to machinery rather than accepted behavior;
+- infrastructure details leaking into policy;
+- edge-case patches revealing one shared contract gap;
+- a bounded result unexpectedly requiring a subsystem.
+
+Ordinary bugs, failed tests, duplicate code, broad mechanical edits, finding count, and personal design preference do not prove structural pressure.
+
+When observed coordination could change the next route, read [Design Pressure Signals](references/design-pressure-signals.md). Skip it only when an equivalent route classification is already supported.
+
+When structural pressure is supported but the likely-changing decision or missing information-hiding boundary cannot yet be named, read [Software Design Philosophy](references/software-design-philosophy.md).
+
+Read the narrowest reference whose condition matches the current question. Read another only if its distinct question remains afterward.
+
+## Choose The Required Design Depth
+
+Read [Interface Design Loop](references/interface-design-loop.md) before:
+
+- comparing materially different interfaces;
+- selecting consequential ownership;
+- freezing an important correctness boundary;
+- choosing among real seam placements.
+
+Read [State And Failure Boundaries](references/state-and-failure-boundaries.md) when correctness materially depends on:
+
+- canonical state;
+- partial effects;
+- atomic visibility;
+- concurrency or cancellation;
+- idempotency and retries;
+- recovery or reconciliation;
+- failure evidence.
+
+Read [Module And Dependency Design](references/module-and-dependency-design.md) when the question materially concerns:
+
+- module decomposition;
+- cohesion and conceptual integrity;
+- dependency direction;
+- cycles or layering;
+- policy versus infrastructure;
+- shared ownership;
+- ports and adapters.
 
-- 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.
+Several references may apply to one consequential boundary. Read them one at a time and only while each distinct condition remains.
 
-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.
+## Test Through The Intended Interface
 
-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.
+The intended interface is the normal behavior and test surface.
 
-## Shape The Interface
+Question the design before adding test machinery when callers or tests must:
 
-When pressure changes the next action:
+- bypass the intended interface;
+- reproduce lifecycle choreography;
+- mock many internals to verify one outcome;
+- depend on private temporary states;
+- know dependency construction callers should not own.
 
-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.
+Do not redesign merely because an internal test observes internals. The problem is external callers requiring knowledge the module should hide.
 
-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.
+Architecture-bearing tests should protect:
 
-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.
+- accepted behavior;
+- visible failure;
+- state invariants;
+- forbidden partial outcomes;
+- settled recovery behavior;
+- a real dependency or observation seam.
 
-## Tests And Evidence
+Tests that protect only accidental machinery do not justify that machinery.
 
-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.
+Exploratory code can produce design evidence. It does not become production architecture without deliberate selection, authorized implementation, and verification at the required boundary.
 
-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.
+## Return The Narrowest Supported Route
 
-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.
+Return a changed ownership, scope, authority, or route boundary through [Workflow](../workflow/SKILL.md). Otherwise return to the active activity with:
 
-## Boundary Examples
+- structural evidence;
+- affected caller outcome;
+- interface, module, dependency, state, and failure unit involved;
+- likely-changing or currently unowned decision;
+- materially different alternatives only when real;
+- recommendation and assumptions;
+- unresolved user-owned decisions;
+- evidence still required;
+- narrowest route.
 
-- 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.
+Possible routes include:
 
-## Return The Route
+- continue with the current boundary;
+- make a local correction;
+- diagnose an unsupported cause;
+- revise a Spec or Plan;
+- use [Simplify Code](../simplify-code/SKILL.md) for behavior-preserving reduction;
+- run a bounded learning slice;
+- propose bounded deepening;
+- defer supported design pressure;
+- stop for owner direction.
 
-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.
 
-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.
+Freeze a supported boundary instead of pursuing architectural completeness. Retain the decision, not perpetual design activity.