@hassangameryt/freeflow 0.7.3 → 0.9.0

package/skills/commit-work/SKILL.md

@@ -1,145 +0,0 @@
----
-name: "commit-work"
-description: "Use when creating an explicitly requested or selected local Git commit, including staging its exact contents, verifying the resulting checkpoint, or performing a separately authorized simple push."
----
-
-# Commit Work
-
-Preserve one supported repository state as a coherent local Git checkpoint.
-
-Commit Work normally follows execution, verification, self-review, and any selected independent review. It preserves that supported state; it does not establish correctness, close the Slice, authorize another Slice, or imply push, integration, release, or launch.
-
-A commit is not mandatory merely because work finished. Enter only when the user explicitly requests a local commit or [Workflow](../workflow/SKILL.md) selects an authorized Local commit checkpoint.
-
-An explicitly requested preservation checkpoint may capture incomplete, failing, or inconclusive work. Describe that state honestly and do not treat the commit as permission to cross the unresolved boundary.
-
-## Enter At The Commit Boundary
-
-Before staging, confirm:
-
-- local commit authority is explicit and still valid;
-- the checkpoint has one coherent claim;
-- the request, accepted decisions, and live changes still describe the same outcome;
-- fresh evidence supports the exact state being preserved, or this is an explicitly requested preservation checkpoint;
-- any selected independent review is complete and its material findings are adjudicated;
-- no unresolved decision, source conflict, or required evidence gap is hidden by the checkpoint claim.
-
-A Working Record may preserve checkpoint selection and authority but cannot create them. Approval to implement does not imply approval to commit.
-
-Commit Work verifies fidelity between the supported state and the Git checkpoint. It does not dispatch missing review, repair implementation, or generate missing behavioral evidence. Return those needs to Workflow.
-
-## Inspect The Candidate State
-
-Inspect before changing the index:
-
-```bash
-git status --short --branch
-git status
-git diff
-git diff --cached
-git ls-files --others --exclude-standard
-```
-
-Inspect submodule state when status reports a changed submodule.
-
-Read [Staging Decisions](references/staging-decisions.md) when:
-
-- staged, unstaged, or untracked changes have mixed ownership or concerns;
-- a path contains both intended and excluded changes;
-- existing staged ownership is uncertain;
-- generated, durable, sensitive, or suspicious files appear;
-- narrowing the checkpoint may require changing existing staged state.
-
-Read [Git State Edges](references/git-state-edges.md) when Git reports an in-progress operation, unmerged paths, detached `HEAD`, submodule ambiguity, or an empty candidate; a requested commit would amend, be empty, or bypass hooks; or any commit or hook fails.
-
-Treat staged state as evidence of index contents, not evidence of ownership, intent, verification, or readiness.
-
-## Build The Exact Checkpoint
-
-Stage only paths or hunks required to make the checkpoint claim true.
-
-Broad staging commands are acceptable only when every changed path has been inspected and belongs to the same checkpoint. Otherwise stage explicit paths or hunks.
-
-Do not silently unstage, rearrange, discard, overwrite, or absorb user-owned work to manufacture a clean commit.
-
-After staging, inspect the exact candidate:
-
-```bash
-git diff --cached
-git diff --cached --check
-```
-
-Confirm:
-
-- every staged path and hunk belongs;
-- required tests, documentation, generated outputs, or metadata are present;
-- no unrelated, sensitive, unexplained, or user-owned content is included;
-- the staged diff is non-empty unless an empty commit was explicitly requested;
-- the commit claim does not exceed available verification and review evidence;
-- excluded working-tree changes do not invalidate evidence for the staged checkpoint.
-
-Interpret `git diff --cached --check` against repository conventions. Unresolved conflict markers or unintended whitespace damage stop the commit; do not edit content merely to silence the command.
-
-If producing the exact checkpoint requires source changes, additional evidence, or a user-owned staging decision, return to Workflow rather than performing that work here.
-
-## Create The Commit
-
-Use the repository's established commit-message style. Otherwise use a short imperative subject describing the actual checkpoint, not the wider task ambition.
-
-Add a body only when the diff does not adequately explain material context, tradeoffs, residual risk, or why incomplete state is being preserved. Reference existing issues, Specs, Plans, or decisions only when they materially explain the checkpoint. Do not invent trailers or metadata conventions.
-
-Create an ordinary local commit from the inspected index.
-
-Do not use `--amend`, `--allow-empty`, or `--no-verify` by implication. Read Git State Edges when one is explicitly requested or becomes relevant.
-
-If a hook fails, changes files or the index, or makes prior evidence stale, do not bypass or blindly retry it. Inspect the resulting state through Git State Edges.
-
-## Verify The Checkpoint
-
-After Git reports a successful commit, inspect:
-
-```bash
-git show --stat --oneline --decorate HEAD
-git show --format= --name-status HEAD
-git status --short --branch
-```
-
-Confirm that:
-
-- the intended commit was created;
-- its subject and contents represent the checkpoint claim;
-- no unexpected staged, unstaged, or untracked state resulted;
-- remaining changes are known and were not silently absorbed.
-
-Report:
-
-- commit SHA and subject;
-- the checkpoint claim and included scope;
-- verification and selected-review evidence;
-- whether the commit is complete or an honest preservation checkpoint;
-- remaining staged, unstaged, untracked, unverified, or unpushed work;
-- any hook, signing, identity, or repository limitation;
-- the route returned to Workflow.
-
-Return the checkpoint result to Workflow. When a Working Record exists, Workflow may route [Track Work](../track-work/SKILL.md) to record `commit:<sha>`, settle the selected checkpoint, and reconcile the Current Slice.
-
-Do not stage leftovers, begin another Slice, push, integrate, release, or clean up merely because the commit succeeded.
-
-## Push Only When Separately Authorized
-
-A local commit does not authorize push.
-
-Before any push, read [Simple Push](references/simple-push.md). Use [Finish Branch](../finish-branch/SKILL.md) instead when the request involves integration, pull-request strategy, branch cleanup, history rewriting, or choosing among branch-closeout routes.
-
-## Stop
-
-Stop and return the smallest blocking fact when:
-
-- commit authority or the checkpoint claim is unclear;
-- live changes no longer match the supported outcome;
-- selected review or required evidence remains unresolved;
-- the exact checkpoint cannot be staged without manipulating ambiguous user-owned state;
-- sensitive or unexplained content may be included;
-- Git is in a non-ordinary state whose intended outcome is unsettled;
-- creating the commit would require implementation changes, evidence generation, hook bypass, amendment, or history rewriting outside explicit authority;
-- push destination, upstream, or remote-history effect is unclear.

