@hassangameryt/freeflow 0.5.0 → 0.7.0

package/skills/discuss/SKILL.md

@@ -1,121 +1,175 @@
 ---
 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.
+description: "Use when the user is exploring, challenging, or revisiting what to build or how to proceed, or when assumptions, alternatives, or new evidence leave the next sound action materially 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.
+Discuss owns exploration, alternatives, assumptions, and direction. It may shape recommendations, proposed work, and checkpoints. It does not authorize active evidence generation, mutation, delivery, or a user-owned decision.
 
-## Follow The Discussion Route
+## Enter Or Exit Cleanly
 
-Use this as a directed map, not a checklist:
+Use Discuss when:
 
-```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
-```
+- the outcome, boundary, approach, or acceptance remains materially open;
+- several meaningful paths remain viable;
+- an assumption or earlier direction needs reconsideration;
+- new evidence makes the next route uncertain.
 
-Preserve decisions, evidence, artifacts, and work that still hold whenever discussion re-enters from implementation, verification, review, failure, or another conversation.
+Do not turn every interaction into a discussion phase. If the user asks a direct factual question, provides a clear bounded request, or gives feedback that does not reopen direction, answer or return the request to Workflow.
 
-## Enter Or Exit Cleanly
+When one known user-owned 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).
 
-Use Discuss when:
+## Discuss Like A Collaborator
+
+Respond to the user’s substance before steering the conversation.
+
+Carry your share of the thinking:
+
+- interpret what the current evidence and intent imply;
+- expose consequential assumptions and tradeoffs;
+- challenge claims when evidence or engineering judgment warrants it;
+- recommend a direction when one is better supported;
+- revise your position plainly when new reasoning or evidence changes it.
 
-- 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.
+Ask only questions whose answers could materially change the route and which available evidence cannot answer. Ask the user about intent, priorities, constraints, and tradeoffs they own. Do not make the user answer factual questions that existing sources can resolve.
 
-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.
+Keep one consequential uncertainty in focus. Do not conduct a questionnaire, manufacture alternatives, repeat accepted context, or continue arguing for a rejected path without new evidence.
 
-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.
+## Follow The Discussion Loop
+
+```text
+Orient from what remains true
+-> respond to the current substance
+-> focus the uncertainty that could change the route
+-> inspect facts, ask about intent, or compare meaningful paths
+-> determine what is now supported
+   -> continue discussion
+   -> learn through bounded action
+   -> decide continuity
+   -> route the supported result
+```
+
+Use this as a feedback loop, not a user-facing checklist.
 
 ## Orient Without Restarting
 
 Identify only what the next decision needs:
 
-- goal and current direction;
-- settled facts and explicit decisions;
+- the goal and current direction;
+- supported facts and explicit decisions;
 - tentative assumptions or viable alternatives;
-- evidence and uncertainty that could change the route.
+- open questions capable of changing the route;
+- evidence that still matters.
+
+Keep these distinctions available:
+
+- **Settled:** supported fact or explicit decision.
+- **Tentative:** live hypothesis or provisional direction.
+- **Open:** unresolved and capable of changing the next action.
+
+Use those labels in the response only when they make a transition or summary clearer. Do not turn every discussion turn into a status report.
 
-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.
+When discussion reopens after implementation, feedback, verification, review, or failure, preserve what still holds and revisit only the affected assumption, decision, or direction.
 
-## Focus The Discussion
+When a Working Record exists, read [Track Work](../track-work/SKILL.md) before any record operation. Recover the relevant current state, reconcile it with current user direction and live evidence, and return to the question that actually changed. Memory does not override contradictory evidence or current intent.
 
-Stay with the highest unresolved question that could change the outcome, boundary, approach, or acceptance. Leave dependent details until that question is sufficiently understood.
+## Resolve What Conversation Can Resolve
 
-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.
+Inspect existing code, tests, documentation, policies, artifacts, repository state, supplied material, or current primary sources when they can answer a factual question without exercising target behavior or changing state.
+
+When several observations could answer the same question, or the likely inspection is broad, use [Action Selection](../action-selection/SKILL.md) to choose the smallest discriminating observation.
 
 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.
+1. compare only the paths that could realistically be chosen;
+2. state what each optimizes and what it sacrifices;
+3. identify the assumptions on which each path depends;
+4. recommend the best-supported direction;
+5. state what evidence or changed priority would alter that recommendation.
 
