@researai/deepscientist 1.5.17 → 1.6.0

package/src/skills/decision/SKILL.md

@@ -7,17 +7,77 @@ skill_role: stage
 # Decision
 
 Use this skill whenever continuation is non-trivial.
+Use it to make one route judgment from durable evidence and then get the quest moving again.
+
+## Match signals
+
+Use `decision` when:
+
+- the next stage is not obvious
+- the evidence is mixed
+- the current line may need to stop
+- the quest needs a branch, reset, or reuse-baseline judgment
+- a user preference-sensitive choice remains
+- a blocker needs an explicit route
+
+Do not use `decision` when:
+
+- the active mainline is still too ambiguous for a real route judgment and should first be reconciled through `intake-audit`
+- the next move is already obvious from durable evidence and can proceed directly
+- the task is really baseline recovery, scouting, ideation, or execution rather than a route judgment
+
+## One-sentence summary
+
+Make one route judgment from durable evidence, record the verdict and smallest valid action, then keep the quest moving.
+
+## Control workflow
+
+1. Check whether the board is decision-ready.
+   If the current mainline, latest decisive result, or stale-route state is unclear, route through `intake-audit` first.
+2. State the real question and gather only decision-relevant evidence.
+   Compress the strongest support, strongest contradiction, main risk, main cost, and what is genuinely new.
+3. Choose the smallest canonical action that resolves the current state.
+   Make the winner, main rejected alternatives, and the decisive reason explicit.
+4. Record the decision durably.
+   Include verdict, action, reason, evidence paths, and next stage or next direction.
+5. Ask the user only when local evidence cannot safely resolve a real preference, scope, or cost choice.
+
+## AVOID / pitfalls
+
+- Do not repeat the same decision without new evidence.
+- Do not decide from vibe, momentum, or optimism.
+- Do not hide a blocked state behind a vague “continue”.
+- Do not launch analysis campaigns casually when the expected information gain is weak.
+- Do not choose among candidate packages without naming why the alternatives lost.
+- Do not imply baseline reuse is resolved unless the concrete attachment and confirmation path is clear.
+- Do not choose `finalize` for a paper line unless manuscript coverage reports `submission_ready=true`; a draft checkpoint routes back to `write`, and a review package routes to `review`.
+- Do not keep a paper route alive after a publishability stop-loss finding. If durable evidence shows that novelty, evidence sufficiency, or reader value has collapsed beyond reasonable narrowing, recommend `stop` or `branch`, and record any narrowed non-paper objective as the next direction rather than as a new action. Do not execute `stop` for a low-quality paper judgment without asking the user to confirm that route.
+
+## Constraints
+
+- Use durable evidence, not impressions, as the basis for route judgment.
+- Use the smallest canonical action that genuinely resolves the state.
+- When baseline reuse or attachment is selected, land it concretely and leave an explicit blocker or waiver if the baseline gate still cannot clear.
+- Use blocking user requests only when the user truly must choose.
+- Later stages must not need to guess what was decided, why it was decided, or what happens next.
+
+## Validation
+
+Before `decision` can end, all applicable checks should be true:
+
+- the route question is explicit
+- the decisive evidence is explicit
+- the chosen action matches the actual state
+- the main rejected alternative or blocker is visible
+- the decision is durably recorded with verdict, action, reason, evidence paths, and next direction
+- the next stage or next action is explicit
 
 ## Interaction discipline
 
