@researai/deepscientist 1.5.13 → 1.5.15

package/src/skills/baseline/references/baseline-checklist-template.md

@@ -1,7 +1,7 @@
 # Baseline Checklist Template
 
 Use this as a living checklist.
-Update it during reading, setup, smoke testing, real execution, verification, and route changes.
+Keep it short by default. For a fast path, complete the core checklist first and expand only if the route becomes complex or unstable.
 
 ## Identity
 
@@ -9,49 +9,38 @@ Update it during reading, setup, smoke testing, real execution, verification, an
 - route:
 - owner stage:
 
-## Analysis
+## Core
+
+- [ ] baseline object and route are explicit
+- [ ] dataset / split and metric contract are explicit enough to judge comparability
+- [ ] `PLAN.md` captures the command path, expected outputs, acceptance condition, and fallback
+- [ ] smoke decision is explicit:
+  - skipped for a justified reason, or run once with outputs checked
+- [ ] real validation/run decision is explicit:
+  - skipped for a justified reason, or launched/read with durable evidence
+- [ ] expected result files and required metrics are checked
+- [ ] baseline is accepted, blocked, or waived with a durable note
+
+## Closeout
+
+- [ ] concise `1-2` sentence baseline summary written
+- [ ] next stage named explicitly
+
+## Optional Expansion
+
+Fill this only when the route becomes full-audit, repair-heavy, or publication-oriented.
 
 - [ ] paper source identified
 - [ ] repo source identified
 - [ ] paper read enough to restate the core method faithfully
 - [ ] repo read enough to identify the real entrypoints
-- [ ] dataset / split contract confirmed
-- [ ] metric contract confirmed
 - [ ] main files to inspect or modify listed
-- [ ] risks and fallbacks written into `PLAN.md`
-
-## Setup
-
 - [ ] working directory confirmed
 - [ ] environment route chosen
 - [ ] key dependencies checked
 - [ ] model / data download path confirmed
 - [ ] fallback source recorded for critical downloads
-
-## Smoke Test
-
-- [ ] smoke command written in `PLAN.md`
-- [ ] smoke command executed
-- [ ] smoke outputs verified
-- [ ] smoke failure handled or route revised
-
-## Main Run
-
-- [ ] real command written in `PLAN.md`
-- [ ] real run launched with durable logging
 - [ ] monitoring cadence started
 - [ ] health signals confirmed
 - [ ] any execution deviation reflected back into `PLAN.md`
-
-## Verification
-
-- [ ] expected result files exist
-- [ ] metric keys are complete
-- [ ] baseline is comparable to the intended contract
 - [ ] verification note written
-- [ ] baseline accepted or explicitly blocked / waived
-
-## Closeout
-
-- [ ] concise `1-2` sentence baseline summary written
-- [ ] next stage named explicitly

package/src/skills/baseline/references/baseline-plan-template.md

@@ -1,9 +1,10 @@
 # Baseline Plan Template
 
 Use this when the `baseline` stage becomes concrete enough to act.
-Keep it short when the route is simple, but do not skip the sections that affect reproducibility, code touchpoints, or fallback handling.
+Keep it short when the route is simple. For fast-path attach/import/prebound validation, a one-screen plan is enough if it preserves the route, command path, outputs, acceptance condition, and fallback.
+Expand the optional sections only when the route is ambiguous, code-touching, broken, multi-variant, or intended for reuse beyond the current quest.
 
-## 1. Objective
+## 1. Core Contract
 
 - quest goal:
 - user's core requirements:
@@ -12,80 +13,63 @@ Keep it short when the route is simple, but do not skip the sections that affect
   - attach / import / reproduce / repair
 - baseline id:
 - variant id:
-
-## 2. Source Package
-
 - source paper:
 - source repo:
-- fallback repo or mirror:
 - source commit / version / tag:
 - task:
 - dataset / split:
 - metric contract:
+- expected command path:
+- expected outputs:
+- acceptance condition:
+- cheapest fallback:
 