package/skills/commit-work/references/git-state-edges.md

@@ -1,94 +0,0 @@
-# Git State Edges
-
-Read this when Git reports an in-progress operation, unmerged paths, detached `HEAD`, submodule ambiguity, or an empty candidate; a requested commit would amend, be empty, or bypass hooks; or any commit or hook fails.
-
-These states can change the meaning or recoverability of a commit. Inspect before choosing a recovery action.
-
-## In-Progress Operations
-
-A commit during merge, rebase, cherry-pick, or revert may complete or advance that operation rather than create an ordinary checkpoint.
-
-Stop and establish:
-
-- which operation is active;
-- whether the current checkpoint is intended to conclude it;
-- whether all conflicts and behavior decisions are settled;
-- which owner should continue the operation;
-- what verification is required on the resulting state.
-
-Do not use Commit Work to finish an operation merely because Git currently permits `commit`.
-
-Unmerged paths always stop an ordinary commit.
-
-## Detached HEAD
-
-A detached-`HEAD` commit may be valid but can become difficult to recover or push.
-
-Before committing, require an explicit preservation route naming how the resulting commit will remain reachable. Use [Finish Branch](../../finish-branch/SKILL.md) when branch creation, integration, or checkout ownership must be decided.
-
-Do not silently create or switch branches.
-
-## Amend And Empty Commits
-
-`git commit --amend` rewrites an existing checkpoint. Use it only when the user explicitly requests amendment and the exact target commit, included changes, authorship effects, and remote-history state are known.
-
-If the target may already be shared or pushed, return to [Workflow](../../workflow/SKILL.md) or Finish Branch before rewriting it.
-
-Use `--allow-empty` only for an explicitly requested empty checkpoint with a named repository purpose. An accidentally empty index is not authorization for an empty commit.
-
-## Hooks
-
-Do not bypass hooks merely because they block the commit.
-
-When a hook fails:
-
-1. preserve its complete result;
-2. inspect `HEAD`, the index, and working tree;
-3. determine whether a commit was created despite the reported failure;
-4. determine whether the hook changed files or staged content;
-5. return implementation, verification, policy, or environment failures to their owning route.
-
-When a hook changes repository content, the previously supported state may no longer be the state being committed. Reinspect the complete diff and obtain affected verification before retrying.
-
-Use `--no-verify` only when the user explicitly requests that exact bypass and repository policy permits it. Report which checks were skipped and which claims therefore remain unsupported.
-
-## Commit Command Failures
-
-After any failed or interrupted commit attempt, inspect:
-
-```bash
-git status
-git diff
-git diff --cached
-git log -1 --oneline --decorate
-```
-
-Do not assume failure means no commit was created or no state changed.
-
-For identity, signing, credential-helper, editor, lock, filesystem, or permission failures:
-
-- do not change global or repository Git configuration without authority;
-- do not delete lock files while process ownership is unclear;
-- do not retry through a materially different command without a supported cause;
-- report the exact blocker and preserved state.
-
-Use [Diagnose Failure](../../diagnose-failure/SKILL.md) when the cause remains unclear or a retry repeats the failure.
-
-## Submodules
-
-A parent commit records a submodule pointer, not the submodule's uncommitted contents.
-
-Inspect:
-
-- the recorded pointer change;
-- whether the nested worktree is dirty;
-- whether the intended checkpoint includes the pointer update;
-- whether nested changes have their own preservation route.
-
-Do not claim nested changes are preserved by committing only the parent repository.
-
-## Return Safely
-
-Return to Commit Work only when the repository has one supported, recoverable checkpoint candidate.
-
-Otherwise preserve the exact Git state and return to Workflow, Finish Branch, Diagnose Failure, or the producing activity whose responsibility changed.