-- Follow the shared interaction contract injected by the system prompt.
-- For ordinary active work, prefer a concise progress update once work has crossed roughly 6 tool calls with a human-meaningful delta, and do not drift beyond roughly 12 tool calls or about 8 minutes without a user-visible update.
-- Message templates are references only. Adapt to context and vary wording so updates feel natural and non-robotic.
-- If the runtime starts an auto-continue turn with no new user message, continue from the active requirements and durable quest state instead of replaying the previous user turn.
-- If `startup_contract.decision_policy = autonomous`, do not emit ordinary `artifact.interact(kind='decision_request', ...)` calls; decide the route yourself, record the reason, and continue.
-- Use `reply_mode='blocking'` for the actual decision request only when the user must choose before safe continuation and the quest contract still allows a user-gated decision.
-- If a threaded user reply arrives, interpret it relative to the latest decision or progress interaction before assuming the task changed completely.
-- Quest completion is a special terminal decision: first ask for explicit completion approval with `artifact.interact(kind='decision_request', reply_mode='blocking', reply_schema={'decision_type': 'quest_completion_approval'}, ...)`, and only after an explicit approval reply should you call `artifact.complete_quest(...)`.
+Follow the shared interaction contract injected by the system prompt.
+Avoid repeating the same decision without new evidence, and use blocking requests only when the user truly must choose.
+For ordinary active work, prefer a concise progress update once work has crossed roughly 6 tool calls with a human-meaningful delta, and do not drift beyond roughly 12 tool calls or about 8 minutes without a user-visible update.
+When a decision materially resolves ambiguity and the quest can continue automatically, follow the durable record with `artifact.interact(kind='milestone', reply_mode='threaded', ...)` so the user can see the chosen route, the decisive evidence, and the next checkpoint.
 
 ## Tool discipline
 
@@ -26,30 +86,27 @@ Use this skill whenever continuation is non-trivial.
 - **For git state inside the current quest repository or worktree, prefer `artifact.git(...)` before raw shell git commands.**
 - **Use `decision` to judge the route, not as an excuse to bypass the `bash_exec(...)` / `artifact.git(...)` tool contract.**
 
-## Stage purpose
+## Truth sources
 
-`decision` is not a normal anchor.
-It is a cross-cutting control skill that should be used whenever the quest must decide:
+Make decisions from durable evidence:
 
-- whether to continue
-- whether to branch
-- whether to attach or reuse a baseline
-- whether to launch an experiment
-- whether to launch an analysis campaign
-- whether to move to writing
-- whether to finalize
-- whether to reset
-- whether to stop
-- whether to ask the user for a structured decision
+- the current board packet when one exists
+- recent run artifacts
+- report artifacts
+- baseline state
+- quest documents
+- memory only as supporting context
 
-## Use when
+Do not make major decisions from vibe or momentum.
+Do not treat `decision` as a substitute for state reconciliation when the active mainline is still ambiguous.
 
-- the next stage is not obvious
-- the evidence is mixed
-- the current line may need to stop
-- the quest needs a branch or reset
-- a user preference-sensitive choice remains
-- a blocker needs an explicit route
+When the quest is algorithm-first, add one extra truth-source rule before non-trivial route choices:
+
+- read `artifact.get_optimization_frontier(...)`
+- treat the frontier as the primary optimize-state summary
+- only override it when newer durable evidence clearly dominates
+- if the frontier says `explore`, do not collapse immediately to exploit unless the latest durable result clearly changes the frontier
+- if the frontier says `fusion`, judge whether complementary lines can be merged before launching another isolated candidate
 
 ## Required decision record
 
@@ -61,14 +118,9 @@ Every consequential decision should make clear:
 - evidence paths
 - next stage or next direction
 
-## Recommended verdicts
-
-- `good`
-- `bad`
-- `neutral`
-- `blocked`
+Keep the verdict simple and legible, and make sure the chosen action matches the actual state rather than sounding optimistic by default.
 
-## Allowed actions
+## Canonical actions
 
 Use the following canonical actions:
 
@@ -82,6 +134,7 @@ Use the following canonical actions:
 - `attach_baseline`
 - `publish_baseline`
 - `write`
+- `review`
 - `finalize`
 - `iterate`
 - `reset`
@@ -90,275 +143,37 @@ Use the following canonical actions:
 
 Choose the smallest action that genuinely resolves the current state.
 
