@hassangameryt/freeflow 0.7.1 → 0.7.2

package/skills/write-plan/SKILL.md

@@ -1,123 +1,92 @@
 ---
 name: write-plan
-description: Use when writing or revising an implementation plan, execution plan, remediation plan, migration plan, or similar ordered plan.
+description: "Use when writing or revising an implementation plan, execution plan, remediation plan, migration plan, or similar ordered plan."
 ---
 
 # Write Plan
 
-Write an ordered execution strategy that is expected to be followed.
+Write a supported ordered strategy for an agreed outcome. Make its dependencies, actions, checks, and invalidation conditions clear without inventing requirements or pretending unknown later work is settled.
 
-A Plan defines intended phases, slices, dependencies, boundaries, and checks. It is not a Spec, progress report, task history, or rolling record.
+A Plan describes intended execution. The Working Record preserves actual work, evolving state, and the next useful action. Neither creates authority by existing.
 
-## Confirm The Work Is Ready To Plan
+## Plan Only What Is Understood Enough To Order
 
-Write a Plan when:
+Use a durable Plan when the intended outcome and material decisions are settled, the approach and dependencies can be ordered without guessing, and the strategy needs to survive independently.
 
-- the intended outcome and scope are clear;
-- material user decisions and source conflicts are resolved;
-- the execution approach is understood well enough to order;
-- phases, slices, and dependencies can be stated without guessing;
-- expected checks are known or obtainable;
-- substantial branching or discovery is not expected.
+Not every task needs one. A small correction can proceed from its request and supported approach. An evolving route with substantial branching belongs in [Track Work](../track-work/SKILL.md) as provisional Slices, not a confident long-form Plan.
 
-If direction or major alternatives remain unsettled, read [Discuss](../discuss/SKILL.md). If one user-owned choice or source conflict blocks planning, read [Decision Gate](../decision-gate/SKILL.md). If a reported failure lacks a supported cause or diagnostic loop, read [Diagnose Failure](../diagnose-failure/SKILL.md) instead of planning a guessed fix.
+Use [Discuss](../discuss/SKILL.md) for unresolved direction or material alternatives, [Decision Gate](../decision-gate/SKILL.md) for a blocking owner choice or source conflict, and [Diagnose Failure](../diagnose-failure/SKILL.md) for a fix whose cause is unsupported. Do not encode the hoped-for answer as a planning assumption.
 
-Use [Track Work](../track-work/SKILL.md) when strategy is still evolving or actual execution, evidence, deviations, and current state need durable memory.
+If the user asks about a Plan, answer rather than write one. If execution of the task is already authorized and a Plan is useful preparation, writing it need not create another approval stop. Preserve any review or user-return boundary actually selected.
 
-If the user asks about a Plan, answer instead of writing or revising one.
+## Establish The Current Basis
 
-## Plan From Source
+A separate Spec is not required when the request and accepted understanding are sufficiently clear. Otherwise consume the relevant Spec, issue, design, diagnosis, decision, or requirements, together with current code, tests, policies, ADRs, and external constraints where needed.
 
-A Plan may be written directly from sufficiently clear context; a separate Spec is not required.
+Identify which accepted source version or amendment the Plan implements. A Working Record can locate those sources but cannot override them. Do not use an older experimental or design baseline merely because a prior Plan was reviewed.
 
-Use the sources that establish the intended work:
+Separate:
 
-- explicit user direction and accepted shared understanding;
-- a Spec, issue, technical design, diagnosis, requirements, or Working Record when one exists;
-- relevant code, tests, policies, ADRs, and established behavior;
-- current external sources when an API, platform, or version constrains execution.
+- the required outcome and non-goals;
+- accepted design choices and constraints;
+- the supported implementation approach;
+- assumptions whose failure would invalidate dependent work;
+- unresolved or intentionally deferred work outside this Plan's promise.
 
-When a Spec or decision artifact is linked, preserve its contract rather than silently reinterpreting it. Live evidence overrides stale memory. A Working Record, handoff, review item, or earlier Plan is not authority over contradictory user decisions or source truth.
+An experiment produces evidence, not an automatic requirement. Include its consequences only where selected for this outcome; do not omit consequences the user subsequently accepted.
 
-## Write The Ordered Strategy
+## Write The Smallest Useful Strategy
 
-Read [plan shapes](references/plan-shapes.md) and choose the smallest shape that makes the intended execution inspectable.
+Read [Plan Shapes](references/plan-shapes.md) before choosing the artifact shape.
 