-## 3. Paper And Repo Reading Notes
-
-- paper summary in `1-3` bullets:
-- repo summary in `1-3` bullets:
-- what the baseline actually does:
-- what the likely bottlenecks or brittle points are:
-- what still needs verification:
-
-## 4. Code Touchpoints
-
-List the main files or modules that matter before you change anything substantial.
-
-| Path | Role | Why it matters now | Expected action | Notes |
-|---|---|---|---|---|
-| | | | inspect / modify / leave alone | |
-
-## 5. Environment And Asset Plan
+## 2. Execution Path
 
 - working directory:
 - environment plan:
 - required downloads:
-- checkpoints / models:
 - hardware assumptions:
-- likely external blockers:
-
-Fallbacks and contingency options:
-
-- if Hugging Face is slow, blocked, or rate-limited:
-  - try ModelScope, official mirrors, quest-local caches, or manually staged files
-- if the official repo is unavailable:
-  - use a verified mirror and record the exact provenance
-- if the full run is too expensive:
-  - define the smoke-test path and the cheapest comparable reduced pilot
+- smoke test needed:
+  - yes / no
+- smoke command:
+- main validation or run command:
+- expected runtime / budget:
+- durable log path:
+- verification targets:
+- fastest failure signal:
 
-## 6. Execution Strategy
+## 3. Risks And Revision
 
-### Smoke Test
+- main risks:
+- when to escalate from fast path to full audit:
+- revision note:
 
-- command:
-- purpose:
-- expected outputs:
-- fastest failure signal:
+## 4. Optional Expansion
 
-### Main Run
+Fill this only when the route is no longer simple.
 
-- command:
-- expected outputs:
-- expected runtime / budget:
-- durable log path:
+- fallback repo or mirror:
+- checkpoints / models:
+- likely external blockers:
 - safe efficiency levers to try first:
-
-### Monitoring And Sleep Rules
-
-- first checks:
-  - `60s`
-  - `120s`
-  - `300s`
-  - `600s`
-  - `1800s`
 - health signals that justify continued monitoring rather than intervention:
 - conditions that require plan revision or kill-and-relaunch:
+- paper summary in `1-3` bullets:
+- repo summary in `1-3` bullets:
+- what the baseline actually does:
+- what the likely bottlenecks or brittle points are:
+- what still needs verification:
+
+## 5. Optional Code Touchpoints
+
+List the main files or modules only when you expect real inspection or edits.
+
+| Path | Role | Why it matters now | Expected action | Notes |
+|---|---|---|---|---|
+| | | | inspect / modify / leave alone | |
 
-## 7. Verification Plan
+## 6. Optional Verification Plan
 
 - required result files:
 - required metric keys:
@@ -93,12 +77,12 @@ Fallbacks and contingency options:
 - acceptance condition:
 - downgrade / blocked condition:
 
-## 8. Checklist Link
+## 7. Checklist Link
 
 - checklist path:
 - which item should move next:
 
-## 9. Revision Log
+## 8. Revision Log
 
 | Time | What changed | Why it changed | Impact on execution |
 |---|---|---|---|

package/src/skills/decision/SKILL.md

@@ -84,12 +84,14 @@ 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(kind='decision', action='iterate', ...)`
+- 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', ...)`
@@ -104,6 +106,7 @@ If the chosen action is baseline reuse, the decision is not complete until one o
 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.
@@ -121,6 +124,12 @@ Make decisions from durable evidence:
 
 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
@@ -249,6 +258,14 @@ When recording the decision, make explicit:
 - which existing evidence was decisive
 - what residual risk remains after the choice
 
+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
@@ -326,7 +343,7 @@ When asking, use a structured decision request with:
 
 ### 6. Record the decision durably
 
-Use `artifact.record(kind='decision', ...)` for the final decision.
+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.

package/src/skills/experiment/SKILL.md

@@ -39,7 +39,9 @@ Use this skill for the main evidence-producing runs of the quest.
 - If the runtime starts an auto-continue turn with no new user message, continue from the current run state, logs, artifacts, and active requirements instead of replaying the previous user turn.
 - Progress message templates are references only. Adapt to the actual context and vary wording so messages feel human, respectful, and non-robotic.
 - If a threaded user reply arrives, interpret it relative to the latest experiment progress update before assuming the task changed completely.
+- Hard execution rule: every terminal command in this stage must go through `bash_exec`; do not use any other terminal path for smoke tests, real runs, Git, Python, package-manager, or file-inspection commands.
 - Prefer `bash_exec` for experiment commands so each run gets a durable session id, quest-local log folder, and later `read/list/kill` control.