package/skills/commit-work/references/simple-push.md

@@ -1,92 +0,0 @@
-# Simple Push
-
-Read this before performing any push through Commit Work.
-
-A **simple push** sends inspected local commits from the current named branch to one explicit or established remote branch without force, deletion, tag publication, integration, pull-request creation, release, or deployment.
-
-Use [Finish Branch](../../finish-branch/SKILL.md) when the route requires choosing how to integrate, share, preserve, rewrite, or clean up branch state.
-
-## Confirm Push Authority
-
-Push requires authority separate from local commit.
-
-Confirm:
-
-- which commits are intended;
-- the local branch;
-- the destination remote and branch;
-- whether setting a new upstream is included;
-- that no force, deletion, tag, or history rewrite is implied.
-
-Do not infer a remote, destination branch, pull-request target, or shared-branch policy when the wrong choice could affect collaborators.
-
-## Inspect The Route
-
-Inspect:
-
-```bash
-git branch --show-current
-git status --short --branch
-git branch -vv
-git remote -v
-git log -1 --oneline --decorate
-```
-
-When an upstream exists, inspect:
-
-```bash
-git rev-parse --abbrev-ref --symbolic-full-name @{upstream}
-git rev-list --left-right --count @{upstream}...HEAD
-```
-
-Ahead/behind state is only as fresh as the local remote-tracking reference. Do not claim current remote state unless it was freshly observed.
-
-Stop before pushing when:
-
-- `HEAD` is detached;
-- destination or upstream is unclear;
-- unexpected commits or dirty state change the route;
-- protected or shared-branch policy disallows the push or leaves its route unclear;
-- local and observed upstream history diverge;
-- the push would require force, deletion, tag publication, or another separately controlled action.
-
-## Push The Exact Branch
-
-Use the established upstream when it clearly matches the approved route.
-
-When no upstream exists, set one only when the remote and branch destination are explicit and the configuration change is included in the accepted route.
-
-Do not push additional branches or tags.
-
-A force push is not a simple push. Return an explicitly requested history rewrite to Workflow or Finish Branch.
-
-## Handle Rejection Without Escalation
-
-If the push is rejected or fails:
-
-- preserve the complete result;
-- do not automatically pull, merge, rebase, force, change remotes, or change destination;
-- inspect whether any remote update occurred;
-- return authentication, divergence, policy, or destination decisions to [Workflow](../../workflow/SKILL.md) or Finish Branch.
-
-A failed push does not invalidate the local commit.
-
-## Verify And Report
-
-After a successful push, inspect:
-
-```bash
-git status --short --branch
-git branch -vv
-```
-
-Report:
-
-- pushed commit range;
-- remote and destination branch;
-- whether an upstream was created or changed;
-- command result and strongest observed remote-state evidence;
-- remaining unpushed commits or dirty state;
-- CI, review, integration, release, or deployment work not established by the push.
-
-A successful push proves transfer to the observed destination. It does not prove pull-request creation, merge, release, deployment, or remote CI success.