-Include, when relevant:
+Include relevant goal, sources, scope, decisions, assumptions, dependencies, ordered coherent outcomes, focused checks, integration, completion conditions, and what would invalidate the strategy. Use exact paths and commands when known and useful; do not invent them to make the Plan look executable.
 
-- goal, source, scope, and non-goals;
-- accepted decisions, assumptions, dependencies, and required order;
-- phases and slices with coherent, bounded results;
-- checks, integration, and final acceptance;
-- conditions that would invalidate the Plan.
+Size outcomes for manageable working context, dependencies, uncertainty, and checking. Do not divide mechanically by file, bug count, test, or method. The complete task may require several Slices, but each should have a coherent result and a clear dependency on earlier work where one exists.
 
-Include exact paths, systems, and commands when known and useful. Do not guess them to make the Plan appear complete.
+A validation step may stop the Plan if a bounded assumption fails. If its result is expected to select among materially different strategies, keep dependent work provisional in the Working Record rather than presenting the later sequence as decided.
 
-Each slice should produce a coherent result that can be checked. A validation step may stop the Plan when a known assumption fails. If its result is expected to choose among materially different strategies, use a Working Record learning slice instead of pretending the later Plan is known.
+The Plan is not a context inventory. Specify only the sources and relationships needed to explain or execute its steps, leaving ordinary local choices to the executing agent.
 
-## Select Useful Checkpoints
+## Preserve Acceptance And Return Conditions
 
-During execution, every bounded activity is verified and silently self-reviewed before its result is accepted, reused, or claimed complete; do not restate that default unless its evidence boundary is unusual.
+Tie each material outcome and final check to the accepted behavior it serves. Do not let available tests redefine acceptance or claim whole-system completion from a narrow observer.
 
-At meaningful slice, phase, integration, risk, or continuity boundaries, consider independent review, a local commit, a user decision, or a continuity checkpoint. Record only selected checkpoints and their conditions. A slice ending or a fixed count alone does not justify a commit; prefer one when supported work forms a coherent rollback point or the next work may destabilize it.
+Keep the agreed user-facing return condition visible: return a proposed strategy, implement one Slice, finish the described task, or stop at a specified boundary. Internal delegation handbacks and context cycles are not automatic user checkpoints.
 
-Plan acceptance establishes the agreed strategy; it does not by itself authorize execution. When the user clearly approves execution of the Plan, that authority may cover its listed work, checks, reviews, Working Record updates, and local commits. It does not authorize push, integration, migration, deprecation, release, or launch. Planned commits remain conditional on live evidence and [Commit Work](../commit-work/SKILL.md) inspection.
+A Plan must not invent product behavior, compatibility, public interfaces, failure semantics, sensitive policy, migration, scale, retries, recovery, or extension machinery. Do not replace agreed scope with an unapproved MVP or later-version split.
 
-## Keep Plan And Working Record Separate
+Before a new prerequisite becomes a planned obligation, determine whether it serves an accepted requirement or only preserves a particular approach. Resolve consequential alternatives instead of hiding them in confident steps.
 
-The Plan records the intended execution path. The Working Record records actual execution, current slices, evidence, task-local decisions, deviations, and next action.
+## Select Checkpoints Without Making A Schedule Of Ceremonies
 
-Do not revise the Plan for slice progress, expected evidence, status changes, or reversible local choices. Record those events in the Working Record when one exists.
+Ordinary verification and silent self-review belong to producing each supported result. Do not restate them as independent gates unless a particular evidence boundary needs explanation.
 
-Link accepted behavior, contracts, and architecture rationale from the owning Spec or decision artifact instead of duplicating them in the Plan.
+Include independent review, a local commit, a user decision, or continuity transfer only when selected to protect a concrete dependency, risk, rollback, or delivery boundary. A Slice ending or a fixed count is insufficient.
 
-## Stop Before Inventing A Path
+Accepting a Plan as a strategy is not permission to execute it. Explicit approval to execute the Plan may cover its listed work, checks, selected reviews, record maintenance, and local commits. It does not imply push, integration, migration, deprecation, release, or launch. Planned commits remain conditional on fresh evidence and [Commit Work](../commit-work/SKILL.md) inspection.
 
-Stop when writing would:
+When an existing agreement already covers the work, preserve that source instead of asking the user to approve the same scope again because it is now written down.
 