+- For meaningful long-running runs, include the estimated next reply time or next check-in window whenever it is defensible.
 
 ## Stage purpose
 
@@ -64,6 +66,9 @@ Use `references/evidence-ladder.md` when deciding whether the current package is
 Completing one main run is not quest completion.
 After reporting the run, keep moving to iterate, analyze, write, or finalize unless a genuine blocking decision remains.
 
+When the quest is algorithm-first, treat `experiment` as the execution surface of `optimize`, not as the terminal goal of the workflow.
+After a measured result, the default next move is frontier review and optimize-side route selection rather than paper packaging.
+
 ## Quick workflow
 
 Treat this as the short run-order summary. The detailed run contract, execution rules, and recording rules remain in `Workflow`.
@@ -90,6 +95,7 @@ Treat this as the short run-order summary. The detailed run contract, execution
 - After each `artifact.record_main_experiment(...)`, route from the measured result:
   - if paper mode is enabled, decide whether to strengthen evidence, analyze, or write
   - if paper mode is disabled, prefer iterate / revise-idea / branch over default writing
+- In algorithm-first work, after each main run, return to `optimize` or `decision` for frontier review before launching another large run.
 
 ## Experiment mental guardrails
 
@@ -429,8 +435,8 @@ For commands that may run longer than a few minutes:
   - if you only need wall-clock waiting between checks, use `bash_exec(command='sleep N', mode='await', timeout_seconds=N+buffer, ...)`
   - keep a real buffer on that sleep timeout; do not set `timeout_seconds` exactly equal to `N`
   - if you are waiting on an already running managed session, prefer `bash_exec(mode='await', id=..., timeout_seconds=...)` instead of starting a new sleep command
-- after every completed sleep / await cycle, inspect logs and send `artifact.interact(kind='progress', ...)` with the latest real status, latest evidence, the next checkpoint, and the estimated next reply time
-- after the first meaningful signal and then at real checkpoints (e.g., completion, or roughly every ~30 minutes if still running), keep those progress updates going rather than waiting silently
+- after every completed sleep / await cycle, inspect logs first; only send `artifact.interact(kind='progress', ...)` when the user-visible state, frontier, blocker status, or ETA materially changed
+- after the first meaningful signal and then at real checkpoints (e.g., completion, recovery, blocker, or a materially widened comparable surface), keep those progress updates going rather than waiting silently
 - if the run is clearly invalid, wedged, or superseded, stop it with `bash_exec(mode='kill', id=..., wait=true, timeout_seconds=...)`; if it must die immediately, add `force=true`, record the reason, fix the issue, and relaunch cleanly
 - do not report completion until logs and output files both confirm completion
 

package/src/skills/finalize/SKILL.md

@@ -11,10 +11,13 @@ Use this skill to close or pause a quest responsibly.
 
 - 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.
+- Do not emit another finalize progress update when the user-visible state is unchanged.
 - If the runtime starts an auto-continue turn with no new user message, keep finalizing from the durable quest state and active requirements instead of replaying the previous user turn.
 - If a threaded user reply arrives, interpret it relative to the latest finalize progress update before assuming the task changed completely.
 - When finalize reaches a real closure state, pause-ready packet, or route-back decision, send one threaded `artifact.interact(kind='milestone', ...)` update that names the recommendation, why it is the right call, and any reopen condition that still matters.
 - True quest completion still requires explicit user approval through the runtime completion flow before calling `artifact.complete_quest(...)`.
+- Rechecking that the same bundle files still exist, or re-aligning status surfaces without changing the closure judgment, does not by itself count as a fresh milestone.
+- Hard execution rule: if this stage needs terminal work such as Git inspection, packaging checks, document builds, or file inspection, every such command must go through `bash_exec`.
 
 ## Stage purpose
 
@@ -54,8 +57,19 @@ Before finalizing, gather:
 - latest quest documents
 - latest review / proofing / submission state when a paper bundle exists
 - the paper bundle manifest and its referenced paths when the quest has a paper-like deliverable
+- the paper evidence ledger and selected-outline section statuses when the quest has a paper-like deliverable
 
 If finalization reveals that the quest is still too uncertain, route back through `decision` rather than forcing closure.
