@hassangameryt/freeflow 0.2.0 → 0.4.0

package/skills/design-for-depth/references/software-design-philosophy.md

@@ -0,0 +1,248 @@
+# Software Design Philosophy
+
+Use this reference when `design-for-depth` needs deeper reasoning than the active skill can carry.
+
+This is not a checklist to run every time. Pull the idea that changes the next route.
+
+## Core Claim
+
+Good design reduces coordination.
+
+A deep module lets callers, tests, reviewers, and future agents use a small interface to get a lot of behavior. A shallow module makes them learn almost as much as the implementation.
+
+Design work is worthwhile when it hides a decision that would otherwise spread.
+
+## Ousterhout: Complexity, Deep Modules, Strategic Programming
+
+### Complexity
+
+Complexity shows up as:
+
+- too many dependencies;
+- obscurity, where important facts are hard to find;
+- change amplification, where a small behavior change touches many places;
+- cognitive load, where the user of a module must remember too much;
+- unknown unknowns, where a future agent cannot tell what it must inspect.
+
+For Freeflow, complexity is not “many lines.” A single compact helper can be complex if callers must know its quirks. A large implementation can be simple to use if the interface hides the hard parts.
+
+### Deep modules
+
+A deep module has a simple interface and useful behavior behind it.
+
+Deep means:
+
+- callers say what outcome they need;
+- implementation owns sequencing and policy details;
+- tests can verify behavior through the public interface;
+- future changes stay localized;
+- docs and review comments do not need to explain the hidden machinery every time.
+
+Shallow means:
+
+- the interface mirrors the implementation;
+- callers pass many flags and know ordering rules;
+- tests assert internal call sequences;
+- wrappers rename work without hiding decisions;
+- future agents still need to inspect everything to use it safely.
+
+### Strategic vs tactical programming
+
+Tactical programming makes the current patch fit, even if it spreads complexity.
+
+Strategic programming spends a little extra attention to preserve future locality.
+
+Freeflow translation:
+
+- Do not redesign everything up front.
+- Do stop when the local patch clearly makes the next slice, review, or bug fix harder.
+- Return the structural evidence to [Workflow](../../workflow/SKILL.md) when a tactical patch is becoming structural work.
+
+## Parnas: Information Hiding
+
+Parnas's key design move: modules should hide design decisions likely to change.
+
+Do not decompose only by processing steps:
+
+```text
+parse -> validate -> send -> log
+```
+
+when the real likely-changing decision is:
+
+```text
+notification delivery policy: provider choice, retry, fallback, telemetry, failure semantics
+```
+
+A good module hides the unstable decision.
+
+For consequential systems, failure behavior is often the unstable decision. Hide the contract in the module before callers invent their own retries, fallbacks, state writes, escalation paths, or graceful-failure claims.
+
+Ask:
+
+- What decision would cause the most edits if it changed?
+- What can fail, who observes it, what state is written, and what must not happen?
+- Does the system fail closed, fail open, degrade, escalate, retry, or stop?
+- What recovery path and evidence prove graceful handling?
+- Which callers currently know that decision?
+- Can one module own it?
+- What interface would let callers stop knowing it?
+
+Examples:
+
+- Billing grace period policy should not be spread across webhook handlers, email copy, UI guards, and tests.
+- Notification retry/fallback policy should not be duplicated in each route.
+- Permission semantics should not be separately encoded in frontend, backend, and test setup.
+- Cache invalidation rules should not require every caller to remember freshness knobs.
+
+## Feathers: Seams And Enabling Points
+
+A seam is where behavior can change without editing the surrounding work.
+
+A seam needs an enabling point: the place where a different adapter, test double, probe, or behavior can be supplied.
+
+Freeflow use:
+
+- Use seams to make hard-to-test or hard-to-change behavior tractable.
+- Do not create seams merely because a pattern sounds clean.
+- Prefer seams that match real variation or observability needs.
+
+Questions:
+
+- What behavior needs to vary?
+- Where can that variation enter without editing callers?
+- What enabling point supplies the adapter or behavior?
+- Does the seam protect production code and tests, or only add indirection?
+
+Good seam candidates:
+
+- provider variation: email/SMS/payment/search/storage;
+- environment variation: prod/test/offline/fake implementations;
+- observability variation: probes, clocks, log sinks, metrics;
+- migration variation: old and new implementations behind one interface.
+
+Weak seam candidates:
+
+- one implementation with no likely variation;
+- a seam created only to mock internals while the real interface stays awkward;
+- a factory/registry around every function;
+- an adapter whose interface still exposes provider-specific quirks.
+
+## Ports And Adapters
+
+Ports/adapters protects core behavior from infrastructure details.
+
+Freeflow wording:
+
+- The core owns policy.
+- The adapter owns provider mechanics.
+- The interface between them says what the core needs or provides.
+
+Use this idea when infrastructure details are leaking into product logic.
+
+Examples:
+
+- Stripe event parsing is adapter work; billing policy is core work.
+- Email provider retries are adapter work; user notification policy may be core work.
+- Database query syntax is adapter work; permission semantics are core work.
+- Browser event plumbing is adapter work; user-flow state is core work.
+
+Do not over-apply ports/adapters:
+
+- simple scripts may not need ports;
+- a single stable library call may not need an adapter;
+- wrapping an SDK without hiding policy or provider quirks is often shallow.
+
+## Public Contract Cost
+
+Hyrum's Law applies beyond public HTTP APIs: every observable flag, path, state, ordering rule, filename, error, timing behavior, and fallback can become depended upon.
+
+Expose a fact only when the caller owns it or correct use requires it. Internal protocols may remain detailed and independently tested without becoming public seams.
+
+A useful split:
+
+- **Public:** caller-owned outcome, decisions, stable invariants, and observable failure semantics.
+- **Internal:** storage layout, provider mechanics, retries, cleanup, integrity publication, temporary states, and optimization machinery.
+
+Public flexibility has permanent coordination cost. One outcome-level operation is often deeper than a toolkit that lets callers reconstruct the module's lifecycle.
+
+## Maturity And Learning
+
+Classify mechanisms before adding them:
+
+- required trust and safety cannot be deferred merely to simplify the design;
+- efficiency, scale, and portability require accepted requirements or observed pressure.
+
+When the best interface cannot be known from source inspection, use a bounded learning slice. Name the question, competing designs, evidence, cost boundary, and discard-or-promote rule. Code can answer a design question without becoming the production design automatically.
+
+## Refactoring Pressure
+
+Design pressure often appears as ordinary implementation pain:
+
+- shotgun surgery;
+- repeated review findings;
+- flaky tests around ordering;
+- many mocks for one behavior;
+- hard-to-explain correctness;
+- one bug fix causing another;
+- “just add this flag everywhere.”
+
+Do not treat all pressure as a command to refactor.
+
+Classify it:
+
+- **Real design pressure:** complexity spread blocks safe progress.
+- **Local mess:** cleanup can happen within current scope.
+- **Deferred deepening:** record the candidate, finish current work.
+- **Owner decision:** deeper change affects product/API/security/compatibility.
+
+## Applying The Philosophy In Freeflow
+
+### In discussion
+
+Use design ideas to ask better questions, not to freeze architecture.
+
+Good questions:
+
+- Which decision is most likely to change?
+- Who should know this rule?
+- What should callers stop coordinating?
+- What future variation is real, not imagined?
+- Which tests should survive a provider or implementation change?
+
+### In specs
+
+Specs name behavior and boundaries. They should not lock in unproven module shapes.
+
+Use:
+
+```text
+Tentative: notification delivery may need one policy-owning module if retries/fallbacks continue spreading.
+Open: whether provider variation is real now or deferred.
+```
+
+not:
+
+```text
+Requirement: implement NotificationDeliveryPortFactoryStrategy.
+```
+
+### In plans
+
+Use [Write Plan](../../write-plan/SKILL.md) only when the ordered strategy can be stated without guessing. When later direction remains provisional, keep it in [Track Work](../../track-work/SKILL.md) or return the evidence to [Workflow](../../workflow/SKILL.md) rather than freezing it as a Plan.
+
+For consequential systems, make failure behavior explicit before implementation choices harden. Do not leave it as an implementer guess after planning only the happy path.
+
+A good slice can be verified through the intended interface. If the slice requires broad caller choreography, revise the slice.
+
+### In review
+
+Review design depth by asking whether the diff reduces or increases caller knowledge.
+
+A diff can pass tests and still fail design review if it scatters policy or creates a shallow interface.
+
+### In diagnosis
+
+Repeated failures may indicate that the system is missing a module, seam, or source-truth decision.
+
+Do not keep fixing symptoms when every fix reveals another coordination problem.