-- invent or change requirements, scope, public behavior, compatibility, sensitive policy, failure semantics, or hard-to-reverse design;
-- hide unresolved strategy, architecture, dependencies, or owner choices inside confident steps;
-- plan a production fix from a guessed cause;
-- rewrite tests, docs, policies, or acceptance merely to make the proposed path succeed;
-- add speculative abstractions, migration machinery, retries, recovery, scale, or extension points;
-- replace agreed scope with an unapproved MVP, v1/v2, roadmap, or later-version split.
+## Revise Only The Affected Strategy
 
-Route the unresolved issue to its owner rather than writing a Plan that assumes the answer.
+Do not update a Plan for completed steps, ordinary local choices, test counts, or routine status. Record material actual state through Track Work when present.
 
-## Revise Only From Founded Evidence
+Revise or supersede the affected strategy when accepted intent or supported evidence changes its scope, design, ordering, dependencies, checks, or mechanism. Preserve valid earlier work and rationale. A clerical correction does not reopen the strategy, and reaching a review cap is not evidence that the Plan needs rewriting.
 
-Write Plan also owns deliberate Plan revisions.
+Identify affected upstream and downstream artifacts. Revise only content whose owned meaning changed and whose mutation is authorized. If an upstream contract remains unresolved, mark dependent steps contingent before they are used. Do not repair consistency by silently changing the required outcome.
 
-Correct clerical mistakes directly. Do not revise the Plan for ordinary local choices or expected progress.
+## Self-Review Before Treating The Plan As Usable
 
-Revise or supersede the affected Plan when supported evidence materially changes its scope, design, architecture, order, dependencies, checks, or execution mechanism. An accepted review item may support revision. Reaching the independent-review cap does not itself justify rewriting the Plan; revise only when diagnosis or evidence shows that the Plan is wrong or insufficient.
+After factual source checks, use [Review Artifact](../review-artifact/SKILL.md) for one silent author self-review of the complete Plan, accepted sources, and intended execution boundary.
 
-Record the reason and execution impact in the Working Record when one exists. Revise a linked Spec or decision artifact only when its owned content changed. Preserve unaffected Plan content and history.
+Check whether the ordered work can achieve the accepted outcome, dependencies are supported, later uncertainty is honest, final checks match acceptance, and selected checkpoints are proportionate. Correct clear covered defects and recheck affected facts and lenses.
 
-## Self-Check
+Do not automatically dispatch an independent reviewer after writing or revising a Plan. Use Review Artifact's independent route only when separately selected and authorized to protect a concrete boundary. Supply complete sources, dependencies, and limits; adjudicate the returned report before acting on its findings.
 
-Silently review the Plan before routing it onward:
+Neither self-review nor independent review grants user acceptance or execution authority. Conversely, an already-covered execution agreement does not need another approval turn solely because planning produced an artifact.
 
-- Are the intended result, source, and scope clear?
-- Can coherent, checkable slices proceed in the stated order?
-- Are dependencies, integration, final checks, and invalidation conditions represented?
-- Are selected checkpoints useful and proportionate rather than automatic ceremony?
-- Did the Plan invent intent, disguise material uncertainty, or absorb rolling task state?
+## Report And Return
 
-Correct clear local issues directly. Surface only material gaps that prevent the Plan from being executable or fit for review.
+Report the Plan path and intended use, source basis, material assumptions or contingent work, invalidation conditions, selected checkpoints, and actual review/acceptance/execution-authority status.
 
-## Review The Plan
-
-After writing or materially revising the Plan, route it to [Review Artifact](../review-artifact/SKILL.md) before treating it as ready for approval and execution.
-
-Provide the reviewer with the complete Plan, intended use, source truth, linked artifacts, dependencies, selected checkpoints, and known evidence gaps. Review Artifact owns dependency ordering, review items, judgment, adjudication, and the review cycle. Artifact review establishes fitness; the user separately accepts the Plan and grants any scoped execution authority.
-
-## Report
-
-State:
-
-- Plan path and intended use;
-- source context and linked artifacts;
-- material assumptions, blockers, or invalidation conditions;
-- selected review, commit, user, or continuity checkpoints;
-- artifact-review, Plan-acceptance, and execution-authorization status.
+Return the supported strategy to the requesting activity. If the agreement covers implementation, the agent can continue through the normal execution route; if it asks for a Plan first, stop there. Do not begin work outside that agreement or claim an unresolved strategy is ready.

package/skills/write-plan/references/plan-shapes.md

