@hassangameryt/freeflow 0.6.0 → 0.7.0

package/skills/decision-gate/SKILL.md

@@ -1,48 +1,106 @@
 ---
-name: decision-gate
-description: Use when proceeding would silently choose for the user, conflict with existing code, tests, docs, or requirements, or take a materially different path from what was requested or agreed.
+name: "decision-gate"
+description: "Use when proceeding would silently choose a consequential outcome for the user, or when accepted sources conflict in a way that leaves one material choice blocking the next action."
 ---
 
 # Decision Gate
 
-Stop before making a decision that belongs to the user or quietly changing the agreed path.
+Resolve one known blocking decision without making it for the user.
 
-The [Interaction Contract](../../runtime/prompts/interaction-contract.md) governs whether the user is asking, proposing, reasoning, or authorizing action. Decision Gate begins only after one blocking choice or conflict is clear. When the problem or alternatives still need broader exploration, read [Discuss](../discuss/SKILL.md) instead.
+A **blocking decision** is a choice whose realistic answers materially change the accepted outcome, scope, behavior, risk, persistence, compatibility, evidence boundary, or next safe action.
 
-## Stop Here
+Decision Gate is not general discussion, factual investigation, or an approval checkpoint for routine work. It begins only when one blocking choice or source conflict is clear enough to resolve with one direct question.
 
-Use the gate when:
+The [Interaction Contract](../../runtime/prompts/interaction-contract.md) governs whether the user is asking, proposing, deciding, or authorizing action. [Workflow](../workflow/SKILL.md) owns authority and routing.
 
-- the user must choose product behavior, scope, priorities, public interfaces, compatibility, permissions, security, privacy, billing, data-loss behavior, migration direction, or another hard-to-reverse outcome;
-- the request conflicts with existing code, tests, docs, policies, requirements, or established behavior;
-- the proposed action would materially change what was requested or agreed, including its evidence quality, risk, cost, persistence, or user-visible result;
-- new evidence exposes one known user choice or source conflict that must be resolved before proceeding.
+## Enter With One Decision
 
-Do not use the gate for facts that can be inspected, harmless local choices, or reversible implementation details that preserve the accepted outcome.
+Use Decision Gate only when:
 
-## Inspect Before Asking
+- the requested or accepted path is known;
+- one unresolved choice or material source conflict can be stated precisely;
+- available evidence and established source precedence do not already settle it;
+- different realistic answers would materially change what follows;
+- proceeding would silently decide for the user or override accepted source truth.
 
-Inspect code, tests, docs, policies, logs, repository state, or current external sources when they can answer the factual part of the problem.
+Do not use Decision Gate for:
 
-Ask the user only for a choice that remains theirs. If you cannot state the decision and meaningful alternatives clearly, the option space is not ready for a gate; use Discuss.
+- facts available through focused passive inspection;
+- reversible implementation details that preserve the accepted outcome;
+- ordinary authorization for one clear additional action;
+- preferences that do not affect the result or its acceptance;
+- hypothetical edge cases without supported reachability or consequence;
+- broad or unsettled option spaces that still require exploration.
+
+Use [Discuss](../discuss/SKILL.md) when the problem, alternatives, assumptions, or direction are not yet bounded enough for one decision.
+
+When several decisions appear, ask only the earliest one whose answer determines whether the others remain relevant. Do not turn the gate into an interview.
+
+## Resolve Facts Before Asking
+
+Inspect the smallest existing evidence that can settle the factual part: the current request, accepted decisions, code, tests, documentation, Specs, policies, ADRs, repository state, supplied artifacts, and current primary sources when relevant.
+
+Do not ask the user to choose between factual claims whose truth can be established from available evidence.
+
+When accepted sources appear to conflict:
+
+1. state each source's exact claim and applicable scope;
+2. determine whether each is current, accepted, draft, historical, generated, or advisory;
+3. apply repository-defined precedence or maintenance policy when one exists;
+4. identify the observable consequence of following each claim.
+
+A difference is material only when applicable sources make incompatible claims and selecting between them changes the accepted result or next safe action.
+
+Do not invent a universal hierarchy: code is not automatically correct because it runs, tests are not automatically requirements because they fail, documentation is not automatically stale because implementation differs, and task memory does not override live accepted source truth.
+
+If established precedence resolves the conflict, return the supported result to Workflow without asking a decision question. Updating an inconsistent source belongs to its owning activity and requires its own authority.
+
+If responsible framing requires new active evidence, return the exact claim, proposed observer, expected evidence, and stop condition to Workflow. Decision Gate does not run an experiment merely to make its question easier.
 
 ## Ask One Direct Question
 
-State:
+State proportionately:
 
-1. what was requested or previously agreed;
-2. the conflicting evidence, missing choice, or materially different path;
+1. the requested or previously accepted path;
+2. the exact missing choice or conflicting evidence;
 3. why it changes the next action;