package/skills/diagnose-failure/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: diagnose-failure
+description: Use when a bug, failure, regression, performance problem, or repeated unsuccessful fix lacks a supported cause.
+---
+
+# Diagnose Failure
+
+Establish what is failing and why before selecting a correction.
+
+A **diagnostic loop** is a repeatable check or observation that can reproduce, support, or contradict the failure claim or current hypothesis at the boundary where it matters. A **supported cause** is a causal explanation strong enough to distinguish meaningful alternatives and choose the next action; it does not require impossible certainty.
+
+A requested patch, plausible code path, reviewer theory, or one favorable rerun is not a supported cause.
+
+## Follow The Diagnostic Route
+
+```text
+[Failure without a supported cause]
+-> [Establish expected and observed behavior]
+-> [Choose the smallest diagnostic loop]
+-> [Reproduce or capture the failure]
+-> [State a falsifiable hypothesis]
+-> [Run one distinguishing observation]
+-> [Route from evidence]
+   -> hypothesis contradicted -> refine or replace it -> observe again
+   -> evidence unavailable -> stop with the smallest missing evidence
+   -> cause supported -> return cause and correction boundary to Workflow
+   -> user-owned behavior or source conflict -> Decision Gate
+   -> structural cause -> Design for Depth
+   -> active harm before cause -> propose bounded containment
+```
+
+Diagnosis may recur inside one Track Work slice. A new hypothesis, observation, or owning-skill route does not create a new slice by itself.
+
+## Enter Diagnosis Deliberately
+
+Use this method for unexplained bugs, failed tests, regressions, flaky behavior, performance problems, unexpected runtime behavior, or related corrections that keep failing.
+
+Use it for repeated workflow trouble only when evidence suggests an unclear shared cause: related findings keep appearing, verification contradicts successive corrections, edge-case patches expose more states, or coordination spreads through shared ownership. Reaching a review cap alone is not diagnostic evidence.
+
+If fresh direct evidence already establishes one clear local defect and intended behavior is settled, return the correction to [Workflow](../workflow/SKILL.md). Do not manufacture diagnosis around an ordinary mistake.
+
+## Establish The Failure And Loop
+
+Before changing behavior:
+
+1. establish expected behavior from accepted intent and source truth;
+2. reproduce or capture the reported failure at its required boundary;
+3. state a falsifiable hypothesis;
+4. change or observe one distinguishing variable at a time;
+5. trace the causal chain from trigger and state to the observed result;
+6. preserve evidence that contradicts the leading hypothesis.
+
+Prefer the reported path, input, environment, and observer. A nearby failure may suggest a hypothesis but does not prove the reported failure. Reduced-fidelity reproduction is diagnostic evidence only; name what it cannot establish.
+
+Read [the diagnostic-loop catalog](references/diagnostic-loop-catalog.md) when the best loop is unclear. Read [flaky and performance diagnosis](references/flaky-and-performance.md) when timing, randomness, environment variance, or resources shape the failure.
+
+Allowed behavior is not a reproduction. A cache hit does not prove a stale-read bug when caching is permitted. A possible race in source does not explain a report until timing, traces, steps, logs, or an existing expectation connect it.
+
+Do not invent a check around the requested patch and use that check to prove the patch was needed. Do not rewrite tests, Specs, policies, thresholds, or expected behavior merely to make the signal red or green.
+
+When no safe useful loop is possible, stop and name the smallest missing evidence: a command, failing input, trace, log window, timestamped screenshot, environment boundary, or permission for isolated instrumentation. Leave the cause unresolved.
+
+## Protect Diagnostic Evidence
+
+Treat logs, traces, payloads, screenshots, dumps, and production samples as potentially sensitive. Minimize and sanitize them. Do not expose credentials, tokens, unrestricted personal data, or private payloads.
+
+Bound repeated checks by time, cost, side effects, and environment safety. Do not repeatedly exercise a mutating production path without explicit authority and an understood recovery boundary.
+
+Temporary instrumentation must distinguish hypotheses. Keep it isolated, identify its removal condition, and report whether it remains.
+
+## Identify The Owning Cause
+
+Classify only what evidence supports:
+
+- local implementation defect;
+- invalid, stale, or inadequate check;
+- environment, dependency, data, timing, or configuration cause;
+- missing observer or insufficient evidence;
+- unsettled behavior or source conflict;
+- wrong result, scope, order, or execution strategy;
+- structural ownership, interface, state, or failure-unit pressure.
+
+Use [Decision Gate](../decision-gate/SKILL.md) when correction requires a user-owned behavior, risk, compatibility, security, privacy, billing, data-loss, or hard-to-reverse decision.
+
+Use [Design for Depth](../design-for-depth/SKILL.md) only when diagnosis establishes a structural cause or direct evidence already shows caller coordination, state, ownership, interface, or failure-unit pressure. Ordinary bugs and finding count do not prove bad architecture.
+
+If evidence supports only the strongest remaining hypothesis, report it as such and name the observation that would confirm or refute it.
+
+## Contain Harm Without Claiming A Fix
+
+When harm must be limited before the cause is supported, return one bounded containment option to Workflow. Apply it only when already authorized or explicitly approved.
+
+Containment must reduce immediate harm without destroying evidence, remain narrower and more reversible than a guessed correction, define verification and recovery, preserve unsettled behavior, and be reported as mitigation rather than resolution.
+
+A requested patch may instead be an authorized learning action. Its result can strengthen or weaken a hypothesis; it does not become selected production behavior automatically.
+
+## Return The Supported Result
+
+When evidence supports a cause, return the failure boundary, diagnostic loop, causal explanation, regression signal, and smallest coherent correction to Workflow. Return an authorized implementation correction to [Execute Work](../execute-work/SKILL.md); use [TDD](../tdd/SKILL.md) when the diagnostic loop provides a failing behavior check that should guide it. Use [Simplify Code](../simplify-code/SKILL.md) when the supported cause shows that obsolete, duplicated, or workaround machinery can be removed while preserving accepted behavior. Mess left by unsuccessful attempts is not enough: settle any behavior or contract change through Workflow first, and do not use cleanup in place of correcting the supported failure or while its evidence remains unresolved. The correction may remain in the current Track Work slice while that slice still has one coherent result.
+
+After correction, use [Verify Work](../verify-work/SKILL.md) to rerun both the minimized regression signal and the original reported path or strongest available observer. If correction fails or exposes related shared-state consequences, re-enter diagnosis before another patch.
+
+Do not claim fixed when only containment succeeded, a minimized check passed, or the original boundary remains unavailable.
+
+Report the failure claim, required boundary, diagnostic loop and observations, supported cause or strongest remaining hypothesis, active containment or instrumentation, recommended route, verification status, and missing evidence.

