@researai/deepscientist 1.5.16 → 1.6.0

package/src/skills/optimize/references/brief-shaping-playbook.md

@@ -0,0 +1,95 @@
+# Brief Shaping Playbook
+
+Use this reference when a candidate direction is still fuzzy and needs to become a structured, ranking-ready brief.
+
+This playbook borrows the useful part of product-style brainstorming without importing a full software-spec workflow.
+The goal is not a long design document.
+The goal is a compact candidate brief that is clear enough to compare, rank, and either submit as `submission_mode='candidate'` or reject.
+
+## 1. Clarify before widening
+
+Before generating more variants, resolve the minimum ambiguity around:
+
+- the concrete bottleneck
+- the evaluation or comparability boundary
+- the main hard constraint: data, metric, compute, latency, memory, interface, or training budget
+- the current incumbent or baseline that this brief must beat or complement
+
+If one unknown would materially change every candidate, clarify it first instead of generating a noisy slate.
+Prefer one question at a time when clarification is genuinely needed.
+If the answer is already available from durable state, use that instead of asking.
+
+## 2. Generate a small differentiated slate
+
+Default target: `2-3` serious approaches.
+
+The slate should usually include:
+
+- one incumbent-deepening refinement
+- one orthogonal mechanism
+- one broader shift candidate when justified
+
+Do not produce several renamed variants of the same mechanism family.
+If two variants differ only by parameter choice or patch detail, keep only the sharper one.
+
+For each candidate, write:
+
+- bottleneck
+- why_current_line_is_limited
+- mechanism
+- why_now
+- keep_unchanged
+- expected_gain
+- main_risks
+
+## 3. Compare on one shared surface
+
+Before recommending a winner, compare the serious candidates on the same dimensions:
+
+- expected upside
+- comparability safety
+- implementation surface
+- mechanism distinctness
+- failure risk
+- reason this route is better now than the nearby alternatives
+
+Do not let each candidate justify itself with a different scoring story.
+Use one comparison surface so ranking is auditable.
+
+## 4. Recommend exactly one lead brief
+
+After comparison, recommend one lead brief and explain:
+
+- why it is the best next move now
+- why the main alternatives are deferred instead of promoted
+- what evidence would quickly disconfirm the lead brief
+
+Do not say “all are promising” and promote everything.
+If the slate is still too close to call, return to widening once or narrow the slate further.
+
+## 5. Self-check before submission
+
+Before calling `artifact.submit_idea(..., submission_mode='candidate', ...)`, check:
+
+- Is the bottleneck concrete rather than generic?
+- Does `why_current_line_is_limited` explain a real gap instead of restating the mechanism?
+- Does `why_now` explain what changed in evidence, failure pattern, or frontier state?
+- Is the comparability boundary explicit?
+- Is the recommendation based on tradeoffs rather than implementation convenience?
+- Would the brief still make sense if handed to another agent with no chat context?
+
+If any answer is no, refine the brief before submission.
+
+## 6. Output shape
+
+A good final brief package is short and structured:
+
+1. brief title
+2. one-paragraph bottleneck and constraint summary
+3. a `2-3` candidate comparison table or bullet slate
+4. recommended brief with tradeoff summary
+5. self-check outcome
+6. fields ready for the method brief template
+
+Keep it compact.
+This is a shaping pass for optimization candidates, not a paper draft or engineering spec.

package/src/skills/optimize/references/candidate-board-template.md

@@ -0,0 +1,13 @@
+# CANDIDATE_BOARD.md
+
+| Candidate ID | Level | Parent | Strategy | Status | Expected Gain | Observed Result | Promote / Archive |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| cand-001 | brief | current-head | explore | proposed | Better tail accuracy | n/a | pending |
+| cand-002 | impl | cand-001 | exploit | smoke_passed | Faster convergence | smoke ok | consider promote |
+
+Notes:
+
+- `Level` should be `brief` or `implementation`
+- `Parent` may be a branch, idea id, run id, or candidate id
+- `Strategy` should usually be one of `explore`, `exploit`, `fusion`, `debug`
+- `Promote / Archive` should be a clear recommendation, not an empty placeholder

package/src/skills/optimize/references/candidate-ranking-template.md

@@ -0,0 +1,51 @@
+# Candidate Ranking Template
+
+## Candidate Set
+
+- Candidate IDs:
+- Ranking scope:
+- Comparison surface:
+
+## Criteria
+
+- expected information gain
+- feasibility in current repo
+- comparability against baseline
+- implementation surface
+- likely novelty or distinctiveness
+- risk of redundant overlap
+- incumbent-improvement potential
+- distinctness from other candidates
+- mechanism-family diversity
+- change-layer diversity
+
+## Ranked Candidates
+
+1. `candidate_id`
+   Score summary:
+   Why it ranks here:
+   Promote / hold / reject:
+
+2. `candidate_id`
+   Score summary:
+   Why it ranks here:
+   Promote / hold / reject:
+
+3. `candidate_id`
+   Score summary:
+   Why it ranks here:
+   Promote / hold / reject:
+
+## Winner Justification
+
+Why the selected candidate should become a durable line now.
+
+## Non-Winner Notes
+
+Why the other candidates were deferred, fused, or rejected.
+
+## Promotion Cap
+
+- how many candidates should be promoted now:
+- why more promotion would dilute the frontier:
+- same-family cap override justification:

package/src/skills/optimize/references/codegen-route-playbook.md