@@ -20,7 +20,7 @@ When no convention exists and future readers need durable identity, begin with a
 > **Source:** <spec, issue, Working Record, diagnosis, or accepted context>
 ```
 
-Use one current status. Follow the repository or owner's vocabulary; useful states may include `Draft`, `Reviewed`, `Ready`, `Superseded`, and `Abandoned`. Writing or reviewing a Plan does not by itself make it `Ready`.
+Use one current status. Follow the repository or owner's vocabulary; useful states may include `Draft`, `Reviewed`, `Ready`, `Superseded`, and `Abandoned`. Writing or reviewing a Plan does not by itself make it `Ready`. State whether any recorded review was author self-review or selected independent review; neither implies user acceptance or execution authority.
 
 Add dates, supersession links, or approvers only when useful and reliable.
 
@@ -39,7 +39,7 @@ Dependencies:
 Required order:
 ```
 
-Link accepted behavior, architecture, and decisions instead of copying their rationale. Do not hide unsettled design or owner choices as assumptions. If an assumption could choose among materially different strategies, resolve it before treating the Plan as executable.
+Link accepted behavior, architecture, and decisions instead of copying their rationale. Identify the governing source version and relevant accepted amendments when they affect execution. Do not hide unsettled design or owner choices as assumptions. If an assumption could choose among materially different strategies, resolve it before treating the Plan as executable. Experimental findings become planned obligations only when selected for the accepted outcome; a previously reviewed baseline does not excuse omitting a later accepted change.
 
 ## Choose The Execution Shape
 
@@ -106,7 +106,7 @@ A slice is a coherent result, not a file list. Mention files, modules, or system
 
 Consider checkpoints at meaningful slice, phase, integration, risk, and continuity boundaries. Record only useful additions; normal verification and silent self-review need no repeated fields.
 
-A selected local commit names its coherent outcome and conditions, not merely “commit after this slice.” Plan approval authorizes listed local commits subject to live evidence and Commit Work inspection, but not push, integration, migration, deprecation, release, or launch. Record actual results and commit identities in the Working Record.
+A selected local commit names its coherent outcome and conditions, not merely “commit after this slice.” Approval to execute the Plan may authorize listed local commits subject to live evidence and Commit Work inspection; approval of its strategy alone does not. Neither implies push, integration, migration, deprecation, release, or launch. Record actual results and commit identities in the Working Record.
 
 ## Adapt For The Work Type
 
@@ -151,6 +151,6 @@ These conditions stop or revise the affected Plan. They are not alternate branch
 
 A local implementation detail, expected result, or completed slice does not revise the Plan.
 
-For a founded material change, update only the affected strategy and dependencies, record why it changed, preserve prior rationale, and update linked artifacts only when their content changed.
+For a founded material change, update only the affected strategy and dependencies, record why it changed, and preserve prior rationale. Update linked artifacts only when their owned content changed and revision is authorized; otherwise mark dependent work contingent and return the missing decision or revision.
 
-Use a superseding Plan when editing in place would obscure what was originally reviewed. Route a materially revised or superseding Plan through artifact review again.
+Use a superseding Plan when editing in place would obscure the earlier accepted strategy or reviewed state. Apply author self-review through Review Artifact to a materially revised or superseding Plan. Independent review is separately selected and authorized when it protects a concrete boundary, not required merely because the Plan changed.

package/skills/write-spec/SKILL.md

@@ -1,104 +1,92 @@
 ---
 name: write-spec
-description: Use when writing or revising a spec, PRD, issue, API contract, technical design, migration contract, decision artifact, or similar durable document.
+description: "Use when writing or revising a spec, PRD, issue, API contract, technical design, migration contract, decision artifact, or similar durable document."
 ---
 
 # Write Spec
 
-Turn clear intent and source evidence into a durable artifact that later work can rely on.
+Turn accepted intent and source evidence into a durable artifact that later work can use without inheriting invented requirements or losing accepted changes.
 
-A spec may be broad, deep, or both. Its shape follows its intended use. It is not a transcript, implementation plan, Working Record, or polished substitute for an unresolved decision.
+A Spec describes content, behavior, constraints, and uncertainty for its intended use. It is not an implementation sequence, Working Record, transcript, or permission grant. Useful technical depth is welcome; hypothetical completeness is not required.
 
-## Identify The Artifact
+## Establish The Artifact's Job
 
-Before writing, establish:
+Identify the artifact type, intended reader or future action, accepted scope, destination, and unresolved questions it must preserve.
 