package/skills/diagnose-failure/references/diagnostic-loop-catalog.md

@@ -0,0 +1,36 @@
+# Diagnostic Loop Catalog
+
+Read this when the smallest useful diagnostic loop for a reported failure or current hypothesis is unclear.
+
+## Common Loops
+
+- **Failing test:** use when an existing stable interface or test boundary reaches the reported behavior.
+- **Reproduction command:** one CLI, package task, or script with representative fixture input.
+- **HTTP or protocol script:** the smallest real request sequence that crosses the affected boundary.
+- **Browser path:** the user flow with relevant DOM, console, network, and visual observations.
+- **Captured trace:** a sanitized log window, HAR, event payload, seed, timestamped screenshot, dump, or production sample replayed safely.
+- **Throwaway harness:** a minimal script around the real module when no test framework reaches it.
+- **Differential loop:** the same input through old and new code, configuration, dataset, dependency, or environment.
+- **Instrumented run:** targeted probes at boundaries that distinguish competing hypotheses.
+
+## Improve The Loop
+
+Prefer a loop that is:
+
+- **Sharper:** observes the reported symptom or hypothesis rather than generic failure.
+- **More representative:** preserves the relevant input, state, environment, and observing boundary.
+- **More distinguishing:** can support one plausible cause while contradicting another.
+- **More deterministic:** pins time, randomness, dependencies, filesystem, or network only when doing so preserves the failure.
+- **Faster:** removes unrelated setup without narrowing the claim.
+- **Safer:** isolates mutation, sanitizes sensitive evidence, and has bounded cleanup or recovery.
+
+An observer must sit on the real path and cover the complete operation. A manual counter beside the path, a helper call, or a nearby mocked flow does not prove the reported boundary ran.
+
+## Boundary Examples
+
+- A UI save remains pending → exercise the browser path and inspect the request, console, and rendered state; a reducer unit test does not prove the reported boundary.
+- A registered callback allegedly never runs → invoke or observe the registered entrypoint; calling its helper directly proves only helper behavior.
+- A failure appears only in CI → compare the same input across local and CI configuration before changing timing or adding retries.
+- Two causes fit one symptom → choose an observation whose outcomes differ between them; another generic failure is not distinguishing evidence.
+
+If no safe useful loop is possible, identify the smallest missing artifact or access: command, logs, trace, failing input, timestamped screenshot, environment boundary, or permission for isolated temporary instrumentation. Leave the cause unresolved rather than substituting a weaker claim.