-In the current runtime, prefer these concrete flow actions:
-
-- record a candidate brief before branch promotion -> `artifact.submit_idea(mode='create', submission_mode='candidate', ...)`
-- accepted idea -> `artifact.submit_idea(mode='create', lineage_intent='continue_line'|'branch_alternative', ...)`
-- promote a candidate brief into a durable optimization line -> `artifact.submit_idea(mode='create', submission_mode='line', source_candidate_id=..., lineage_intent='continue_line'|'branch_alternative', ...)`
-- maintenance-only in-place cleanup of the same branch -> `artifact.submit_idea(mode='revise', ...)`
-- compare branch foundations before a new round -> `artifact.list_research_branches(...)`
-- return to an older durable branch without creating a new node -> `artifact.activate_branch(...)`
-- materialize the concrete main-result node when a real main experiment line is about to be or was just durably recorded -> dedicated child `run/*` branch/worktree
-- start the next optimization round from a measured result -> `artifact.record(payload={'kind': 'decision', 'action': 'iterate', ...})`
-- launch analysis campaign -> `artifact.create_analysis_campaign(...)`
-- finish one analysis slice -> `artifact.record_analysis_slice(...)`
-- select a paper outline -> `artifact.submit_paper_outline(mode='select', ...)`
-- revise the selected paper outline -> `artifact.submit_paper_outline(mode='revise', ...)`
-- close writing into a durable bundle -> `artifact.submit_paper_bundle(...)`
-
-If the chosen action is baseline reuse, the decision is not complete until one of these is durably true:
-
-- the reuse landed on `artifact.attach_baseline(...)` plus `artifact.confirm_baseline(...)`
-- or the quest recorded an explicit blocker or waiver explaining why reuse could not be completed safely
-
-Treat `prepare_branch` as a compatibility or recovery action, not the normal path.
-Treat `activate_branch` as the correct recovery or revisit action when the quest should resume on an existing older durable branch while preserving the newer research head.
-Treat each accepted branch as one durable research round.
-Treat candidate briefs as branchless pre-promotion objects; they are not yet durable optimization lines.
-If a branch already has a durable main-experiment result, a genuinely new optimization round should normally create a child branch from a chosen foundation rather than keep revising that old branch in place.
-Treat each durable main experiment as its own child `run/*` branch/node, not as another mutable state on the idea branch.
-When paper mode is enabled and the necessary analysis for a strong run is done, the next default route is `write` on a dedicated `paper/*` branch/worktree derived from that run branch.
-Do not approve `launch_analysis_campaign` casually; analysis usually carries extra resource cost and should require clear academic or claim-level value before spending that budget.
-
-## Truth sources
-
-Make decisions from durable evidence:
-
-- recent run artifacts
-- report artifacts
-- baseline state
-- quest documents
-- memory only as supporting context
-
-Do not make major decisions from vibe or momentum.
-
-When the quest is algorithm-first, add one extra truth-source rule before non-trivial route choices:
-
-- read `artifact.get_optimization_frontier(...)`
-- treat the frontier as the primary optimize-state summary
-- only override it when newer durable evidence clearly dominates
-
-## Workflow
-
-### 1. State the question
-
-Write the real question explicitly, such as:
-
-- is the current idea promising enough to continue?
-- is baseline reuse sufficient?
-- is more analysis needed before writing?
-- is the draft good enough to finalize?
-
-### 2. Collect the evidence
-
-Summarize only the decision-relevant evidence:
-
-- strongest support
-- strongest contradiction
-- missing dependency
-- known cost or risk
-
-### 3. Choose verdict and action
-
-Typical mapping:
-
-- `good`
-  - continue, branch, launch experiment, write, finalize
-- `neutral`
-  - branch, activate branch, launch analysis campaign, request user decision
-- `bad`
-  - reset, stop
-- `blocked`
-  - reuse baseline, attach baseline, request user decision, stop
-
-The action must match the actual state.
-
-### 3.1 Selection among candidate packages
-
-When the decision is about choosing among multiple candidate outputs, such as:
-
-- experiment groups
-- idea branches
-- outline drafts
-- revision candidates
-- competing reports
-
-do not decide implicitly.
-
-Record:
-
-- candidate ids or names
-- the explicit selection criteria
-- the winner
-- why the winner is preferred
-- why the main alternatives were not chosen
-
-When the choice is about an experiment package or analysis package, also record:
-
-- implementation priority order
-- what you expect to learn from the chosen package
-
-When the choice is about paper outline candidates, also record:
-
-- which outline best matches the actual evidence inventory
-- which `research_questions` and `experimental_designs` become the active contract after selection
-- whether more analysis is still required before drafting
-- whether the winning outline preserves strong:
-  - method fidelity
-  - evidence support
-  - story coherence
-  - experiment ordering
-
-Typical criteria include:
-
-- evidence quality
-- feasibility
-- comparability
-- expected information gain
-- narrative coherence
-- downstream usefulness
-
-For paper outline candidates specifically, prefer a paperagent-like rubric:
-
-- story quality around `motivation -> challenge -> resolution -> validation -> impact`
-- faithful method description rather than idealized storytelling
-- real experiment coverage rather than speculative placeholders
-- comparable baseline usage only where setups truly match
-- main-comparison-first ordering when the evidence supports it
-
-If evaluator scores exist, use them.
-Do not blindly follow a score if the underlying evidence is weak; explain the override when needed.
-
-### 3.2 Research-route selection heuristic
-
-When the decision is about choosing a research direction, experiment route, or branch to invest in:
+For paper-outline decisions, use `artifact.submit_paper_outline(mode='select', ...)` when selecting an existing candidate and `artifact.submit_paper_outline(mode='revise', ...)` when the selected outline needs repair.
+For paper-bundle decisions, use `artifact.submit_paper_bundle(...)` only when the draft or package state is durable enough for that package type.
+When deciding whether a paper line can advance, judge method fidelity and story coherence as well as metric coverage.
+For paper routes, apply the publishability stop-loss rule before choosing `write`, `review`, or `finalize`: if the line cannot plausibly become a useful and defensible paper, recommend stopping the paper objective or branching to a stronger route instead of adding another writing pass. If the proposed action is `stop` because paper quality is too low, first ask for a user decision with the evidence and the branch/narrow alternatives. If the user has given publication, scope, cost, or non-paper preferences, consider them explicitly; if those preferences are unclear and materially affect the stop/branch choice, ask for a user decision.
 
