@hassangameryt/freeflow 0.7.2 → 0.8.0

package/skills/decision-gate/SKILL.md

@@ -9,13 +9,23 @@ Resolve one known blocking decision without making it for the user.
 
 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.
 
-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.
+Decision Gate is not general discussion, factual investigation, or an approval checkpoint for routine work. 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 [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 **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
+
+## Rules
+
+- After asking, stop. Do not perform the blocked action in the same response, and never settle a user-owned choice by proceeding.
+- Never ask the user to choose between factual claims that available evidence can settle.
+- Urgency, prior effort, reviewer confidence, common practice, or general approval to continue does not resolve an unnamed decision or source conflict.
+- An explicit choice resolves only the decision that was asked. A question, criticism, hypothesis, preference, conditional answer, or request for more information is not a decision, and no answer authorizes unrelated effects, another outcome, or a separately controlled boundary.
+- Decision Gate runs no experiments and does not change task memory; return those needs to Workflow.
 
 ## Enter With One Decision
 
-Use Decision Gate only when:
+Goal: use the gate only for a real, bounded, blocking choice.
+
+Use Decision Gate when:
 
 - the requested or accepted path is known;
 - one unresolved choice or material source conflict can be stated precisely;
@@ -23,24 +33,15 @@ Use Decision Gate only when:
 - different realistic answers would materially change what follows;
 - proceeding would silently decide for the user or override accepted source truth.
 
-Do not use Decision Gate for:
-
-- 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.
+Do not use it for 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, hypothetical edge cases without supported reachability or consequence, or broad option spaces that still need 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.
+When several decisions appear, ask 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.
+Goal: the question the user receives contains only what they must decide.
 
-Do not ask the user to choose between factual claims whose truth can be established from available evidence.
+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.
 
 When accepted sources appear to conflict:
 
@@ -49,16 +50,14 @@ When accepted sources appear to conflict:
 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.
+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 correct because it runs, tests are not requirements because they fail, documentation is not stale because implementation differs, and task memory does not override live accepted source truth.
 
-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.
+If established precedence resolves the conflict, return the supported result to Workflow without asking. Updating an inconsistent source belongs to its owning activity and needs its own authority. If framing the choice responsibly needs new active evidence, return the exact claim, proposed observer, expected evidence, and stop condition to Workflow.
 
 ## Ask One Direct Question
 
+Goal: the user can decide from one message, and knows what you recommend.
+
 State proportionately:
 
 1. the requested or previously accepted path;
@@ -68,39 +67,21 @@ State proportionately:
 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.
+Frame the choice around the outcome the user owns, not 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 yes-or-no question fits when one supported deviation needs a decision. Include preserving current behavior, waiting, or stopping only when each is real.
 
-Urgency, prior effort, reviewer confidence, common practice, or general approval to continue does not resolve an unnamed decision or source conflict.
+Recommend plainly when one path is better supported, with its principal tradeoff and what would change the recommendation. A recommendation is not the user's decision.
 
 ## 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:
+Goal: carry exactly the decision made, no more and no less, back to the work.
 
-- 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.
+Respond to the substance of anything that is not a decision, and keep the blocked action stopped. Route narrowly:
 
-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.
+- 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.
 
-Do not broaden the answer, reinterpret it as approval for a different path, or continue past another separately controlled boundary.
+A resolved decision may complete the missing intent for a still-valid request. 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, and the authority state of the next action. When losing the decision or its rationale could cause later misalignment, Workflow may route [Track Work](../track-work/SKILL.md) to preserve it.
 
-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.
+Stop when one direct question has been asked and no answer exists, the answer does not resolve the material block, the 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

@@ -7,13 +7,24 @@ description: "Use during coding and software design to keep boundaries, interfac
 
 Hide coherent, likely-changing decisions behind small, stable, outcome-level interfaces. Reduce the knowledge and coordination callers need without changing the accepted outcome.
 
-A module is anything with an interface and implementation. Its interface includes every fact a caller needs for correct use: operations, decisions, inputs, state, ordering, effects, errors, dependencies, timing, and recovery. Depth is useful coherent behavior and hidden complexity per unit of caller knowledge—not fewer methods or more responsibilities.
+A module is anything with an interface and an implementation. Its interface includes every fact a caller needs for correct use: operations, decisions, inputs, state, ordering, effects, errors, dependencies, timing, and recovery. A module is **deep** when it provides much useful, coherent behavior per unit of caller knowledge; depth is not fewer methods or more responsibilities.
 
-Use this lens under the current activity. It is not a mandatory phase, architecture owner, permission to refactor, or reason to make a local task larger.
+Use this lens under the current activity. It is not a mandatory phase, an architecture owner, or permission to refactor.
+
+The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
+
+## Rules
+
+- A design recommendation is not implementation authority, and this lens never enlarges a task by itself. A new dependency must earn its place through the accepted outcome or a demonstrated need.
+- Never remove required correctness, trust, or safety to make a design smaller. Never turn hypothetical lifecycle completeness into a production requirement.
+- Never design around an invented product or failure policy. When a boundary changes product behavior, public interfaces, compatibility, permissions, security, privacy, billing, data-loss behavior, migration direction, or another user-owned outcome, use [Decision Gate](../decision-gate/SKILL.md) with its concrete consequences and supported alternatives.
+- Do not invent APIs, files, or stronger guarantees to make a design look complete; name the missing observation or choice instead.
 
 ## Start With The Required Outcome
 
-Understand enough material breadth to identify the caller's complete outcome, accepted constraints, current interface, dependencies, canonical state, and relevant success/failure boundary. Do not survey the entire system or settle future variations without a present question.
+Goal: know whether the change touches a boundary worth designing, before designing anything.
+
+Understand enough breadth to identify the caller's complete outcome, accepted constraints, current interface, dependencies, canonical state, and relevant success and failure boundary. Do not survey the entire system or settle future variations without a present question.
 
 Ask:
 
@@ -22,96 +33,76 @@ Ask:
 3. Does the change spread policy, state, dependency choices, or lifecycle knowledge?
 4. Would the current boundary make correct use or the next likely change materially harder?
 
-For a local, source-backed, reversible change that leaves these boundaries sound, apply the lens silently and continue. Do not load additional references, generate alternatives, or introduce an abstraction merely because another shape is imaginable.
-
-A large mechanical change may need no design escalation. A one-line change may need it when it changes permissions, public behavior, canonical state, or consequential failure semantics.
+For a local, source-backed, reversible change that leaves these boundaries sound, apply the lens silently and continue: load no references, generate no alternatives, add no abstraction because another shape is imaginable. A large mechanical change may need no design escalation; a one-line change may need it when it changes permissions, public behavior, canonical state, or consequential failure semantics.
 
 ## Intervene Where The Decision Can Still Change
 
-Use the lens early when interface, ownership, state, or failure choices could harden into caller contracts. It can support discussion, a Spec or Plan, implementation preparation, or selecting a test seam.
+Goal: settle consequential choices before they harden into caller contracts, and leave ordinary mechanics free.
 
-Before substantial implementation, or before writing its guiding design, read [Implementation Decisions](references/implementation-decisions.md) when unresolved representation, identity, ownership, algorithm, or failure choices could invalidate significant dependent work. Select a supported mechanism or identify the missing observation; leave ordinary mechanics free. The reference helps make those choices explicit and check their realization, not impose a blueprint on every task.
+Use the lens early when interface, ownership, state, or failure choices could harden. It can support discussion, a Spec or Plan, implementation preparation, or choosing a test seam.
 
-Once a boundary is supported, do not reopen it merely because the skill remains in context. Re-enter when evidence shows growing caller coordination, scattered policy, exposed internal states, fragile test choreography, unclear dependency/failure ownership, or an invalidated design assumption.
+Read [Implementation Decisions](references/implementation-decisions.md) when unresolved representation, identity, ownership, algorithm, dependency, or failure choices could materially change a technical recommendation or invalidate significant dependent work, before recommending a mechanism, writing its guiding design, or beginning substantial implementation.
 
-Ordinary bugs, duplication, test awkwardness, finding count, and preference do not establish structural pressure. Use [Diagnose Failure](../diagnose-failure/SKILL.md) first when repeated or unexplained failures lack a supported cause. This lens consumes the structural finding rather than inventing one.
+Once a boundary is supported, do not reopen it because this skill remains in context. Re-enter when evidence shows growing caller coordination, scattered policy, exposed internal states, fragile test choreography, unclear dependency or failure ownership, or an invalidated design assumption. Ordinary bugs, duplication, test awkwardness, finding count, and preference do not establish structural pressure. Use [Diagnose Failure](../diagnose-failure/SKILL.md) first when repeated or unexplained failures lack a supported cause; this lens consumes a structural finding rather than inventing one.
 
 ## Bound Success And Failure Proportionately
 
-Before selecting classes, services, packages, flags, or states, name:
+Goal: the failure behavior that matters is owned, and nothing more is built.
+
+Before choosing classes, services, packages, flags, or states, name:
 
 - the caller and complete accepted outcome;
-- caller-owned decisions and observable success/failure;
+- caller-owned decisions and observable success and failure;
 - the likely-changing coordination the module could hide;
-- the failure unit: what must be treated as one coherent success, failure, and recovery boundary.
+- the **failure unit**: what must succeed, fail, and recover as one coherent boundary.
 
-Where effects or partial state are consequential, establish the material failure contract: observer, canonical/diagnostic state, forbidden outcomes, stop/degrade/fail/retry behavior, and supported recovery. Include cancellation, concurrency, or reconciliation only where required behavior or observed reachability makes them material.
+Where effects or partial state are consequential, establish the material failure contract: observer, canonical and diagnostic state, forbidden outcomes, stop/degrade/fail/retry behavior, and supported recovery. Include cancellation, concurrency, or reconciliation only where required behavior or observed reachability makes them material. Read [State And Failure Boundaries](references/state-and-failure-boundaries.md) when correctness depends on them.
 
-Distinguish required correctness and safety from optional stronger guarantees. Do not remove required behavior to make the design smaller, or turn hypothetical lifecycle completeness into a production requirement. A module owning a failure unit does not automatically need durable replay, rollback, universal provenance, or every possible recovery mechanism.
-
-Use [Decision Gate](../decision-gate/SKILL.md) when the proposed boundary changes product behavior, public interfaces, compatibility, permissions, security, privacy, billing, data-loss behavior, migration direction, or another user-owned outcome. Explain concrete consequences and supported alternatives, not only an architectural label.
+Distinguish required correctness and safety from optional stronger guarantees. Efficiency, scale, and portability need an accepted requirement or observed pressure before they shape the design. A module owning a failure unit does not automatically need durable replay, rollback, universal provenance, or every recovery mechanism.
 
 ## Hide Coordination Without Hiding Caller Choices
 
-Prefer operations through which callers request an outcome and the module owns the internal protocol.
+Goal: callers request outcomes; the module owns the protocol.
 
 Before exposing a flag, path, state, ordering rule, retry, provider detail, or recovery step, ask whether the caller genuinely owns it, whether it makes correct use easier, and whether it is stable enough to become a supported contract.
 
-Keep public:
-
-- caller-owned outcomes and decisions;
-- necessary inputs and stable invariants;
-- observable success/failure;
-- information required for correct recovery.
+Keep public: caller-owned outcomes and decisions, necessary inputs and stable invariants, observable success and failure, and information required for correct recovery. Keep internal unless callers genuinely control it: sequencing, storage layout, dependency construction, provider mechanics, retries, cleanup, temporary states, caches, optimization machinery, and diagnostic details.
 
-Keep internal unless callers genuinely control it:
+A **seam** lets behavior, a dependency, or an observer change without coordinated surrounding edits; the adapter, clock, provider, or probe that plugs into it is what varies. Add one for demonstrated variation, a known migration, a required observer, or a dependency needing control, not for imagined flexibility.
 
-- sequencing, storage layout, dependency construction, and provider mechanics;
-- retries, cleanup, temporary states, caches, and optimization machinery;
-- diagnostic implementation details.
-
-A seam permits behavior, dependency, or observation changes without coordinated surrounding edits. An enabling point admits the adapter, clock, provider, or probe at that seam. Add one for demonstrated variation, a known migration, a required observer, or a dependency needing control—not imagined flexibility.
-
-Do not centralize unrelated responsibilities merely to reduce interface count or scatter an old protocol into callers while claiming an abstraction was removed.
+Do not centralize unrelated responsibilities to reduce interface count, or scatter an old protocol into callers while claiming an abstraction was removed.
 
 ## Load Only The Depth The Question Needs
 
-Read [Design Pressure Signals](references/design-pressure-signals.md) when observed coordination could change the route, unless an equivalent classification is already supported.
-
-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.
-
-Read [Interface Design Loop](references/interface-design-loop.md) before comparing materially different interfaces, choosing consequential ownership, freezing an important correctness boundary, or choosing among real seam placements.
+Goal: read the one reference that answers the open question, and stop.
 
-Read [State And Failure Boundaries](references/state-and-failure-boundaries.md) when correctness materially depends on canonical state, partial effects, atomic visibility, concurrency, cancellation, retries, idempotency, recovery, reconciliation, or failure evidence.
+- [Design Pressure Signals](references/design-pressure-signals.md): observed coordination could change the route, or pressure is supported but the missing boundary cannot yet be named.
+- [Interface Design Loop](references/interface-design-loop.md): comparing materially different interfaces, choosing consequential ownership, freezing an important correctness boundary, or choosing among real seam placements.
+- [State And Failure Boundaries](references/state-and-failure-boundaries.md): correctness depends on canonical state, partial effects, atomic visibility, concurrency, cancellation, retries, idempotency, recovery, reconciliation, or failure evidence.
+- [Module And Dependency Design](references/module-and-dependency-design.md): decomposition, cohesion, dependency direction, cycles, layering, shared ownership, policy versus infrastructure, or ports and adapters.
 
-Read [Module And Dependency Design](references/module-and-dependency-design.md) for decomposition, cohesion, dependency direction, cycles, layering, shared ownership, policy versus infrastructure, or ports/adapters.
-
-Read references one at a time while each distinct question remains. Do not convert their checklists into obligations unrelated to the accepted result.
+Read references one at a time while each distinct question remains. Do not convert their lists into obligations unrelated to the accepted result.
 
 ## Learn Without Building The Future System
 
-When existing evidence cannot distinguish viable boundaries, frame a bounded prototype or observation through the current owner: question, alternatives, adequate observer, permitted effects, evidence, return condition, and disposition.
+Goal: when evidence cannot choose between boundaries, answer that question cheaply.
 
-The experiment must answer the design question. If its next prerequisite is actually future production infrastructure, reassess before building it. One failed extension or matching technique is not proof that every in-scope approach is impossible.
+Frame a bounded prototype or observation through the current owner: question, alternatives, adequate observer, permitted effects, evidence, return condition, and disposition. The experiment must answer the design question; if its next prerequisite is future production infrastructure, reassess before building it. One failed extension or technique does not prove every in-scope approach impossible.
 
-Return a supported boundary or an explicit limitation. Working exploratory code is evidence, not automatic production architecture. Promotion requires deliberate selection and authority, and a negative answer does not require another increasingly broad prototype.
+Return a supported boundary or an explicit limitation. Working exploratory code is evidence, not production architecture; promotion needs deliberate selection and authority, and a negative answer does not require another, broader prototype.
 
 ## Check Through The Intended Interface
 
-The intended interface should normally be the behavior and test surface. Question test machinery when callers or tests must bypass it, coordinate private lifecycle steps, replace many internals, or know dependency construction the module should own.
-
-An internal test inspecting internals is not itself a design defect. The concern is callers requiring knowledge the module should hide, or a fixture manufacturing the behavior it claims to observe.
+Goal: tests protect the behavior callers rely on, not the machinery.
 
-Architecture-bearing checks should protect accepted behavior, visible failures, required state invariants, forbidden partial outcomes, settled recovery, and real dependency or observation seams. Tests that protect accidental machinery do not justify keeping that machinery.
+The intended interface should normally be the behavior and test surface. Question the design when callers or tests must bypass it, coordinate private lifecycle steps, replace many internals, or know dependency construction the module should own. An internal test inspecting internals is not itself a defect; the concern is callers needing hidden knowledge, or a fixture manufacturing the behavior it claims to observe.
 
-Test order is not a design criterion. Choose boundaries for the actual caller and supported variation, not to satisfy a formal implementation sequence.
+Architecture-bearing checks protect accepted behavior, visible failures, required state invariants, forbidden partial outcomes, settled recovery, and real dependency or observation seams. Tests that protect accidental machinery do not justify keeping it. Test order is not a design criterion.
 
 ## Return The Smallest Supported Change
 
 Return to [Workflow](../workflow/SKILL.md) when ownership, scope, authority, or the route changes. Otherwise return to the current activity with the structural evidence, affected outcome, boundary, likely-changing decision, assumptions, and remaining evidence or user-owned choice.
 
-Compare alternatives only when real. Recommend the simplest supported boundary that preserves required behavior; explain the principal cost and what would invalidate the recommendation.
-
-Possible results include keeping the existing design, a local correction, diagnosis, an artifact revision, a bounded learning action, an accepted deepening, explicit deferral, or a stop for owner direction. Use [Simplify Code](../simplify-code/SKILL.md) when the selected result is behavior-preserving reduction.
+Compare alternatives only when real. Recommend the simplest supported boundary that preserves required behavior, with its principal cost and what would invalidate it. Results include keeping the existing design, a local correction, diagnosis, an artifact revision, a bounded learning action, an accepted deepening, explicit deferral, or a stop for owner direction. Use [Simplify Code](../simplify-code/SKILL.md) when the selected result is behavior-preserving reduction.
 
-Freeze a sufficiently supported boundary instead of pursuing architectural completeness. A recommendation is not implementation authority, and a new dependency must earn its place through the accepted outcome or demonstrated need.
+Freeze a sufficiently supported boundary instead of pursuing architectural completeness.

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

@@ -1,8 +1,8 @@
 # Design Pressure Signals
 
-Read this when observed coordination could change the next route and an equivalent design-route classification is not already supported.
+Read this when observed coordination could change the next route and an equivalent design-route classification is not already supported, or when structural pressure is supported but the likely-changing decision or missing information-hiding boundary cannot yet be named.
 
-Do not count smells. Identify the pressure that changes the next action, or conclude that none does.
+This reference is judgment. Identify the pressure that changes the next action, or conclude that none does; do not count smells, and do not produce a literature review or system-wide redesign.
 
 ## Classify The Evidence
 
@@ -17,166 +17,68 @@ Ask:
 
 Choose the narrowest supported route:
 
-- **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.
+- **Continue:** the current boundary remains sound.
+- **Local correction:** the defect stays within one module and contract.
+- **Diagnosis:** a failure is repeated or unexplained and its cause is unsupported.
+- **Spec or Plan revision:** behavior, acceptance, or the execution boundary is incomplete.
+- **User decision:** resolving the 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.
+- **Deepening:** a supported information-hiding improvement fits accepted scope.
+- **Deferred deepening:** the pressure is real but not worth resolving now.
 
-## Change Amplification
+## Recognize The Signals
 
-Pressure exists when one policy change requires unrelated edits across callers.
+Complexity is coordination, not line count. It shows up as change amplification (one change needs many surrounding edits), cognitive load (callers must remember many facts), obscurity (important rules are hard to find), dependency burden (safe change needs unrelated modules understood), and unknown unknowns (a caller cannot tell what else to inspect). A large implementation can be simple to use; a small helper can be complex when every caller must know its quirks.
 
-Example:
+- **Change amplification.** One policy change needs edits across unrelated callers, such as a retry policy touching routes, workers, UI state, and tests. Name the decision causing the edits; do not merely move the same choreography into one helper.
+- **Caller protocol growth.** Callers perform internal lifecycle steps (`configure -> open -> retry -> translate error -> clean up -> publish evidence`), each correction adds a state or flag, recovery becomes ordinary caller behavior, or callers depend on paths, filenames, provider errors, or queue names. Ask whether one operation can own the complete success and failure unit while publishing diagnostics separately.
+- **Scattered policy.** One product or operational decision is encoded in several places, such as billing transition timing in a webhook, dashboard, email, and worker. Do not centralize it until the policy is accepted; stop for a decision when it is user-owned or conflicting.
+- **Unowned state or failure.** No module owns canonical state and its visibility point, forbidden partial outcomes, retry or escalation, cancellation and reconciliation, recovery after partial completion, or the evidence proving the final state.
+- **Contract-surface growth.** Each patch adds public flags, temporary states, manifest fields, retry links, recovery instructions, provider-specific errors, or cache and integrity controls. Ask whether callers own those facts or are being forced to understand internal protocol.
+- **Distorted tests.** Tests reproduce caller choreography, mock many helpers to verify one outcome, depend on private lifecycle states, protect machinery from recent patches, prove rejection without checking forbidden writes, or make provider mechanics look like domain requirements. First inspect whether the production boundary owns the complete behavior; do not automatically add mocks or test-only seams.
+- **Edge-case patch streams.** Related fixes keep adding conditions, states, or caller rules (missing contact, then fallback, then duplicate delivery, then retry telemetry, then another exposed state). Diagnose whether the cases share one missing contract, state owner, or failure unit; finding count alone is not architecture.
+- **Scope growth.** A bounded result unexpectedly needs a subsystem, expands remaining work, pulls in deferred capabilities, invalidates earlier evidence, or requires unrelated callers to change. Return the evidence; the route may be simplify, split, revise an artifact, learn, defer, or stop.
 
-```text
-Changing retry policy requires edits in API routes, workers,
-UI state, and tests.
-```
-
-Name the decision causing the edits. Do not merely move the same choreography into one helper.
-
-## Caller Protocol Growth
-
-Pressure exists when callers must perform internal lifecycle steps:
-
-```text
-configure -> open -> retry -> translate error -> clean up -> publish evidence
-```
-
-Related signals:
-
-- 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.
-
-Ask whether one operation can own the complete success and failure unit while publishing diagnostics separately.
-
-## Scattered Policy
-
-Pressure exists when one product or operational decision is encoded in several places.
-
-Example:
-
-```text
-billing transition timing appears separately in webhook,
-dashboard, email, and worker behavior.
-```
-
-Do not centralize behavior until the policy is accepted. When it is user-owned or conflicting, stop for a decision.
-
-## Unowned State Or Failure
-
-Pressure exists when no module owns:
-
-- 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.
-
-Do not design architecture around an invented failure policy.
+Common interface mismatches:
 
-## Contract-Surface Growth
+- **Pass-through wrapper:** renames a call without hiding policy or provider behavior; keep it only for a real domain, compatibility, or observation boundary.
+- **Leaky interface:** callers know infrastructure-specific details.
+- **God module:** unrelated decisions collected behind one interface.
+- **Speculative seam:** indirection for imagined variation.
+- **Dependency cycle:** modules cannot change independently because their responsibilities point at each other.
+- **Premature artifact detail:** a Spec or Plan freezes classes, factories, tables, or algorithms before evidence supports the boundary.
 
-Pressure exists when each patch adds public:
+## Rule Out False Positives
 
-- flags;
-- temporary states;
-- manifest fields;
-- retry links;
-- recovery instructions;
-- provider-specific errors;
-- cache or integrity controls.
+Do not escalate when stable repetition is small and local, broad edits are mechanical and source-backed, a one-off script needs no long-term abstraction, a wrapper preserves a real compatibility contract, an isolated condition is wrong but the interface is sound, an internal test intentionally verifies an internal module, or resolving the pressure would exceed the user's goal without blocking it.
 
-Ask whether callers own those facts or are being forced to understand internal protocol.
+## Name The Missing Boundary
 
-## Distorted Tests
+When pressure is supported, find the decision the module should hide.
 
-Pressure exists when tests:
+Organize modules around decisions likely to change, not processing steps. Instead of exposing `parse -> validate -> retry -> send -> log -> clean up`, look for the decision those steps implement, such as a notification delivery policy. Ask which decision would cause the most surrounding edits if it changed, which callers know it now, who should own it, what outcome-level interface would let callers stop knowing it, and whether it is accepted or still user-owned. Failure and recovery policy are often the likely-changing decision.
 
-- 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.
+A deep module lets callers state the outcome while it owns sequencing, likely-changing policy, internal transitions, cleanup, provider mechanics, and internal failure handling. A wrapper is not deep because it hides lines; it is deep when callers stop knowing concepts or coordinating protocol. Depth is not breadth: a god module hiding unrelated decisions is not deep.
 
-Do not automatically add mocks or test-only seams. First inspect whether the production boundary owns the complete behavior.
+Prefer proportionate strategic design over tactical patching, not maximal architecture: stop the current patch when it clearly spreads a likely-changing decision, adds caller protocol, exposes internal state, creates another required workaround, or makes the next accepted change materially harder.
 
-An intentional internal test is not a defect merely because it observes internals.
+Preserve conceptual integrity: one coherent model of the outcome, state, and failure behavior. Pressure exists when a concept has different names or rules across callers, several modules partly own one decision, callers translate between incompatible representations, or each feature adds another exception to the shared concept. This does not mean one module or one abstraction.
 
-## Edge-Case Patch Streams
+Every observable fact is a contract callers may depend on: flags, paths, states, errors, timing rules, fallbacks, ordering, filenames, retry counts. Expose a fact only when the caller owns the decision, correct use requires it, it is stable enough to support, and its compatibility cost is understood.
 
-Pressure exists when related fixes repeatedly add conditions, states, or caller rules.
+Classify each proposed mechanism by what it is for: **trust** (knowing the result is valid), **safety** (preventing damage, leakage, or runaway behavior), **efficiency**, **scale**, or **portability**. Trust and safety cannot be deferred to simplify a design; efficiency, scale, and portability need an accepted requirement or observed pressure.
 
-Example:
+Name the boundary with supported evidence:
 
 ```text
-handle missing contact
--> handle fallback
--> handle duplicate delivery
--> handle retry telemetry
--> expose another state to callers
+Outcome:
+Coordination currently spread across:
+Likely-changing decision:
+Current owners:
+Proposed owner:
+What callers would stop knowing:
+Failure unit:
+Evidence still missing:
 ```
 
-Do not infer architecture from finding count alone. Diagnose whether the cases share one missing contract, state owner, or failure unit.
-
-## Scope Growth
-
-Pressure exists when a bounded result unexpectedly:
-
-- requires a subsystem;
-- expands remaining work;
-- pulls deferred capabilities into scope;
-- invalidates earlier evidence;
-- requires unrelated callers to change.
-
-Return the evidence. The correct route may be simplify, split, revise an artifact, learn, defer, or stop.
-
-## Common Interface Mismatches
-
-### Pass-through wrapper
-
-Renames a call without hiding policy or provider behavior.
-
-Keep only when it preserves a real domain, compatibility, or observation boundary.
-
-### Leaky interface
-
-Callers know infrastructure-specific details.
-
-### God module
-
-Unrelated decisions are collected behind one interface.
-
-### Speculative seam
-
-Indirection exists only for imagined variation.
-
-### Dependency cycle
-
-Modules cannot change independently because their responsibilities point at each other.
-
-### Premature artifact detail
-
-A Spec or Plan freezes classes, factories, tables, or algorithms before evidence supports the boundary.
-
-## False Positives
-
-Do not escalate when:
-
-- stable repetition remains small and local;
-- broad edits are mechanical and source-backed;
-- 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.
-
-Stop once the route is classified. Return evidence and classification; do not redesign automatically.
+If the decision cannot yet be named, define one bounded learning question rather than a generic abstraction. Stop once the route is classified and the missing boundary is named, or evidence shows no worthwhile boundary change; return the evidence and classification without redesigning automatically.

package/skills/design-for-depth/references/implementation-decisions.md

@@ -1,12 +1,12 @@
 # Implementation Decisions
 
-Read this before substantial implementation, or before writing its guiding design, when unresolved representation, identity, ownership, algorithm, or failure choices could invalidate significant dependent work. Skip it for a supported local change whose remaining mechanics do not alter those boundaries.
+Read this when unresolved representation, identity, ownership, algorithm, dependency, or failure choices could materially change a technical recommendation or invalidate significant dependent work. Apply it before recommending a mechanism during discussion, writing its guiding design, or beginning substantial implementation. Skip it for a supported local change whose remaining mechanics do not alter those boundaries.
 
-Use this method under Design for Depth and the current activity. It does not create another planning phase, document requirement, approval gate, or compute role.
+This reference is judgment, used under Design for Depth and the current activity. It does not create another planning phase, document requirement, approval gate, or compute role.
 
 ## Identify What Implementation Would Still Have To Invent
 
-Start from the accepted outcome, relevant source evidence, and existing design. Ask:
+Start from the current goal and constraints, relevant source evidence, and existing design. During discussion, mark unsettled outcomes and approaches as provisional: compare their consequences without turning an explored option into an accepted requirement. Select supported engineering details within the agreement; return user-owned choices through the current activity. Ask:
 
 > Which remaining choices could change correctness, complexity, failure behavior, or force substantial dependent work to be redone?
 
@@ -73,4 +73,4 @@ Weak direction: "Make persistence idempotent and robust."
 
 Useful direction: "The append owner distinguishes observed acknowledgment from an uncertain attempt. An equal entry in memory does not resolve an earlier failure. Validate before mutation; publish accepted state only at the supported acknowledgment boundary. Test append advancing memory then failing, followed by the identical operation: uncertainty must remain until supported reconciliation. Also test an acknowledged duplicate so the implementation does not reject every retry. Do not infer filesystem durability from readback. Reconsider the mechanism if the actual host boundary differs."
 
-Stop when the next implementation has a supported approach and intentional local freedom, or its blocking question is explicit. Do not pursue a complete blueprint for later work whose premises remain unsettled.
+Stop when the current discussion has a supported recommendation or explicit open question, or the next implementation has a supported approach and intentional local freedom. Preserve provisional versus accepted decisions when passing the result back to the current activity; discussion does not authorize implementation. Do not pursue a complete blueprint for later work whose premises remain unsettled.