-4. the meaningful options and tradeoffs;
+4. the realistic options and material tradeoffs;
 5. a recommendation when evidence supports one;
 6. one direct question that resolves the block.
 
+Frame the choice around the outcome the user owns, not ordinary implementation mechanics. Do not ask which file to change when the real decision is which behavior or contract should govern.
+
+Do not manufacture a menu. Omit dominated, unsafe, unavailable, or hypothetical options. A direct yes-or-no question is appropriate when one supported deviation needs a decision. Include preserving the current behavior, waiting, or stopping only when each is real.
+
+Recommend plainly when one path is better supported. State its principal tradeoff and what evidence or changed priority would alter the recommendation. A recommendation is not the user's decision.
+
 Then stop. Do not perform the blocked action in the same response.
 
-Urgency, approval to continue, reviewer confidence, or existing practice does not resolve an unnamed decision or conflict.
+Urgency, prior effort, reviewer confidence, common practice, or general approval to continue does not resolve an unnamed decision or source conflict.
+
+## Interpret And Return The Decision
+
+Treat an explicit choice as resolving only the decision that was asked. A question, criticism, hypothesis, preference, conditional answer, or request for more information is not automatically a decision; respond to its substance and keep the blocked action stopped.
+
+Route narrowly:
+
+- explicit choice with a clear covered path → Workflow;
+- answer that reopens alternatives or assumptions → Discuss;
+- unresolved factual evidence → Workflow and the appropriate evidence owner;
+- defer, preserve, or stop → return that outcome without forcing progress.
+
+A resolved decision may complete the missing intent for a still-valid request. It does not authorize unrelated effects or another outcome by implication.
+
+Return to Workflow with:
+
+- the exact decision and who or what established it;
+- the selected outcome and important exclusions;
+- material consequences and affected source truth;
+- remaining uncertainty or revisit condition;
+- the authority state of the next action.
 
-## Exit
+When losing the decision or its rationale could cause later misalignment, Workflow may route [Track Work](../track-work/SKILL.md) to preserve it. Decision Gate does not mutate task memory itself.
 
-Exit when the choice is explicit, the conflict is resolved, and remaining uncertainty would not change the next safe action.
+Do not broaden the answer, reinterpret it as approval for a different path, or continue past another separately controlled boundary.
 
-Preserve the decision accurately for the work that depends on it. Do not broaden the decision or treat it as approval for a different path.
+Stop when one direct question has been asked and no answer exists, the answer does not resolve the material block, the appropriate decision owner is unavailable, or active evidence is required before a responsible choice can be framed. A supported wait, deferment, preservation boundary, or stop is a valid result.

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

@@ -1,87 +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
 
-Use this lens 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, establish:
+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.
 
-- the complete outcome callers need and the decisions they genuinely own;
-- the coordination or likely-changing policy the module can hide;
-- visible success and the **failure unit**—the smallest outcome treated as one success, failure, and recovery boundary;
-- failure observers, state or evidence written, forbidden partial outcomes, response policy (stop, fail closed/open, degrade, retry, or escalate), safe restart, recovery, and required proof.
+## Start Shallow
 
-These form the **failure contract**. Failure behavior is part of the interface even when its mechanism remains private.
+For any coding or design task, ask:
 
-When the boundary changes 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:
 
-Read [software design philosophy](references/software-design-philosophy.md) when structural pressure is supported but the likely-changing decision or missing information-hiding boundary cannot yet be named.
+- 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.
+
+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 appears when caller knowledge, duplicated policy, lifecycle choreography, test-only exposure, or unowned failure behavior spreads across a boundary, or a bounded outcome requires an unplanned subsystem because no current seam owns it.
+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.
+
+Several references may apply to one consequential boundary. Read them one at a time and only while each distinct condition remains.
+
+## Test Through The Intended Interface
 
-Read [design pressure signals](references/design-pressure-signals.md) when that evidence may change the next route. The reference owns the detailed classifier and examples; the signals justify design attention, not automatic refactoring.
+The intended interface is the normal behavior and test surface.
 
-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.
+Question the design before adding test machinery when callers or tests must:
 
-## Shape The Interface
+- 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.
 
-Before comparing materially different interfaces, read [the interface design loop](references/interface-design-loop.md) when structural pressure or an important pre-implementation correctness boundary makes ownership consequential, especially when authority, canonical state, atomic visibility, replay, cancellation, or post-commit recovery affects correctness.
+Do not redesign merely because an internal test observes internals. The problem is external callers requiring knowledge the module should hide.
 
-The reference owns the complete comparison method. Prefer the interface that removes caller knowledge, localizes likely change, makes correct use easy, preserves honest failure and recovery, and costs proportionate evidence.
+Architecture-bearing tests should protect:
 
-Do not force multiple designs for an obvious local choice. When evidence cannot distinguish viable seams, use the reference's bounded learning route rather than quietly implementing the whole subsystem.
+- 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.