-- identify the core insufficiency being targeted
-- prefer routes that address that insufficiency elegantly rather than only spending more compute, more stages, or more complexity
-- prefer routes that respect the current codebase architecture unless there is strong evidence that a deeper break is justified
-- balance breakthrough potential against implementation risk and verification cost
+Apply the symmetric **exploration-depth gate before recommending `close_round_write_paper` for an all-negative-result paper** (every attempted idea has been falsified or family-bounded, no positive lift survives). Before routing to `write`, answer all of these in the decision artifact:
 
-Use a light incumbent/frontier discipline for non-trivial route decisions:
+- Have you tested at least two structurally distinct idea families from `idea/references/idea-thinking-flow.md` (mechanism, objective, measurement, infrastructure, or model-architecture / ensemble / multi-agent), or only multiple variants inside one family?
+- Have you challenged the bottleneck framing itself — is "X is the locus of the residual gap" a conclusion or just an artefact of where you stopped looking?
+- Has the literature surfaced a structurally different route the current attempts did not cover (cross-domain mechanism transfer, different evaluator regime, different training-data composition, etc.)?
+- How much of the quest's `time_budget_hours` is unused, and could a third structurally distinct family fit inside the remainder?
 
-- identify the current `incumbent`:
-  - the best-supported active line from existing results, prior decisions, and literature
-- identify a small `frontier`:
-  - usually 2 to 3 serious alternatives worth comparing against the incumbent
-- choose the action that best follows from existing evidence:
-  - continue the incumbent
-  - branch to a frontier alternative
-  - stop or downgrade the line
-  - move to writing if the core claim is already sufficiently supported
+If any answer is "no" or "unsure" and the time budget allows, route back to `idea` for a re-ideation pass focused on a structurally different family before concluding. The negative-result paper is still the right outcome when the gate is honestly cleared; this gate just prevents premature closure when only one corner of the design space has been ruled out. Positive-result papers are not blocked by this gate.
+For resume-changing route decisions, write one compact checkpoint-style quest memory card so later turns know the current active node, node history, what not to reopen by default, and the first files to read.
+Use `type:checkpoint-memory` and `references/checkpoint-memory-template.md` for that card.
 