package/skills/commit-work/references/staging-decisions.md

@@ -1,106 +0,0 @@
-# Staging Decisions
-
-Read this when staged, unstaged, or untracked changes have mixed ownership or concerns; a path contains both included and excluded work; existing staged ownership is uncertain; generated, durable, sensitive, or suspicious files appear; or narrowing may require changing existing staged state.
-
-This reference determines what may enter the checkpoint. It does not establish commit authority, verification, review readiness, or permission to alter user-owned work.
-
-## Classify The Changed Units
-
-Classify at the path level only when the whole path has one role. Otherwise classify individual hunks.
-
-- **Checkpoint content:** directly implements or proves the checkpoint claim.
-- **Required companion:** tests, documentation, schema, metadata, or generated output required for that same claim.
-- **Related but separable:** useful work that does not need to be preserved in this checkpoint.
-- **Unrelated or user-owned:** work outside the accepted outcome or whose ownership is not established.
-- **Sensitive or unsafe:** secrets, credentials, personal data, environment files, debug output, destructive state, or unexplained artifacts.
-- **Unclear:** content whose purpose, generator, ownership, or evidence relationship is not yet supported.
-
-Only checkpoint content and required companions belong.
-
-A broad request such as "commit everything" may authorize broad inclusion, but it does not remove the obligation to inspect unsafe, unclear, or unexpectedly unrelated content.
-
-## Protect Existing Staged State
-
-Existing staged changes may belong to another workflow.
-
-Inspect them, but do not infer that they are intended merely because they are staged. Do not silently:
-
-- absorb them into the checkpoint;
-- unstage or reset them;
-- amend them into another commit;
-- move them through a stash or temporary commit;
-- replace the index or use index tricks to bypass ownership ambiguity.
-
-When intended and pre-existing staged work cannot be separated without manipulating ambiguous state, present the smallest safe options and ask which checkpoint the user wants.
-
-## Handle Partial Files Carefully
-
-A file may contain both checkpoint and excluded hunks. Stage only the intended hunks when their behavior and evidence remain independently coherent.
-
-Stop when:
-
-- included and excluded hunks depend on each other;
-- partial staging would produce an invalid intermediate state;
-- verification ran against the combined working tree and excluded changes may have affected the result;
-- the staged version differs materially from the state that was reviewed or verified.
-
-Do not claim an isolated staged checkpoint is supported merely because the combined dirty worktree passed.
-
-## Include Generated Files Deliberately
-
-Include generated files, snapshots, lockfiles, formatter output, or build artifacts only when repository convention or the accepted outcome requires them.
-
-Establish:
-
-- which command or generator produced them;
-- whether their changes are expected from the accepted source change;
-- whether they are deterministic enough to review;
-- whether hand edits are prohibited;
-- whether their verification belongs to the checkpoint evidence.
-
-Do not include generated output merely because it changed. Do not hand-edit it unless the repository explicitly expects that workflow.
-
-## Preserve Durable Artifacts Honestly
-
-A Spec, Plan, ADR, policy, public documentation file, or release artifact may have authority and maintenance rules independent of implementation.
-
-Include it only when:
-
-- its change is explicitly covered;
-- it belongs to the same coherent checkpoint;
-- it describes the same accepted behavior;
-- its own maintenance policy permits the update.
-
-Do not edit a durable artifact merely to make implementation appear coherent. Return contradictions to [Workflow](../../workflow/SKILL.md).
-
-Working Records under `.freeflow/tasks/**` are ignored local memory and must never be staged or committed.
-
-## Reject Sensitive Or Suspicious Content
-
-Stop before staging:
-
-- secrets, tokens, credentials, private keys, or local environment files;
-- databases, dumps, recordings, or personal data;
-- unexplained binaries or generated archives;
-- logs, traces, screenshots, or debug output not explicitly required;
-- destructive state or files whose inclusion could expose or lose user data.
-
-Do not "clean up" suspicious files by deleting or discarding them. Preserve their state and report the exact paths.
-
-## Verify The Candidate
-
-After staging, compare all three states:
-
-```bash
-git diff --cached
-git diff
-git status --short --branch
-```
-
-The checkpoint is narrow only when:
-
-- the index contains exactly the intended checkpoint;
-- excluded work remains untouched;
-- remaining dirty state is understood;
-- verification still supports the staged version rather than only the combined worktree;
-- the final report can name everything left behind.