package/skills/diagnose-failure/references/flaky-and-performance.md

@@ -0,0 +1,43 @@
+# Flaky And Performance Diagnosis
+
+Read this when timing, randomness, environment variance, or resource behavior makes the failure difficult to reproduce or explain.
+
+## Flaky Failures
+
+The goal is not one lucky rerun. Raise the reproduction rate or capture the distinguishing event until the failure can be explained.
+
+Use, when safe and representative:
+
+- bounded repetition of the exact failing path;
+- captured seeds, time, timezone, locale, viewport, browser, runtime, and dependency versions;
+- controlled scheduling, fake clocks, CPU pressure, network delay, or concurrency;
+- console, network, event-order, scheduler, screenshot, or video traces;
+- old-versus-new, local-versus-CI, or headed-versus-headless differential runs.
+
+Choose the repetition count from runtime, cost, side effects, and the failure rate. Preserve every unfavorable result. Do not loop mutating production behavior merely to improve reproduction.
+
+Do not stabilize a flake with arbitrary sleeps, retries, wider timeouts, swallowed errors, or disabled checks unless evidence shows that mechanism addresses the causal timing or availability contract. Suppressing observation is not correction.
+
+## Performance Problems
+
+Measure the reported path before optimizing it.
+
+Useful causal evidence includes:
+
+- baseline timing or resource use for the representative workload;
+- slow input, dataset, concurrency, cache, and dependency state;
+- profiler, flamegraph, query plan, allocation profile, or browser trace;
+- old-versus-new comparison under matched conditions;
+- a benchmark that exercises the dominant work identified by evidence.
+
+A microbenchmark can test a hypothesis but does not explain the reported slowdown unless the isolated operation materially determines the real path. Repeated calls with one object justify memoization only when the reported workload repeats that object and measurement shows the repeated work dominates.
+
+Sanitize production traces and payloads. When safe production evidence is unavailable, use representative non-production evidence and downgrade the claim.
+
+## Boundary Examples
+
+- Twenty green reruns after widening a timeout → the failure was suppressed or became rarer; its cause is still unresolved.
+- A parser microbenchmark improves while the representative trace is dominated by database waiting → the benchmark does not explain the reported slowdown.
+- Median latency improves while tail latency or memory crosses the accepted boundary → the performance claim remains contradicted or incomplete.
+
+After an authorized correction, verify that the representative baseline improves and required behavior remains correct. Report variance and relevant resource tradeoffs rather than one favorable run.