-For these decisions, do not default to launching a small exploratory run just to break ties.
-Prefer careful judgment from durable evidence already on hand, especially:
+## Operational guidance
 
-- observed result trends
-- failure modes and confounders
-- baseline-relative position
-- related-work saturation or overlap
-- implementation surface and verification burden
+The main skill keeps the control surface in front.
+For the longer judgment and route-shaping notes, read:
 
-When recording the decision, make explicit:
+- `references/strategic-decision-template.md`
+- `references/research-route-criteria.md`
+- `references/operational-guidance.md`
+- `references/checkpoint-memory-template.md`
 
-- why the incumbent still wins, or why it should be replaced
-- which alternatives were serious enough to compare
-- which existing evidence was decisive
-- what residual risk remains after the choice
+Use them when:
 
-For algorithm-first route choices, prefer this default mapping:
-
-- frontier says `explore` -> widen or refine candidate briefs before new branch creation
-- frontier says `exploit` -> keep the strongest line active and advance the best implementation candidates
-- frontier says `fusion` -> open at most one bounded fusion candidate
-- a fixable candidate failure dominates -> run a debug route instead of widening search blindly
-- frontier says `stop` -> record the stop decision and explicit reopen condition
-
-Good route-selection criteria often include:
-
-- feasibility
-- scientific importance
-- methodological rigor
-- expected information gain
-- architectural fit
-- complexity risk
-- downstream narrative value
-
-When selecting an experiment package, make the choice as if you must later justify:
-
-- why this package is the best balance of implementability and scientific value
-- what order the experiments should be implemented in
-- what concrete learning each step is expected to produce
-
-If one option is more novel but much less testable, say that explicitly instead of hiding the tradeoff.
-
-### 4. State the reason
-
-The reason should be concrete and evidence-backed.
-Avoid generic wording like “seems better”.
-
-When the decision is stage-shaping, prefer a richer structure that later stages can execute directly.
-Useful optional fields include:
-
-- `target_idea_id`
-- `target_run_id`
-- `campaign_id`
-- `reflection`
-  - `what_worked`
-  - `what_failed`
-  - `learned_constraints`
-- `next_direction`
-  - objective
-  - key steps
-  - success criteria
-  - abandonment criteria
-- `expected_roi`
-  - `cost_estimate`
-  - `confidence`
-  - qualitative improvement estimate with justification
-
-When a decision materially changes the route, follow it with the appropriate user-visible `artifact.interact(...)` update:
-
-- use threaded `artifact.interact(kind='milestone', reply_mode='threaded', ...)` when the decision is already durably resolved and the quest can continue automatically
-- use `reply_mode='blocking'` only when the user must choose before safe continuation and `startup_contract.decision_policy` is not `autonomous`
-- the user-facing update should name the chosen action, the decisive evidence, the rejected alternative, and the next checkpoint
-
-This is especially useful for:
-
-- idea branch selection
-- experiment package selection
-- launch of an analysis campaign
-- reactivation of an older durable branch
-- post-campaign routing
-- stop / pivot / finalize choices
-
-### 5. Request user input only when needed
-
-Ask the user only when:
-
-- multiple options are all plausible
-- the choice depends on preference, cost, or scope
-- the missing information cannot be derived locally
-
-When asking, use a structured decision request with:
-
-- concise question
-- 1 to 3 concrete options
-- tradeoffs, including the main pros and cons for each option
-- recommended option first
-- explicit reply format
-- a stated timeout window; normally wait up to 1 day before self-resolving if no user reply arrives, except when the only blocker is a missing external credential or secret that only the user can provide
-
-### 6. Record the decision durably
-
-Use `artifact.record(payload={'kind': 'decision', ...})` for the final decision.
-
-If user input is needed, also use `artifact.interact(kind='decision_request', ...)`.
-If the timeout expires without a user reply, choose the best option yourself, record why, and notify the user of the chosen option before moving on.
-This does not apply when the only blocker is a missing external credential or secret that only the user can provide; in that case keep the interaction waiting and, if resumed without the credential, you may park with `bash_exec(command='sleep 3600', mode='await', timeout_seconds=3700)` instead of busy-looping.
-
-If `startup_contract.decision_policy = autonomous`, ordinary route ambiguity is not by itself grounds to request user input.
-In that mode, only explicit approval-style exceptions such as quest completion should normally become blocking user decisions.
+- a richer route-change rationale is needed
+- research-route selection among candidate packages is the main difficulty
+- memory should preserve the new authoritative resume point
 
 ## Decision-quality rules
 
