@hassangameryt/freeflow 0.8.0 → 0.9.0

package/skills/decision-gate/SKILL.md

@@ -1,87 +0,0 @@
----
-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
-
-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. 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
-
-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;
-- 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.
-
-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 the earliest one whose answer determines whether the others remain relevant. Do not turn the gate into an interview.
-
-## Resolve Facts Before Asking
-
-Goal: the question the user receives contains only what they must decide.
-
-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:
-
-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 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 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;
-2. the exact missing choice or conflicting evidence;
-3. why it changes the next action;
-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 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.
-
-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
-
-Goal: carry exactly the decision made, no more and no less, back to the work.
-
-Respond to the substance of anything that is not a decision, 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. 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 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,108 +0,0 @@
----
-name: design-for-depth
-description: "Use during coding and software design to keep boundaries, interfaces, ownership, state, dependencies, and failure behavior simple and proportionate."
----
-
-# Design For Depth
-
-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 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, 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
-
-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:
-
-1. What outcome is changing?
-2. What must callers currently know or coordinate?
-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: 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
-
-Goal: settle consequential choices before they harden into caller contracts, and leave ordinary mechanics free.
-
-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.
-
-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.
-
-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
-
-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 and failure;
-- the likely-changing coordination the module could hide;
-- 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 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. 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
-
-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 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.
-
-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.
-
-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
-
-Goal: read the one reference that answers the open question, and stop.
-
-- [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 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
-
-Goal: when evidence cannot choose between boundaries, answer that question cheaply.
-
-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 production architecture; promotion needs deliberate selection and authority, and a negative answer does not require another, broader prototype.
-
-## Check Through The Intended Interface
-
-Goal: tests protect the behavior callers rely on, not the 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.
-
-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, 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.

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

@@ -1,84 +0,0 @@
-# Design Pressure Signals
-
-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.
-
-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
-
-Ask:
-
-1. What caller outcome and interface are affected?
-2. What facts must callers know or coordinate?
-3. Did the current change add to that knowledge?
-4. What policy, dependency, state transition, or failure behavior is spreading?
-5. Is the cause supported?
-6. Can the issue be resolved inside accepted scope and authority?
-
-Choose the narrowest supported route:
-
-- **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:** a supported information-hiding improvement fits accepted scope.
-- **Deferred deepening:** the pressure is real but not worth resolving now.
-
-## Recognize The Signals
-
-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.
-
-- **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.
-
-Common interface mismatches:
-
-- **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.
-
-## Rule Out False Positives
-
-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.
-
-## Name The Missing Boundary
-
-When pressure is supported, find the decision the module should hide.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-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.
-
-Name the boundary with supported evidence:
-
-```text
-Outcome:
-Coordination currently spread across:
-Likely-changing decision:
-Current owners:
-Proposed owner:
-What callers would stop knowing:
-Failure unit:
-Evidence still missing:
-```
-
-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,76 +0,0 @@
-# Implementation Decisions
-
-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.
-
-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 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?
-
-Name the actual question, not a generic demand for more design. For example, deciding which occurrence identifies a source matters more than choosing Map versus array; deciding what survives a failed transfer matters more than choosing a retry helper.
-
-For each consequential unknown, choose one route:
-
-- **Evidence supports a mechanism:** select it and explain why it fits.
-- **An environmental fact is missing:** identify the observation that distinguishes the alternatives before dependent implementation.
-- **A user-owned boundary is unsettled:** return that choice through the current owner.
-- **Only ordinary mechanics remain:** leave them to implementation and continue.
-
-Do not invent APIs, future files, or stronger guarantees to complete the design. Nor should the user have to choose implementation syntax: explain user-owned consequences and resolve supported engineering details within the agreement.
-
-## Choose The Representation And Mechanism
-
-Develop only the decisions that answer the current question. Reuse supported design rather than filling every category:
-
-| Decision | Make explicit when material |
-| --- | --- |
-| Representation and identity | Domain objects and independent lifetimes; what counts as the same occurrence; what must remain distinct |
-| State and ownership | Authoritative facts, derived caches, transition owner, and permitted mutations |
-| Algorithm and cost | Essential steps; collection keys and relationships; update/invalidation rules; work repeated as input grows |
-| Effects and failure | Required ordering; what is accepted or visible at each boundary; what survives failure and what may be retried |
-| Modules and dependencies | Who hides each decision; which callers consume the result; dependencies or coordination that must not spread |
-| Evidence | Observable required behavior and a plausible wrong implementation the check must reject |
-
-Use Design for Depth's interface, state/failure, and module references when their named questions need resolution; do not repeat their full methods here. Compare materially different approaches only when they remain viable. Prefer eliminating unnecessary coordination to hiding the same protocol behind another helper.
-
-## Preserve The Decision, Not A Complete Patch
-
-Communicate enough for another implementer, or your later context, to retain the chosen approach:
-
-- the decision and its source basis;
-- why it fits and the invariant it protects;
-- the essential mechanism, including a small type or control-flow sketch when useful;
-- the counterexample and distinguishing observer;
-- required constraints versus suggested mechanics and local freedom;
-- the evidence or condition that would invalidate the choice.
-
-Use a paragraph, example, or compact table. Do not prescribe every loop or helper, or reproduce the whole program in prose. Naming a data structure without its keys, meaning, and maintenance rules is not useful algorithmic direction.
-
-Keep durable decisions in the owning technical design; keep execution order in the Plan and changed understanding in task memory. A current assignment should carry the applicable decisions and relevant source section, not another complete copy of every artifact. A path or hash does not establish that its contents are available to the implementer.
-
-## Check Realization Before Dependent Expansion
-
-When an unfamiliar boundary could invalidate substantial later work, choose the first coherent implementation path that can disagree with the design. It may span several files and a failure case. A skeleton, happy-path result, or green summary alone may not exercise the decision.
-
-Assess the actual implementation and observation: which important choices were realized, omitted, contradicted, or replaced with a supported reason? Check ownership, identity, ordering, and the observer—not fidelity to suggested filenames or helper syntax.
-
-A precise sketch can be wrong. Preserve accepted behavior, stop dependent effects when the mechanism is invalidated, and resolve the affected choice through the current owner. Supported local corrections need no design restart. Once the boundary is established, reuse it rather than repeating this assessment after every edit.
-
-## Examples
-
-### Identity And Indexing
-
-Weak direction: "Use a Map and avoid repeated scans."
-
-Useful direction: "Keep native occurrence IDs as source identity. Equal bodies may identify several candidates; do not merge their occurrences. Let the source owner maintain the result-to-exchange relationship. Update appended sources and rebuild affected indexes after ancestry replacement. Check repeated equal bodies, late attribution, and a branch change; measure the repeated preparation path rather than only an isolated lookup. Helper layout is local. Reconsider the index if the source does not provide the assumed stable identity."
-
-### Acknowledgment And Retry
-
-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 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.

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

@@ -1,105 +0,0 @@
-# Interface Design Loop
-
-Read this before comparing materially different interfaces or settling an important correctness boundary where ownership is consequential.
-
-This reference is judgment. Use only evidence and criteria capable of distinguishing viable boundaries; the numbered steps are an order of thinking, not output to emit.
-
-## 1. Frame The Complete Outcome
-
-Orient broadly enough to state:
-
-- caller and complete outcome;
-- source-backed behavior and non-goals;
-- decisions the caller genuinely owns;
-- dependencies and current constraints;
-- material state and failure boundaries;
-- why the current seam requires attention.
-
-Do not begin from existing flags, storage paths, classes, or temporary states. They may be symptoms of the current design.
-
-## 2. Define The Failure Unit
-
-Name the failure unit as Design for Depth's Bound Success And Failure describes, including whether partial reuse is required or merely an optimization. When correctness depends on canonical state, partial effects, atomic visibility, concurrency, cancellation, retries, recovery, reconciliation, or final-outcome evidence, read [State And Failure Boundaries](state-and-failure-boundaries.md).
-
-## 3. Inventory Material Caller Knowledge
-
-List only facts callers must know and that could affect the boundary:
-
-- operations and inputs;
-- caller-owned decisions;
-- ordering and lifecycle states;
-- configuration and provider details;
-- dependencies;
-- errors and failure semantics;
-- compatibility and migration;
-- recovery, cost, and performance expectations.
-
-For each fact ask:
-
-- Does the caller own it?
-- Could the module own it?
-- Is it stable enough to expose?
-- Would changing it force surrounding edits?
-
-The goal is not zero interface knowledge. It is the smallest honest contract.
-
-## 4. Classify What Each Mechanism Is For
-
-Separate required trust and safety from efficiency, scale, and portability, as [Design Pressure Signals](design-pressure-signals.md) describes. Do not defer required correctness for a simpler-looking interface, or promote hypothetical efficiency, scale, or portability into present architecture.
-
-## 5. Produce Alternatives Only When Real
-
-When materially different ownership choices remain viable, design two or three interfaces that change seam placement—not only terminology.
-
-For each show:
-
-1. ordinary caller usage;
-2. caller-owned decisions;
-3. hidden internal protocol;
-4. failure unit and observable behavior;
-5. dependency and adapter strategy;
-6. evidence needed;
-7. material cost or limitation.
-
-When module decomposition, cohesion, dependency direction, cycles, layering, policy-versus-infrastructure ownership, or change propagation materially affects the design, read [Module And Dependency Design](module-and-dependency-design.md).
-
-Do not manufacture alternatives for a local, reversible, source-backed choice.
-
-## 6. Compare On Discriminating Criteria
-
-Use only criteria that could change the recommendation:
-
-- behavior per interface fact;
-- locality of likely change;
-- cohesion and ownership clarity;
-- correct-use ergonomics;
-- misuse and hidden-decision risk;
-- dependency direction;
-- failure honesty and recovery;
-- contract stability;
-- test surface;
-- reversibility;
-- maturity fit;
-- implementation and evidence cost.
-
-Prefer the boundary that removes concepts and coordination, not one that centralizes the same protocol behind additional terminology.
-
-## 7. Learn Before Freezing
-
-When evidence cannot distinguish viable boundaries, define one bounded learning slice:
-
-```text
-Question:
-Competing boundaries:
-Smallest prototype or observation:
-Evidence required:
-Time or cost boundary:
-Discard-or-promote rule:
-Return condition:
-```
-
-The learning slice answers the design question. It does not quietly implement the whole subsystem.
-
-## 8. Return The Supported Boundary
-
-Return the selected boundary with its structural evidence, hidden decision, caller-owned contract, failure behavior, the discriminating reason when alternatives were real, unresolved user-owned decisions, and the narrowest next route. Stop once a boundary is supported or a bounded learning question is identified.

package/skills/design-for-depth/references/module-and-dependency-design.md

@@ -1,117 +0,0 @@
-# Module And Dependency Design
-
-Read this when module decomposition, cohesion, dependency direction, cycles, layering, policy-versus-infrastructure ownership, or change propagation materially affects the design.
-
-This reference is judgment. Do not use it merely because the codebase has many files or dependencies.
-
-## Decompose Around Coherent Decisions
-
-A module should own one coherent outcome, policy, state boundary, or failure unit.
-
-Do not split only by:
-
-- processing step;
-- technical file type;
-- framework convention;
-- arbitrary size;
-- desire for more abstractions.
-
-Ask:
-
-- Which behavior changes together?
-- Which decision has one reason to change?
-- Which state and failure behavior belong together?
-- What should callers stop coordinating?
-
-## Prefer Cohesion Over Convenience
-
-High cohesion means related behavior, invariants, state, and failure handling live together.
-
-Pressure exists when:
-
-- one module owns unrelated policies;
-- one policy is spread across many modules;
-- state transitions are separated from their invariants;
-- failure handling is detached from the operation it protects;
-- callers assemble the real behavior from helpers.
-
-Do not centralize unrelated behavior merely to reduce duplication.
-
-## Direct Dependencies Toward Stable Policy
-
-Policy should not depend directly on volatile infrastructure details when those details can change independently.
-
-Prefer:
-
-```text
-stable outcome or policy
--> small dependency interface
--> infrastructure adapter
-```
-
-Use dependency inversion only when it hides real variation, provider mechanics, migration, or testing control.
-
-Do not add interfaces around every concrete implementation.
-
-## Detect Dependency Cycles
-
-A dependency cycle often indicates:
-
-- responsibilities are divided incorrectly;
-- shared policy has no owner;
-- state is jointly owned;
-- interfaces expose implementation details;
-- modules must know each other’s lifecycle.
-
-Do not break a cycle by moving imports or creating a neutral-looking utility while preserving the same conceptual cycle.
-
-Name the shared decision and assign ownership.
-
-## Preserve Honest Layering
-
-A layer is useful when it hides a distinct level of decision.
-
-A layer is shallow when it:
-
-- forwards calls;
-- renames types;
-- exposes lower-layer errors and states;
-- requires callers to understand both layers;
-- exists only to satisfy a pattern.
-
-Allow a higher-level module to request outcomes. Keep infrastructure details below the boundary.
-
-## Use Ports And Adapters Proportionately
-
-A port is an outcome or capability required by policy. An adapter supplies concrete infrastructure.
-
-Use when:
-
-- provider variation exists;
-- migration is known;
-- infrastructure details leak into policy;
-- tests require safe dependency control.
-
-Avoid when:
-
-- one stable implementation exists;
-- the wrapper hides no decision;
-- the generic interface preserves provider quirks;
-- caller complexity does not decrease.
-
-## Keep Shared Code From Becoming Shared Ownership
-
-A shared helper may centralize syntax while leaving policy ownership scattered.
-
-Before extracting shared code, ask:
-
-- Is this one concept that should evolve together?
-- Who owns its behavior and failure contract?
-- Are callers still making the same decision independently?
-- Does extraction remove coordination or merely relocate code?
-
-Some duplication is cheaper than a shared abstraction with unclear ownership.
-
-## Return
-
-Test module shape through its contract, as Design for Depth's Check Through The Intended Interface describes; do not make production architecture imitate the test framework. Return the affected responsibilities, policy/state/failure ownership, dependency direction, any cycle or layering pressure, and the proposed boundary with the variation or migration that justifies its seams. Stop when dependencies support the outcome without unnecessary coordination; do not reorganize the codebase for conceptual purity.