+For paper-like deliverables, do not finalize while any of these remain true:
+
+- required main-text outline items are still unresolved
+- completed analysis remains unmapped into the paper contract
+- the active paper line still reports open supplementary work that is expected to block the manuscript
+
+If the current paper-state blocker is not obvious from the existing files, call `artifact.get_paper_contract_health(detail='full')` before deciding whether finalize is legitimate.
+If the active quest/runtime state is unclear after restart or long pause, call `artifact.get_quest_state(detail='summary')` first.
+If the exact latest `SUMMARY.md`, `status.md`, or active user requirement wording matters for closure, call `artifact.read_quest_documents(...)`.
+If earlier user/assistant continuity matters for whether the quest should really stop, call `artifact.get_conversation_context(...)` instead of guessing from prompt context alone.
 
 ## Truth sources
 
@@ -90,6 +104,7 @@ The finalize stage should usually leave behind:
 If the quest produced a paper-style bundle, finalization should also check that the writing stage left behind enough closure evidence, such as:
 
 - selected outline and outline selection records
+- evidence ledger records and section-level result tables
 - review output
 - proofing output
 - submission or packaging checklist
@@ -113,12 +128,14 @@ Say clearly what exists and why it matters. Name concrete paths or artifact ids
 When a paper bundle exists, verify the manifest inventory explicitly, including:
 
 - `paper/paper_bundle_manifest.json`
+- `paper/evidence_ledger.json`
 - the recorded `paper_branch` and source evidence branch / run fields in that manifest
 - referenced `outline_path`
 - referenced `draft_path`
 - referenced `writing_plan_path`
 - referenced `references_path`
 - referenced `claim_evidence_map_path`
+- referenced `evidence_ledger_path`
 - referenced `baseline_inventory_path`
 - referenced `compile_report_path`
 - referenced `pdf_path`
@@ -243,6 +260,7 @@ Weak finalization:
 - leaves no clear recommendation
 - claims “done” without showing what is actually done
 - drops the package or file inventory needed for resumption
+- ignores unmapped completed analysis that never entered the paper contract
 
 ## Memory rules
 

package/src/skills/idea/SKILL.md

@@ -7,6 +7,10 @@ description: Use when a quest needs concrete hypotheses, limitation analysis, ca
 
 Use this skill to turn the current baseline and problem frame into concrete, literature-grounded, testable directions.
 
+When `startup_contract.need_research_paper = false` and the quest already has a concrete optimization handle, `idea` may stop after selecting or seeding a direction and then hand off into `optimize` instead of insisting on the full paper-oriented ideation loop.
+In that algorithm-first case, `idea` should usually produce a small method-brief frontier and then defer candidate ranking, promotion, and bounded search to `optimize`.
+When doing that handoff, prefer the brief-shaping discipline later used by `optimize`: clarify the bottleneck and constraints, keep only a small differentiated `2-3` option slate, and hand off a recommended brief rather than a pile of loose intuitions.
+
 ## Interaction discipline
 
 - Follow the shared interaction contract injected by the system prompt.
@@ -39,6 +43,15 @@ The output must survive three checks at once:
 - feasibility in the current repo and resource budget
 - manuscript defensibility if the line later becomes a paper claim
 
+When the route already looks likely to become a paper-facing line, seed one lightweight structured outline candidate during idea work.
+Use `artifact.submit_paper_outline(mode='candidate', ...)` for that seed instead of leaving the future paper structure only in prose.
+Use `references/outline-seeding-example.md` for the minimum acceptable shape.
+The idea-stage outline candidate is not the full paper line yet, but it should already name the likely `research_questions`, `experimental_designs`, and the first section-level evidence needs that later supplementary slices must satisfy.
+Keep that seed minimal and executable: a small section skeleton plus expected evidence items is better than a long narrative outline with no concrete evidence hooks.
+If the current research head, strongest measured branch, or active runtime refs are unclear after resume, call `artifact.get_quest_state(detail='summary')` and `artifact.list_research_branches(...)` before choosing a foundation.
+If the current brief / plan / status wording matters for direction choice, call `artifact.read_quest_documents(...)`.
+If earlier user conversation materially changes the direction-selection target, call `artifact.get_conversation_context(...)` before locking the next idea.
+
 Finishing one idea deliverable is not quest completion.
 After reporting a completed idea package, continue into the next justified stage unless a real blocking decision is still unresolved.
 