@@ -0,0 +1,50 @@
+# Codegen Route Playbook
+
+Choose the code-generation route deliberately.
+
+## Use brief-only
+
+Use no-code candidate briefs when:
+
+- the direction is still underspecified
+- multiple distinct directions still need ranking
+- a new line should not be promoted yet
+
+## Use stepwise generation
+
+Prefer stepwise generation when:
+
+- a new durable line is being implemented for the first time
+- the change spans data processing, model design, and training/evaluation
+- a modular decomposition will reduce large integrated errors
+- a plan -> refine -> implement sequence is safer than one monolithic edit
+
+## Use diff / patch generation
+
+Prefer diff / patch generation when:
+
+- a strong current implementation already exists
+- the current change is local enough to preserve most of the line
+- the task is improve, exploit, debug, or most fusion work
+- the desired change can be described as a bounded delta from the current solution
+
+## Use full rewrite
+
+Use a full rewrite only when:
+
+- the existing implementation is structurally broken
+- the desired architecture no longer matches the current codebase shape
+- diff patching would be more fragile than replacement
+
+Do not jump to a rewrite merely because one local patch failed.
+
+## Response shape
+
+For non-trivial codegen work, prefer this shape:
+
+1. short plan
+2. bounded implementation surface
+3. keep-unchanged contract
+4. validation step
+
+Do not go from a vague idea directly into a large patch with no intermediate plan.

package/src/skills/optimize/references/debug-response-template.md

@@ -0,0 +1,29 @@
+# Debug Response Template
+
+## Error
+
+What concrete error or failure occurred?
+
+## Retrieved Memory
+
+What similar failure pattern or repair lesson should be reused before changing code?
+
+## Root Cause
+
+What is the most likely underlying cause?
+
+## Minimal Fix
+
+What is the smallest plausible fix?
+
+## Keep Unchanged
+
+What parts of the line must remain unchanged for comparability and stability?
+
+## Next Check
+
+What bounded smoke or validation check should confirm the fix?
+
+## Archive Threshold
+
+What outcome would prove this candidate should be archived instead of debugged again?

package/src/skills/optimize/references/frontier-review-template.md

@@ -0,0 +1,32 @@
+# Frontier Review Template
+
+## Current Frontier
+
+- mode:
+- best branch:
+- best run:
+- stagnant branches:
+- candidate backlog:
+- fusion candidates:
+
+## Evidence Summary
+
+- strongest support:
+- strongest contradiction:
+- biggest unresolved risk:
+
+## Route Choice
+
+- explore / exploit / fusion / debug / stop:
+- why this is the best next move:
+
+## Active Optimize Submode
+
+- brief / rank / seed / loop / fusion / debug:
+- why this submode is dominant now:
+
+## Immediate Next Action
+
+- exact next step:
+- what result will trigger another frontier review:
+- what result would force a different mode:

package/src/skills/optimize/references/fusion-playbook.md

@@ -0,0 +1,36 @@
+# Fusion Playbook
+
+Use fusion only when:
+
+- at least two lines have real strengths
+- the strengths are complementary
+- one line alone is no longer improving fast enough
+
+Before fusion, write down:
+
+- source line A:
+  strongest mechanism:
+  strongest evidence:
+  main weakness:
+  what must survive the fusion:
+
+- source line B:
+  strongest mechanism:
+  strongest evidence:
+  main weakness:
+  what must survive the fusion:
+
+Then answer:
+
+- what exactly is being fused?
+- why does this combination address a real bottleneck?
+- why are the source strengths complementary rather than redundant?
+- what remains unchanged for comparability?
+- what evidence would prove the fusion was worth it?
+- what bounded first validation step should run before any broad rollout?
+
+Do not fuse:
+
+- two lines with the same mechanism under different names
+- two weak lines with no clear strengths
+- merely because multiple branches exist

package/src/skills/optimize/references/method-brief-template.md

@@ -0,0 +1,73 @@
+# Method Brief Template
+
+## Title
+
+One short line naming the candidate direction.
+
+## Bottleneck
+
+What concrete bottleneck or limitation does this target?
+
+## Why Current Line Is Limited
+
+Why is the current best line or baseline not already solving this?
+
+## Mechanism
+
+What specific intervention or design change is proposed?
+
+## Mechanism Family
+
+Name the family explicitly, for example `adapter`, `loss`, `architecture`, `augmentation`, `ensemble`, `retrieval`, `objective-shift`.
+
+## Change Layer
+
+One of:
+
+- `Tier1`: local optimization / training detail
+- `Tier2`: representation or component change
+- `Tier3`: paradigm or system-level shift
+
+## Source Lens
+
+Where did this candidate come from?
+
+- baseline_refinement
+- orthogonal_mechanism
+- failure_repair
+- cross_domain_transfer
+- objective_shift
+- search_widening
+
+## Keep Unchanged
+
+What must remain stable for comparability?
+
+## Expected Gain
+
+What evidence should improve if this works?
+
+## Implementation Surface
+
+- main files or modules likely involved:
+- likely change scope: local / moderate / broad
+
+## Risks
+
+- Main failure mode
+- Comparability risk
+- Implementation risk
+
+## Foundation
+
+- Source branch / run / baseline:
+- Why this foundation is the right starting point:
+
+## Promote Now
+
+- yes / no
+- why:
+
+## Next Target
+
+Usually `optimize` or `experiment`.