@@ -379,16 +194,8 @@ Weak decisions:
 - pretend blocked states are progress
 - choose a winner without naming the rejected alternatives or criteria
 
-## Memory rules
-
-Write to memory only when the lesson is reusable across future decisions, such as:
-
-- a recurring failure pattern
-- a reliable stop condition
-- a useful branching heuristic
-
-The canonical record of the decision itself belongs in `artifact`.
-
 ## Exit criteria
 
 Exit once the decision is durably recorded and the next stage or action is explicit.
+
+A good decision pass changes the route once; it does not keep re-explaining the same route without new evidence.

package/src/skills/decision/references/checkpoint-memory-template.md

@@ -0,0 +1,47 @@
+# Checkpoint Memory Template
+
+Use this when later turns could otherwise resume from the wrong node, route, or blocker.
+
+## Recommended structure
+
+### 1. Current route
+
+- current route label
+- current stage / anchor
+- short route judgment
+
+### 2. Current active node
+
+- active branch / run / paper node / report pair
+- why this is the authoritative resume point now
+
+### 3. Node history
+
+- predecessor node(s)
+- superseded node(s) or route(s)
+- why the current node beat or replaced them
+
+### 4. Strongest retained result or blocker
+
+- strongest still-valid result
+- or the dominant current blocker
+
+### 5. Do-not-reopen by default
+
+- experiments, routes, or closure paths that should stay closed unless new evidence appears
+- any explicit do-not-repeat rule
+
+### 6. Next resume step
+
+- the single best next step
+
+### 7. First-read files
+
+- `status.md`
+- `SUMMARY.md`
+- current `PLAN.md` / `CHECKLIST.md`
+- any route-critical report, manifest, or handoff file
+
+### 8. Reopen condition
+
+- exact condition that would justify reopening an older node or switching away from the current one

package/src/skills/decision/references/operational-guidance.md