@@ -106,6 +119,11 @@ Break ties primarily through careful reasoning over:
 - Do not write, promote, or submit a final idea until the durable survey covers at least `5` and usually `5-10` task-modeling-related, mechanism-relevant, or otherwise directly usable papers.
 - Treat that literature floor as a hard gate, not a suggestion.
   If the direct task-modeling neighborhood truly contains fewer than `5` usable papers, record that evidence explicitly and fill the remaining slots with the closest adjacent papers whose mechanism can be translated into the current task and codebase.
+- Algorithm-first exception:
+  - when `startup_contract.need_research_paper = false` and a concrete optimization handle already exists, you may stop after a memory sweep plus a small targeted paper check instead of satisfying the full `5-10` paper floor
+  - use that exception only when the immediate goal is method-brief selection for `optimize`, not paper-level novelty claims
+  - if you use the exception, say explicitly that the output is an optimization brief frontier rather than a paper-ready idea package
+  - still shape that frontier deliberately: clarify the bottleneck and comparability boundary first, keep a differentiated `2-3` candidate slate, and explain why one brief is recommended now
 - Every fresh idea build or idea-refinement pass must begin with:
   - a memory sweep, and
   - an external literature sweep.
@@ -133,12 +151,19 @@ Break ties primarily through careful reasoning over:
 - Unless strong durable evidence already narrows the route to one obvious serious option, run one bounded divergent pass that produces a small but meaningfully varied slate, usually `6-12` raw ideas before collapsing to a serious frontier that is usually `2-3` and at most `5`.
 - If all surviving candidates belong to the same mechanism family, widen once with at least two new ideation lenses before converging.
 - Keep structurally coherent rejected ideas in a parking-lot or rejected-candidate section so they can be recombined later if needed.
+- In algorithm-first work, `idea` should usually produce direction families, not a large within-family variant swarm.
+- Treat within-family micro-variants as `optimize` brief work unless the mechanism family itself is still unresolved.
 - Every serious candidate must answer `why now?` or `what changed?`, not just `what is the mechanism?`
 - Every selected idea must survive a two-sentence pitch and strongest-objection check before promotion.
 - Do not promote a direction unless you can explain:
   - what limitation it targets
   - why prior methods do not already solve it
   - what evidence would later be needed to defend the claim
+- When the likely next route is a paper-facing main experiment plus analysis package, do not stop at prose-only idea notes; seed the likely `research_questions`, `experimental_designs`, and per-section evidence needs in the outline candidate.
+- If the likely route already has a clear paper-facing structure, seed the future paper line early:
+  - identify the likely main-text sections
+  - identify which sections will need supplementary evidence rather than only the main run
+  - identify the concrete evidence items that must later be maintained in the paper line's outline folder or compiled outline contract
 - If the idea is not novel but still worth doing, state that honestly as:
   - replication value
   - transfer-to-new-setting value
@@ -182,6 +207,51 @@ In practice:
 
 Do not skip the `scout` pass just because the quest is already in the `idea` stage.
 
+## Direction-shaping protocol
+
+Use `references/idea-thinking-flow.md` when the main need is better reasoning hygiene.
+Use `references/idea-generation-playbook.md` when the main need is to create a new idea slate and select one clear next research object.
+
+Default creation flow for a fresh idea pass:
+
+1. frame one concrete limitation
+2. separate symptom / mechanism hypothesis / consequence
+3. keep one main hypothesis plus `2-3` competing hypotheses
+4. name the primary lever bucket
+5. generate a bounded candidate slate from that framing
+6. record selected / deferred / rejected outcomes explicitly
+
+Set the frontier width with a validation-cost estimate before widening:
+
+- `fast-check`: the first objective validation loop is likely under about `20` minutes
+- `slow-check`: the first objective validation loop is likely over about `20` minutes or otherwise expensive in compute, queue time, or human delay
+
+For `fast-check` idea work:
+
+- allow a slightly wider serious slate when the candidates are meaningfully different
+- prefer candidates with cheap, orthogonal falsification paths
+- keep more alternatives alive into `optimize` because validation is cheaper than overthinking
+
+For `slow-check` idea work:
+
+- keep the serious slate tighter, usually `1-3`
+- demand a clearer bottleneck story and stronger evidence before adding another family
+- prefer the route with the best expected evidence-per-run, not the route with the most speculative upside
+- do not hand off a broad speculative slate just because it sounds interesting
+
+Do not start by shopping for modules to add.
+Do not let one attractive mechanism become the de facto framing before the limitation is pinned down.
+Do not let direction-family ideation collapse into within-family variant generation too early.
+
+In normal idea work, stop at the direction-family level:
+
+- select which mechanism families deserve serious consideration
+- identify the strongest one to carry forward
+- hand off within-family brief shaping to `optimize` when the quest is algorithm-first
+
+If the task still requires choosing among mechanism families, stay in `idea`.
+If the family is already chosen and the next need is branchless method-brief shaping, hand off to `optimize`.
+
 ## Truth sources
 
 Use:
@@ -1118,6 +1188,14 @@ When writing paper memory cards, include enough metadata to avoid redundant sear
 
 At the end of ideation, at least one part of the literature survey must be preserved in memory so a later idea pass can retrieve it directly instead of rebuilding the search from scratch.
 
+Every serious idea pass should also leave a durable outcome split:
+
+- one selected idea or selected direction family
+- any deferred but still plausible alternatives
+- any rejected alternatives with a one-line rejection reason
+
+Do not leave the rejected and deferred reasoning only in chat.
+
 Promote to global memory only when the lesson is reusable outside this quest.
 
 ## Artifact rules

package/src/skills/idea/references/idea-generation-playbook.md

@@ -0,0 +1,100 @@
+# Idea Generation Playbook
+
+Use this reference when the `idea` stage needs a concrete creation flow for producing a new idea slate.
+
+The goal is not a bag of clever mechanisms.
+The goal is one clear next research object plus a durable record of what was deferred or rejected.
+
+## 1. Start from one limitation card
+
+Write one limitation card before generating ideas:
+
+- observed symptom
+- condition where it appears
+- why it matters for the target metric or claim
+- strongest evidence that this is a real pattern
+
+If the limitation card is weak, do not widen into ideation yet.
+
+## 2. Split the problem into three layers
+
+For the active limitation, separate:
+
+- symptom
+- mechanism hypothesis
+- consequence
+
+Do not skip this split.
+It prevents solution-shopping from becoming the hidden driver.
+
+## 3. Keep competing hypotheses alive
+
+Before selecting mechanisms, record:
+
+- one main hypothesis
+- `2-3` competing hypotheses
+
+If there is only one hypothesis, the idea pass is usually too collapsed.
+
+## 4. Name the lever bucket
+
+Choose the primary lever bucket explicitly:
+
+- data
+- model
+- objective
+- optimization or training dynamics
+- inference
+- evaluation protocol
+- infrastructure
+
+If the lever bucket is unclear, the idea is usually still too fuzzy.
+
+## 5. Generate direction families, not micro-variants
+
+Create a bounded slate of direction families.
+Default target:
+
+- `6-12` raw ideas in one bounded divergent pass
+- collapse to `2-3` serious candidates and at most `5`
+
+Prefer family-level differences over small parameter or implementation variations.
+If several candidates are really the same family with minor tweaks, merge them.
+
+For each serious candidate, record:
+
+- limitation targeted
+- mechanism family
+- why now
+- strongest prior-work overlap
+- expected evidence burden
+- likely falsification path
+
+## 6. Select one and ledger the rest
+
+At the end of the pass, produce three durable buckets:
+
+- selected
+- deferred
+- rejected
+
+For deferred ideas, write why they remain plausible but are not first.
+For rejected ideas, write one-line rejection reasons such as:
+
+- redundant with closer prior work
+- too confounded to test cleanly
+- weak value if positive
+- too broad for current compute or codebase
+- lower priority than the selected route
+
+## 7. Exit criterion
+
+The pass is complete only when the output contains:
+
+- one selected idea or selected direction family
+- one falsifiable claim
+- one minimal experiment concept
+- one abandonment condition
+- deferred and rejected rationale recorded durably
+
+If the result is still a bag of possibilities, stay in `idea`.