package/skills/discuss/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: discuss
+description: Use when discussing, exploring, shaping, challenging, or revisiting an idea, request, artifact, design, or implementation direction, or when an open-ended request or new evidence makes the next approach uncertain.
+---
+
+# Discuss
+
+Build enough shared understanding to choose the next sound action.
+
+Discussion may shape understanding, recommendations, proposed work, and checkpoints. It does not authorize mutation, settle a user-owned choice implicitly, or turn exploratory output into production behavior.
+
+## Follow The Discussion Route
+
+Use this as a directed map, not a checklist:
+
+```text
+[Entry or re-entry]
+-> [Orient from accepted context and live evidence]
+-> [Focus the highest uncertainty that could change the route]
+-> [Inspect facts / ask / compare meaningful paths]
+-> [Route from what is now supported]
+   -> enough understanding
+      -> task-shaped and continuity may matter
+         -> Track Work decides whether to recommend a Working Record
+      -> otherwise -> return direction to Workflow
+   -> one user-owned choice or source conflict -> Decision Gate
+   -> evidence needed -> propose a bounded learning action
+                         -> when authorized -> Track Work
+                            -> Execute Work or wait from its result
+                         -> re-enter Discuss with evidence
+   -> unexplained or repeated failure -> Diagnose Failure
+   -> stable accepted content or strategy -> Write Spec / Write Plan
+```
+
+Preserve decisions, evidence, artifacts, and work that still hold whenever discussion re-enters from implementation, verification, review, failure, or another conversation.
+
+## Enter Or Exit Cleanly
+
+Use Discuss when:
+
+- the user is exploring what to build or how to approach it;
+- important outcomes, boundaries, alternatives, or tradeoffs remain open;
+- an artifact, design, implementation direction, or earlier assumption needs reconsideration;
+- new evidence makes the next approach uncertain.
+
+Do not force discussion for a direct factual question or clear bounded action whose intended result is understood. Feedback alone does not require discussion. Re-enter only when it reopens assumptions, options, or direction.
+
+When one known choice or source conflict blocks progress, use [Decision Gate](../decision-gate/SKILL.md). When a failure lacks a supported cause or keeps recurring, use [Diagnose Failure](../diagnose-failure/SKILL.md) before treating it as a design problem.
+
+## Orient Without Restarting
+
+Identify only what the next decision needs:
+
+- goal and current direction;
+- settled facts and explicit decisions;
+- tentative assumptions or viable alternatives;
+- evidence and uncertainty that could change the route.
+
+When a Working Record exists, orient from its current context and check important claims against live evidence. Read older history only when the present direction or rationale is unclear. Update only what new evidence affects.
+
+## Focus The Discussion
+
+Stay with the highest unresolved question that could change the outcome, boundary, approach, or acceptance. Leave dependent details until that question is sufficiently understood.
+
+Inspect code, tests, docs, policies, artifacts, repository state, supplied material, or current primary sources when they can answer factual questions. Ask the user about intent, priorities, constraints, and tradeoffs that evidence cannot decide.
+
+When materially different paths remain viable:
+
+1. compare only the few that matter, including the current path or waiting when real;
+2. state what each optimizes, its main assumptions and tradeoffs, and evidence that could rule it out;
+3. recommend a direction when evidence supports one and say what could change that recommendation;
+4. leave user-owned choices with the user and do not keep arguing for a rejected path without new evidence.
+
+Ask in natural prose, usually about one main topic at a time. Use a menu only for genuinely closed choices. Do not manufacture alternatives for an obvious local decision.
+
+When architecture, interfaces, ownership, state, failure contracts, or spreading complexity shape the direction, use [Design for Depth](../design-for-depth/SKILL.md) as a lens and retain it while the boundary remains design-bearing.
+
+## Learn Through Bounded Action
+
+When discussion alone cannot answer a material question, propose the smallest useful learning or delivery action:
+
+```text
+Type: Learning | Delivery | Deepening
+Question or outcome:
+Smallest bounded action:
+Expected evidence:
+Useful checkpoint, if any:
+Stop, discard, revise, or promote when:
+```
+
+A proposal is not authorization. Before execution, confirm that the action is requested or approved. When the action is authorized, use [Track Work](../track-work/SKILL.md) to decide whether durable task memory is needed, then follow its result to [Execute Work](../execute-work/SKILL.md) or wait.
+
+Return with the observed result. Treat prototypes, tests, benchmarks, sketches, and working behavior as evidence, not automatic approval of their design or promotion. Preserve what still holds and re-enter only the affected question.
+
+## Preserve Only Useful State
+
+Keep discussion legible as:
+
+- **Settled:** supported fact or explicit decision.
+- **Tentative:** current hypothesis or provisional direction.
+- **Open:** unresolved and capable of changing the next action.
+
+Keep this state in conversation while context is sufficient. Use Track Work when evolving context must survive compaction, pause, or another session. Use [Write Spec](../write-spec/SKILL.md) for stable accepted content and [Write Plan](../write-plan/SKILL.md) for a stable ordered strategy. Do not create an artifact merely because discussion occurred.
+
+Recommend independent review, local commit, user decision, or continuity checkpoints only when they protect dependent work or reduce material risk. Discussion may shape and preserve an approved checkpoint, but does not execute it. Normal verification and silent self-review provide the ordinary self-check; Workflow establishes the slice outcome.
+
+Read [discussion checkpoints](references/checkpoints.md) when selecting or preserving a compact discussion checkpoint or re-entry state.
+
+## Return Supported Direction
+
+Converge when the next sound action no longer depends on unresolved direction, not when every future question is answered.
+
+Return to [Workflow](../workflow/SKILL.md) with:
+
+- current shared understanding;
+- settled and tentative direction;
+- open questions that still change the route;
+- recommended next action or bounded proposal;
+- its authority state and any selected checkpoint.
+
+If no action is needed, answer or stop. If work is proposed but unapproved, recommend the exact action and wait for the user's response.