package/skills/decision-gate/SKILL.md

@@ -1,106 +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. It begins only when one blocking choice or source conflict is clear enough to resolve with one direct question.
-
-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.
-
-## Enter With One Decision
-
-Use Decision Gate only 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 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.
-
-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 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 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, 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.
-
-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.
-
-Do not broaden the answer, reinterpret it as approval for a different path, or continue past another separately controlled boundary.
-
-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,117 +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 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.
-
-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.
-
-## 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.
-
-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. 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.
-
-## 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.
-
-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. Apply it before recommending a mechanism during discussion, writing its guiding design, or beginning substantial implementation. Explore alternatives against the current goal and constraints; select a supported mechanism or identify the missing observation or user-owned choice. Leave ordinary mechanics free. The reference helps make those choices explicit and check their realization, not impose a blueprint on every task.
-
-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.
-
-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.
-
-## Bound Success And Failure Proportionately
-
-Before selecting classes, services, packages, flags, or states, name:
-
-- the caller and complete accepted outcome;
-- caller-owned decisions and observable success/failure;
-- the likely-changing coordination the module could hide;
-- the failure unit: what must be treated as one coherent success, failure, and recovery 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.
-
-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.
-
-## Hide Coordination Without Hiding Caller Choices
-
-Prefer operations through which callers request an outcome and the module owns the internal 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 internal unless callers genuinely control it:
-
-- 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.
-
-## 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.
-
-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.
-
-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.
-
-## 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.
-
-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.
-
-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.
-
-## 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.
-
-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.
-
-Test order is not a design criterion. Choose boundaries for the actual caller and supported variation, not to satisfy a formal implementation sequence.
-
-## 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.
-
-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.