-- artifact type and intended use;
-- audience or future action it must support;
-- accepted intent, scope, and source context;
-- destination and repository convention;
-- unresolved questions that belong in the artifact.
+Answer questions about a Spec without editing it unless revision is requested. Use [Discuss](../discuss/SKILL.md) when direction or alternatives remain materially open, and [Decision Gate](../decision-gate/SKILL.md) for one blocking owner choice or source conflict. Do not repeat discussion that already settled the artifact's purpose.
 
-If the user is asking about an artifact, answer instead of writing one. If direction or alternatives still need shared understanding, read [Discuss](../discuss/SKILL.md). If one user-owned choice or source conflict blocks writing, read [Decision Gate](../decision-gate/SKILL.md).
+An agreement to draft a proposal permits proposed design, clearly labelled. It does not make that design accepted behavior. An agreement to implement accepted work may include documenting its supported contract; do not manufacture another user approval merely because a document was produced.
 
-Do not repeat discussion that already settled the artifact's intent.
+## Establish The Current Source Basis
 
-## Write From Source
+Use the sources that actually determine the artifact:
 
-Inspect the sources that define the artifact:
+- current user direction and accepted discussion, including later amendments;
+- existing Specs, issues, decisions, and contracts being revised or consumed;
+- relevant live code, tests, policy, ADRs, and established behavior;
+- current primary sources when an external version or interface constrains the result;
+- [Track Work](../track-work/SKILL.md) for task memory when a record exists.
 
-- explicit user decisions and current shared understanding;
-- [Track Work](../track-work/SKILL.md), which owns the living Working Record for current state, slices, task-local decisions, and evidence, when one exists;
-- relevant code, tests, requirements, policies, ADRs, and established behavior;
-- existing artifacts that this one revises or depends on;
-- current primary sources when an external contract or version matters.
+A record or implementation summary cannot override contradictory current intent or accepted source truth. Distinguish what was requested, what was proposed, what was accepted, and what an observation actually established.
 
-Use a Working Record as task memory, not authority over contradictory user decisions or live evidence. Distinguish accepted facts and decisions from hypotheses, proposals, and unresolved questions.
+Preserve enough source identity to recover the basis of a consequential statement. For an approval such as "proceed," retain the proposal and response together when their scope matters. Authorization to investigate or draft an option is not acceptance of undisclosed production consequences.
 
-Do not infer goals or requirements from adjacent repository details merely because they are available.
+Do not infer requirements from nearby code, existing tests, or available machinery merely because those sources exist. A test can faithfully protect an unnecessary mechanism.
 
-## Shape The Artifact By Its Job
+## Write Only What The Intended Use Needs
 
-Read [spec shapes](references/spec-shapes.md) and use only the sections that help the artifact perform its intended job. Read [artifact standards](references/artifact-standards.md) when choosing a durable destination, identity, status, or revision shape. Read [decision records](references/decision-records.md) when the artifact records a durable decision.
+Read [Spec Shapes](references/spec-shapes.md) before choosing the structure. Read [Artifact Standards](references/artifact-standards.md) when choosing destination, identity, status, source trail, or revision shape. Read [Decision Records](references/decision-records.md) when the artifact primarily preserves a decision and rationale.
 
-Include, when relevant:
+Include relevant purpose, scope, non-goals, accepted behavior, constraints, interfaces, consequential failure semantics, acceptance, and evidence. Explain architecture and ownership deeply where the intended use requires it; do not remove necessary detail just to shorten the document.
 
-- purpose, context, scope, and accepted content;
-- behavior, design, interfaces, constraints, and consequential failure semantics required by the artifact;
-- acceptance and suitable evidence;
-- accepted decisions, clearly marked uncertainty, and source references.
+When writing an implementation-guiding design whose unresolved representation, identity, ownership, algorithm, or failure choices could invalidate significant dependent work, read [Design for Depth](../design-for-depth/SKILL.md) and use its Implementation Decisions method. Preserve the selected choices and rationale, distinguishing fixed constraints from illustrative sketches and local freedom. Existing supported decisions need no fresh design exercise; open choices must remain visible rather than being filled with invented mechanics.
 
-A technical design may go deeply into architecture, interfaces, ownership, state, and failure behavior. Do not remove useful depth merely to keep the artifact short.
+Keep distinguishable:
 
-Do not turn the artifact into ordered execution phases, task status, slice history, or a volatile file inventory. Ordered execution belongs in a Plan; living task state belongs in the Working Record.
+- required behavior and accepted decisions;
+- supported facts and their evidence limits;
+- proposed implementation mechanisms;
+- tentative assumptions and open questions;
+- intentional deferrals and superseded direction.
 