@@ -0,0 +1,94 @@
+# Operational Guidance
+
+Use this reference when the decision route needs the longer tactical notes rather than the short control surface in `SKILL.md`.
+
+## Planning note
+
+Use quest or workspace planning files only as supporting state for the decision, not as a reason to open another planning loop when the real need is a route judgment.
+
+## Action note
+
+Prefer the smallest canonical action that resolves the route cleanly, and keep runtime-specific branching details out of the default decision payload unless they matter now.
+
+Use these concrete actions when the route actually requires them:
+
+- revisit an older durable research line with `artifact.activate_branch(...)`
+- land baseline reuse with `artifact.attach_baseline(...)`
+- accepted idea -> `artifact.submit_idea(mode='create', lineage_intent='continue_line'|'branch_alternative', ...)`
+- open paper-outline selection with `artifact.submit_paper_outline(mode='select', ...)`
+- close writing into a durable paper-facing bundle with `artifact.submit_paper_bundle(...)`
+
+Do not approve `launch_analysis_campaign` casually.
+Analysis usually carries extra resource cost and should require clear academic or claim-level value before spending that budget.
+
+## Baseline reuse note
+
+When the route judgment lands on baseline reuse or attachment:
+
+- use `artifact.attach_baseline(...)` to land on the concrete reusable baseline
+- use `artifact.confirm_baseline(...)` once the attached baseline is accepted as the active comparator
+- if baseline reuse still cannot clear the gate, leave an explicit blocker or waiver instead of implying the route is resolved
+
+## Selection among candidate packages
+
+When choosing among multiple candidate outputs, do not decide implicitly.
+Record the candidates, the criteria, the winner, and why the main alternatives lost.
+
+When the choice is paper-facing, prefer the option that best preserves:
+
+- method fidelity
+- evidence support
+- story coherence
+- experiment ordering that later `write` or `finalize` can defend
+
+## Research-route selection heuristic
+
+When the decision is about a research direction, experiment route, or branch:
+
+- identify the core insufficiency being targeted
+- prefer a small serious frontier over many weak alternatives
+- prefer careful judgment from durable evidence over launching tie-break runs by reflex
+- record why the winner won, why the main alternatives lost, and what residual risk remains
+
+The route heuristic is intentionally lightweight: compare the incumbent against a small serious frontier and choose one dominant next move.
+For algorithm-first routing, prefer this compact mapping:
+
+- frontier says `explore` -> widen or refine candidate briefs before new branch creation
+- frontier says `exploit` -> keep the strongest line active and advance the best implementation candidates
+- frontier says `fusion` -> open at most one bounded fusion candidate
+- frontier says `stop` -> record the stop decision and explicit reopen condition
+
+For a compact research-route rubric, read `references/research-route-criteria.md`.
+
+## User-input note
+
+Ask the user only when:
+
+- multiple options are all plausible
+- the choice depends on preference, cost, or scope
+- the missing information cannot be derived locally
+
+When asking, use a structured decision request with:
+
+- concise question
+- 1 to 3 concrete options
+- tradeoffs, including the main pros and cons for each option
+- recommended option first
+- explicit reply format
+
+Keep decision requests narrow; if local evidence can resolve the route safely, do not hand routine ambiguity back to the user.
+
+## Memory note
+
+Write memory only when the decision created a reusable lesson or changed the authoritative resume point for later turns.
+
+When the authoritative resume point changes, write one compact checkpoint-style quest memory card.
+Mark it with `type:checkpoint-memory`.
+The card should include:
+
+- current active node
+- node history
+- what not to reopen by default
+- first files to read
+
+Use `references/checkpoint-memory-template.md`.

package/src/skills/decision/references/research-route-criteria.md

@@ -1,30 +1,30 @@
 # Research Route Criteria
 
-Use this reference when choosing among candidate branches, idea packages, or experiment groups.
+Use this reference when choosing among candidate branches, idea packages, experiment groups, or paper-facing routes.
 
 ## Core question
 
-What exact insufficiency are we trying to resolve?
+What exact insufficiency are we trying to resolve now?
 
-Do not choose a route only because it sounds sophisticated.
+Do not choose a route only because it sounds sophisticated or because it gives the illusion of motion.
 
 ## Preferred route profile
 
 Prefer routes that:
 
-- attack a real bottleneck
+- attack a real bottleneck rather than a vague hope
 - stay compatible with the existing architecture when possible
 - are implementable with bounded risk
 - can produce interpretable evidence
-- are defensible in later writing
+- are defensible in later writing, review, or rebuttal
 
-## Common tradeoffs to name explicitly
+## Tradeoffs to name explicitly
 
 - novelty vs feasibility
-- elegance vs brute-force scaling
 - expected gain vs verification cost
 - architectural fit vs rewrite burden
 - immediate progress vs long-term research value
+- elegant mechanism vs brute-force scaling
 
 ## Selection output
 
@@ -33,6 +33,5 @@ A good route decision records:
 - winner
 - strongest alternatives
 - criteria
-- implementation priority
 - expected learnings
 - why the rejected options lost