package/skills/discuss/references/checkpoints.md

@@ -0,0 +1,66 @@
+# Discussion Checkpoints
+
+Read this when closing or preserving a compact discussion checkpoint.
+
+A checkpoint records enough shared understanding to continue or choose the next action. It does not mean discussion is permanently complete.
+
+## Keep It In Chat When Possible
+
+Keep the checkpoint in the conversation when the current context can safely continue. Use only the fields that help:
+
+```text
+Goal or question:
+Current understanding:
+Settled:
+Tentative:
+Open:
+Evidence or alternatives that matter:
+Approved or proposed checkpoints, if any:
+Recommended or accepted next action:
+Authority source or approval needed:
+```
+
+Do not turn a checkpoint into a transcript, questionnaire, frozen architecture, automatic spec, or complete plan.
+
+## Preserve Selected Checkpoints
+
+When discussion proposes or approves an execution checkpoint, preserve only what later action needs:
+
+```text
+Status: Proposed | Approved
+Type:
+Purpose:
+Due boundary:
+Conditions:
+Approval scope:
+```
+
+Do not infer authorization from a recommendation. Keep local commit approval separate from push or integration, and keep migration, deprecation, release, and launch separately controlled.
+
+## Preserve It When Needed
+
+Choose the artifact by the information that must survive:
+
+- **Working Record:** evolving task and checkpoint state, slices, decisions, evidence, history, and next action. Read [Track Work](../../track-work/SKILL.md).
+- **Write Spec:** stable accepted content needs a separate durable artifact. Read [Write Spec](../../write-spec/SKILL.md).
+- **Write Plan:** a stable ordered strategy and its selected checkpoints need a separate artifact. Read [Write Plan](../../write-plan/SKILL.md).
+- **ADR:** a surprising, hard-to-reverse repo-level decision needs durable rationale.
+- **Handoff:** one point-in-time continuation state must be transferred to another context or owner.
+- **Domain documentation:** stable terminology or domain meaning belongs in an existing glossary or domain source.
+
+Do not create an artifact merely because discussion occurred. Prefer an existing repository convention; ask before inventing a destination whose authority, durability, or ownership matters.
+
+## Re-Entry Checkpoint
+
+When new evidence reopens discussion, preserve only the affected change:
+
+```text
+New evidence:
+Invalidated assumption:
+Still valid:
+Decision, slice, or artifact affected:
+Question or experiment now needed:
+Authority or decision needed:
+```
+
+Do not restart from zero or rewrite unaffected decisions and work.