-## Stop Before Inventing Intent
+Use the repository's vocabulary rather than inventing a new status schema. Place a consequential uncertainty where the reader makes the affected decision, not in a distant caveat after confident requirements.
 
-Stop when writing would:
+Keep ordered execution in a Plan and live progress in the Working Record. Link shared rationale rather than copying it into several independently maintained sources.
 
-- invent or silently change product behavior, scope, requirements, public interfaces, compatibility, sensitive policy, failure semantics, or hard-to-reverse design;
-- override code, tests, docs, policies, ADRs, or established behavior without resolving the conflict;
-- present a tentative proposal or assumption as accepted;
-- hide an owner decision behind `TBD`, polished prose, or an unmarked open question;
-- reduce agreed scope into MVP, v1/v2, roadmap, or later-version framing without approval;
-- create a destination or artifact convention whose authority or durability matters without resolving it.
+## Do Not Promote An Approach Into A Requirement
 
-Ask only for the decision that prevents the artifact from serving its intended use. Otherwise represent uncertainty honestly and continue.
+Before adding an obligation, identify its accepted source or why it is necessary for the stated outcome. A limitation of one implementation technique does not establish a need for stronger guarantees, host changes, new persistence, retries, or a subsystem.
 
-## Revise Deliberately
+When a consequential choice remains, present its concrete effect and supported alternatives through its owner. Do not settle it through normative prose, an unexplained assumption, or a polished placeholder.
 
-When revising an artifact:
+Stop the affected writing when it would silently change behavior, scope, public interfaces, compatibility, sensitive policy, failure semantics, or hard-to-reverse design. Do not rewrite source truth to suit implementation, or reduce agreed scope into an unapproved MVP, roadmap, or later-version split.
 
-- preserve accepted content that still holds;
-- update only what new intent or evidence changed;
-- keep superseded decisions and material rationale recoverable through the owning decision record, change history, or version control.
+Open questions need not stop unrelated content. A proposal can be fit for discussion while remaining unfit to authorize or guide production implementation; state that boundary clearly.
 
-Do not rewrite history or synchronize unaffected artifacts. A clerical correction does not reopen settled intent; a material revision changes the artifact's review boundary and may affect its dependencies.
+## Reconcile Material Changes
 
-## Self-Check
+Preserve accepted content that still holds. Change only what new intent or evidence affects, and keep consequential prior rationale recoverable through the owning decision record, change history, or version control.
 
-Silently review the artifact before routing it onward:
+When an accepted amendment or learning result changes the contract, identify the affected downstream Plan, acceptance check, or implementation assumption. Reconcile those dependencies when authorized; otherwise mark them contingent and return the needed revision before dependent use. Do not synchronize unrelated artifacts.
 
-- Does it perform its stated job?
-- Does it agree with accepted intent and source evidence?
-- Can a future reader distinguish required, tentative, open, deferred, and superseded information?
-- Is it broad and deep enough for its intended use without taking over another artifact's job?
-- Are consequential claims, failure behavior, and acceptance supported or explicitly unresolved?
-- Did writing introduce any decision the user did not make?
+Experimental learning does not automatically enter the production contract. Distinguish findings deliberately selected for implementation from observations retained as evidence or deferred possibilities. Conversely, do not keep using an older baseline after the user accepted a relevant change.
 
-Correct clear local issues directly. Surface only unresolved material issues that prevent the artifact from being fit for use.
+Do not rewrite historical decisions as though they always contained the new choice. Follow repository policy for historical records and supersession.
 
-## Review The Artifact
+## Self-Review Once Before Use
 
-After writing or materially revising the artifact, route it to [Review Artifact](../review-artifact/SKILL.md) before treating it as fit for its intended use.
+After checking source-backed factual claims, use [Review Artifact](../review-artifact/SKILL.md) for silent author self-review of the complete resulting artifact and its intended use.
 
-Provide the reviewer with the complete artifact, its intended use, source truth, dependencies, and known evidence gaps. Review Artifact owns review items, judgment, adjudication, and the review cycle.
+Check that it preserves accepted intent and amendments, separates requirements from proposals, has sufficient evidence and acceptance conditions, and keeps affected dependencies coherent. Correct clear covered defects, then recheck affected facts and review lenses. Return unresolved owner decisions instead of making the document internally consistent by inventing an answer.
 