-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, or failure behavior shapes the direction, use [Design for Depth](../design-for-depth/SKILL.md) as a lens.
 
-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.
+Converge when the next sound action no longer depends on unresolved direction. Do not continue discussion merely because more detail could be explored.
 
 ## Learn Through Bounded Action
 
-When discussion alone cannot answer a material question, propose the smallest useful learning or delivery action:
+Do not keep reasoning about an empirical uncertainty when a small, reversible experiment can discriminate between the remaining hypotheses.
+
+Use a Learning action when:
+
+- accepted evidence and passive inspection cannot answer a material question;
+- exercising behavior, building a prototype, testing an assumption, or writing disposable code can answer it;
+- the expected information can change the direction;
+- the action can be bounded by evidence and a stop condition.
+
+Propose:
 
 ```text
-Type: Learning | Delivery | Deepening
-Question or outcome:
-Smallest bounded action:
+Question or hypothesis:
+Smallest discriminating action:
+Reversible effects and production boundary:
 Expected evidence:
-Useful checkpoint, if any:
-Stop, discard, revise, or promote when:
+Stop and return when:
+Discard, revise, or propose promotion 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.
+A learning proposal does not authorize execution. Before returning it to Workflow, decide whether its context needs durable preservation. Workflow confirms authority and routes covered work through [Track Work](../track-work/SKILL.md) when needed and then [Execute Work](../execute-work/SKILL.md).
 
-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.
+Return the result to Discuss. Treat prototypes, tests, benchmarks, sketches, and working behavior as evidence—not automatic approval of their design or promotion into production.
 
-## Preserve Only Useful State
+If the work remains valuable as an accepted outcome regardless of what it teaches, propose a Delivery or Deepening result instead of disguising it as Learning.
 
-Keep discussion legible as:
+## Decide Continuity Before Leaving
 
-- **Settled:** supported fact or explicit decision.
-- **Tentative:** current hypothesis or provisional direction.
-- **Open:** unresolved and capable of changing the next action.
+Before discussion hands off a supported direction, ask:
 
-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.
+> Would losing the current understanding, decisions, evidence, proposals, or next action risk later misalignment?
 
-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.
+If no, keep the state in conversation.
 
-Read [discussion checkpoints](references/checkpoints.md) when selecting or preserving a compact discussion checkpoint or re-entry state.
+If yes, read [Discussion Continuity](references/discussion-continuity.md) before choosing or preserving the durable destination. When a Working Record is appropriate:
 
-## Return Supported Direction
+```text
+Discuss
+-> material supported state
+-> Track Work update
+-> Discuss
+-> Workflow
+```
 
-Converge when the next sound action no longer depends on unresolved direction, not when every future question is answered.
+Discuss decides what the state means and whether it needs continuity. Track Work owns the Working Record and its lifecycle. A record update does not end discussion, authorize work, select a proposal, or change the owning route.
 
-Return to [Workflow](../workflow/SKILL.md) with:
+Do not create a Working Record for a short disposable exchange or one clear direct result merely because discussion occurred. Reconsider the decision if a small task develops durable decisions, several outcomes, repeated feedback, checkpoints, or context-loss risk.
+
+## Shape Checkpoints Sparingly
+
+Recommend a user decision, independent review, local commit, or continuity checkpoint only when crossing that boundary unresolved could materially endanger dependent work.
+
+Discussion may propose a checkpoint. Workflow selects it. Track Work preserves it when durable memory is needed. A recommendation or recorded checkpoint does not authorize the action it describes.
+
+## Return Supported Direction
+
+Return to [Workflow](../workflow/SKILL.md) with the concepts the next route needs:
 
 - 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.
+- continuity decision;
+- authority state and selected checkpoint, when any.
+
+Use natural prose unless structured state materially improves continuity.
+
+Route narrowly:
+
+- one user-owned choice or source conflict -> Decision Gate;
+- unexplained or repeated failure -> Diagnose Failure;
+- stable accepted content -> [Write Spec](../write-spec/SKILL.md);
+- stable ordered strategy -> [Write Plan](../write-plan/SKILL.md);
+- covered bounded work -> Workflow and Execute Work;
+- no action needed -> answer or stop.
 
-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.
+If work is recommended but not authorized, state the exact proposal and wait.

package/skills/discuss/references/discussion-continuity.md

@@ -0,0 +1,123 @@
+# Discussion Continuity
+
+Read this before preserving discussion across context loss, creating or updating durable task memory from discussion, or carrying a proposed or selected checkpoint beyond the current conversational context.
+
+Discussion state is not automatically a Working Record, Spec, Plan, checkpoint, or authority.
+
+## Keep It In Conversation When Possible
+
+Keep state in chat when the current context can safely reach the next decision or action.
+
+Summarize only what helps:
+
+```text
+Goal or question:
+Current understanding:
+Settled:
+Tentative:
+Open:
+Evidence or alternatives that matter:
+Recommended or accepted next action:
+Authority or decision still needed:
+```
+
+Prefer natural prose. Use structured fields only when they prevent ambiguity or support a transition. Never emit empty or irrelevant fields.
+
+Do not preserve a transcript, repeated rationale, rejected alternatives that no longer matter, or every discussion turn.
+
+## Choose Durable Memory By Purpose
+
+Use a durable destination only when losing the state could cause later misalignment:
+
+- **Working Record:** evolving task state, current work, proposed outcomes, decisions, evidence pointers, checkpoints, blockers, and the next useful action.
+- **Spec:** stable accepted behavior, boundaries, or content needs a tracked source.
+- **Plan:** an accepted ordered execution strategy must survive independently.
+- **ADR:** a surprising and hard-to-reverse repository decision needs durable rationale.
+- **Handoff:** a point-in-time continuation package must transfer to another context or owner.
+- **Domain documentation:** stable terminology or domain meaning belongs in an existing repository source.
+
+Do not create an artifact merely because discussion occurred. Prefer an existing repository convention. Ask before inventing a tracked destination whose authority or ownership matters.
+
+## Preserve Through Track Work
+
+Discuss owns exploration and meaning. [Track Work](../../track-work/SKILL.md) owns the Working Record and its lifecycle.
+
+```text
+Discuss
+-> supported state worth preserving
+-> Track Work performs one atomic update
+-> Discuss confirms the preserved meaning
+-> continue discussion or return to Workflow
+```
+
+A Working Record is appropriate when:
+
+- the task must survive compaction, pause, navigation, or transfer;
+- decisions, evidence, blockers, authority, or the next action need reconstruction;
+- one outcome may span implementation, verification, feedback, review, or correction;
+- several proposed outcomes or dependencies must remain ordered without becoming authorized;
+- a selected checkpoint must survive until its boundary is resolved.
+
+Preserve only supported state that could affect later interpretation or action. Give each detailed fact one canonical owner. Track Work should store current meaning rather than append discussion chronology.
+
+When the initial record need arises from discussion, preserve the state that justified the record in the first authorized atomic update. Do not create an empty shell and lose the decisions, proposals, or uncertainty that made continuity necessary.
+
+After preservation, return to Discuss unless Workflow established another route. Record mutation does not transfer ownership or authorize execution.
+
+## Carry Proposed And Selected Checkpoints
+
+A possible checkpoint remains proposed in the current discussion until Workflow selects it.
+
+For a proposed checkpoint, preserve only:
+
+```text
+Status: Proposed
+Type:
+Purpose:
+Boundary it could protect:
+Authority or selection still needed:
+```
+
+For a selected checkpoint, preserve:
+
+```text
+Status: Selected
+Type:
+Purpose:
+Due boundary:
+Condition:
+Selection source:
+Authority scope:
+```
+
+Persist checkpoint state through Track Work only when durable memory is needed. Keep local commit authority separate from push or integration, and keep migration, release, and launch separately controlled.
+
+## Preserve Re-entry State
+
+When evidence, feedback, or failure reopens discussion, preserve only the affected change:
+
+```text
+New evidence:
+Assumption or direction affected:
+What remains valid:
+Decision, proposal, Slice, or artifact affected:
+Question or bounded learning action now needed:
+Authority or user decision needed:
+```
+
+Do not restart from zero, rewrite unaffected decisions, or narrate completed work.
+
+After context loss, recover through Track Work’s prescribed view before relying on the record. Compare recovered memory with current user direction and live evidence. Reconcile only what current evidence changed.
+
+## Stop
+
+Stop preserving when the current meaning and one next useful action can be reconstructed safely.
+
+Do not turn continuity into:
+
+- a transcript;
+- a mandatory artifact;
+- a second source of authority;
+- a frozen architecture;
+- an automatic checkpoint;
+- a reason to begin execution.