-## Report
+This is the author's ordinary self-review, not another mandatory review cycle. Do not dispatch an independent reviewer merely because a Spec was written or materially revised.
 
-State:
+Independent review applies only when selected and authorized to protect a concrete boundary. Supply the complete artifact, source basis, dependencies, and evidence limits through Review Artifact's independent route. Its report ends the review; findings require adjudication before revision or use.
 
-- artifact path, type, and intended use;
-- source context used;
-- material unresolved questions or blocked decisions;
-- artifact-review status.
+Review establishes fitness, not user acceptance or execution authority. Respect an explicitly selected approval checkpoint, but do not create one for every artifact by default.
+
+## Report And Stop
+
+Report the artifact path, type, intended use, source basis, material unresolved or contingent content, and actual review/acceptance status. Do not label author self-review as independent review or use an approval status without its source.
+
+Stop when the authorized artifact is fit for its stated use or its blocking decision/evidence limit is explicit. Return to the requesting activity; writing a Spec does not begin implementation or authorize another outcome.

package/skills/write-spec/references/artifact-standards.md

@@ -49,7 +49,7 @@ Draft | Reviewed | Approved | Rejected | Superseded
 
 The appropriate statuses depend on the artifact type. An issue, policy, ADR, and API contract need not share one lifecycle.
 
-Status communicates artifact state; it does not replace review evidence or user authority.
+Status communicates artifact state; it does not replace review evidence or user authority. Distinguish author self-review from selected independent review when reporting review status. Writing a Spec or Plan does not automatically select an independent reviewer.
 
 ## Preserve Sources Without Copying Them
 
@@ -66,7 +66,7 @@ session:<session-id>/turn:<turn-id>
 
 Use identifiers that actually exist. Prefer links and concise quotations over copied inventories, logs, diffs, or transcripts.
 
-A source trail should let a future reader recover why the artifact says what it says. It does not require preserving every conversation turn.
+A source trail should let a future reader recover why the artifact says what it says. For consequential choices, preserve the relevant proposal, disclosed consequences, and acceptance source rather than an isolated “proceed” or an agent's approval summary. Distinguish accepted amendments from unselected experimental findings. This does not require preserving every conversation turn.
 
 ## Revise Without Rewriting History
 

package/skills/write-spec/references/decision-records.md

@@ -56,7 +56,7 @@ Use the repository's ADR or decision format when one exists. Otherwise adapt thi
 <Evidence, conditions, or later decision that would reopen or replace it.>
 ```
 
-State proposals as proposals. Do not write an assumption, reviewer suggestion, or agent preference as an accepted decision.
+State proposals as proposals. Do not write an assumption, reviewer suggestion, or agent preference as an accepted decision. For a consequential choice, identify the presented option, disclosed consequences, and acceptance source. Approval to investigate or draft an option does not establish acceptance of its eventual production requirements.
 
 ## Preserve Authority And History
 
@@ -67,7 +67,8 @@ When a decision changes:
 - preserve the old record as `Superseded` rather than rewriting it to match the present;
 - create or identify the replacement decision;
 - link both directions;
-- update owning specs, plans, or policies whose current content depends on it;
+- identify owning specs, plans, or policies whose current content depends on it and revise them when authorized;
+- mark dependent work contingent when a required decision or source revision remains unresolved;
 - preserve the evidence that justified the change.
 
 Live evidence may show that implementation violates a decision or that the decision is no longer viable. Use Decision Gate when resolving that conflict requires user authority.

package/skills/write-spec/references/spec-shapes.md

@@ -73,6 +73,21 @@ Possible sections:
 
 A technical design may contain implementation detail when that detail defines the accepted design. Ordered phases and execution slices still belong in a Plan.
 
+### Implementation Decisions
+
+Include this subsection when consequential engineering choices must survive implementation handoffs or context loss. For selecting those choices, use [Design for Depth](../../design-for-depth/SKILL.md); this shape preserves their result rather than duplicating the design method.
+
+Capture only what the intended implementation needs:
+
+- selected representation, identity, state owners, and module responsibilities;
+- essential algorithm, effect ordering, update/invalidation, and failure behavior;
+- source basis, rationale, and invariants;
+- a plausible wrong implementation and the observer that distinguishes it;
+- required constraints, suggested mechanics, and implementer freedom;
+- unresolved assumptions and conditions requiring reconsideration.
+
+A compact type or control-flow sketch is useful when it removes consequential ambiguity. Mark illustrative code as such; it is not the behavioral oracle. Keep the applicable revision recoverable and update only decisions affected by new evidence. Do not require this subsection for a product-only artifact or an already clear local change.
+
 ## API, Protocol, Or Interface Contract
 
 Use for a public or internal interface that callers will depend on.

package/pi-extension/dist/cognitive-routing/commands.js

@@ -1,96 +0,0 @@
-const PROFILE_VALUES = ["standard", "reasoning", "auto"];
-const HISTORY_VALUES = ["history", "history active", "history anomalies"];
-export function cognitiveRoutingProfileCompletions(prefix) {
-  const query = prefix ?? "";
-  return [...PROFILE_VALUES, ...HISTORY_VALUES]
-    .filter((value) => value.startsWith(query))
-    .map((value) => ({
-      value,
-      label: value,
-      description:
-        value === "auto"
-          ? "Release the manual hold and use the Reasoning profile"
-          : value === "history"
-            ? "Show Cognitive Routing transition history"
-            : value === "history active"
-              ? "Show current-branch Cognitive Routing history"
-              : value === "history anomalies"
-                ? "Show Cognitive Routing history anomalies"
-                : `Hold ${value} profile manually`,
-    }));
-}
-function historyOptions(value) {
-  if (value === "history") return {};
-  if (value === "history active") return { scope: "active-branch" };
-  if (value === "history anomalies") return { anomaliesOnly: true };
-  return undefined;
-}
-function formatHistory(result) {
-  const lines = [
-    `Cognitive Routing history: ${result.current.profile} · ${result.current.control}`,
-    `Events: ${result.events.length}; unresolved=${result.summary.unresolvedCount}; anomalies=${result.summary.anomalyCount}`,
-  ];
-  if (result.summary.latestSemanticEventId) lines.push(`Latest semantic: ${result.summary.latestSemanticEventId}`);
-  if (result.summary.latestCompletedEventId) lines.push(`Latest completed: ${result.summary.latestCompletedEventId}`);
-  for (const event of result.events) {
-    const transition = event.from && event.to ? ` ${event.from} → ${event.to}` : "";
-    lines.push(
-      `${event.jsonlPosition}: ${event.outcome} · ${event.classification}${transition} · changed=${event.changed} · ${event.id}`,
-    );
-  }
-  return lines.join("\n");
-}
-export async function handleCognitiveRoutingProfileCommand(args, ctx, controller) {
-  const input = (args ?? "").trim().toLowerCase();
-  const [action, ...rest] = input.split(/\s+/);
-  if (action !== "profile") return false;
-  const value = rest.join(" ");
-  const historyView = historyOptions(value);
-  if (historyView) {
-    const result = ctx.history
-      ? await ctx.history(historyView)
-      : controller?.history
-        ? await controller.history(historyView)
-        : undefined;
-    if (result) {
-      ctx.ui?.notify?.(formatHistory(result), "info");
-    } else {
-      ctx.ui?.notify?.("Cognitive Routing history is unavailable for this session.", "warning");
-    }
-    return true;
-  }
-  if (!PROFILE_VALUES.includes(value)) {
-    ctx.ui?.notify?.(
-      "Usage: /freeflow profile standard, /freeflow profile reasoning, /freeflow profile auto, or /freeflow profile history [active|anomalies]",
-      "warning",
-    );
-    return true;
-  }
-  if (typeof ctx.isIdle === "function" && !ctx.isIdle()) {
-    ctx.ui?.notify?.("Freeflow settings and profile changes are available only while Pi is idle.", "warning");
-    return true;
-  }
-  if (!controller) {
-    ctx.ui?.notify?.(
-      "Cognitive Routing is unavailable for this session. It may be disabled, unsupported by the Pi host, or suppressed by an explicit startup model selection.",
-      "warning",
-    );
-    return true;
-  }
-  if (value === "auto") {
-    const result = await controller.setAutomaticControl();
-    if (result.status === "automatic") {
-      ctx.ui?.notify?.("Cognitive Routing manual hold released; automatic Reasoning control is active.", "info");
-    } else {
-      ctx.ui?.notify?.(`Cognitive Routing could not release the manual hold: ${result.reason}.`, "warning");
-    }
-    return true;
-  }
-  const result = await controller.setManualProfile(value);
-  if (result.status === "active") {
-    ctx.ui?.notify?.(`Cognitive Routing manual hold set to ${result.profile}.`, "info");
-  } else {
-    ctx.ui?.notify?.(`Cognitive Routing could not set the manual profile: ${result.reason}.`, "warning");
-  }
-  return true;
-}