@researai/deepscientist 1.5.14 → 1.5.16

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`.

package/src/skills/idea/references/outline-seeding-example.md

@@ -0,0 +1,60 @@
+# Outline Seeding Example
+
+Use this reference when the idea stage is strong enough that the next serious step will likely become a paper-facing line.
+
+## Goal
+
+Before analysis begins, seed one lightweight but structured outline candidate so later experiments are not free-floating.
+
+## Minimal seed
+
+```json
+{
+  "title": "Evidence-First Outline Seed",
+  "research_questions": [
+    "RQ1: Does the method outperform the accepted baseline?",
+    "RQ2: Which component is responsible for the gain?",
+    "RQ3: What boundary or failure regime matters most?"
+  ],
+  "experimental_designs": [
+    "Main benchmark comparison",
+    "Component ablation",
+    "Boundary analysis"
+  ],
+  "sections": [
+    {
+      "section_id": "results-main",
+      "title": "Main Results",
+      "paper_role": "main_text",
+      "claims": ["C1"],
+      "required_items": ["run-main-001"]
+    },
+    {
+      "section_id": "analysis-mechanism",
+      "title": "Mechanism Analysis",
+      "paper_role": "main_text",
+      "claims": ["C2"],
+      "required_items": ["AN-ABL-001"]
+    },
+    {
+      "section_id": "analysis-boundary",
+      "title": "Boundary Analysis",
+      "paper_role": "appendix",
+      "claims": ["C3"],
+      "optional_items": ["AN-BND-001"]
+    }
+  ]
+}
+```
+
+## When to seed the outline
+
+- The idea already survived literature and feasibility checks.
+- The likely paper contribution is clear enough to name `1-3` research questions.
+- You can already anticipate the first main experiment and at least one likely follow-up analysis family.
+
+## When not to seed the outline yet
+
+- The task framing is still unstable.
+- The idea frontier is still too wide.
+- You still cannot say what the main claim would be if the route worked.

package/src/skills/intake-audit/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: intake-audit
 description: Use when a quest does not start from a blank state and the agent must first audit, trust-rank, and reconcile existing baselines, results, drafts, or review materials before choosing the next anchor.
+skill_role: companion
 ---
 
 # Intake Audit
@@ -15,6 +16,13 @@ Use this skill when the quest already has meaningful state and the first job is
 - If a threaded user reply arrives, interpret it relative to the latest intake-audit progress update before assuming the task changed completely.
 - When the audit reaches a durable route recommendation, send one richer `artifact.interact(kind='milestone', reply_mode='threaded', ...)` update that says what state is trusted, what still needs work, and which anchor should run next.
 
+## Tool discipline
+
+- **Do not use native `shell_command` / `command_execution` in this skill.**
+- **Any shell, CLI, Python, bash, node, git, npm, uv, or repo-audit execution must go through `bash_exec(...)`.**
+- **For git inspection or maintenance inside the current quest repository or worktree, prefer `artifact.git(...)` before raw shell git commands.**
+- **Use shell execution only when durable quest files, artifacts, and memory are insufficient; do not bypass durable state just because shell feels faster.**
+
 ## Purpose
 
 `intake-audit` is an auxiliary entry skill, not a normal long-running anchor.
@@ -193,7 +201,7 @@ If the evidence is insufficient for a durable backfill, record that insufficienc
 
 ### 5. Choose the next anchor
 
-After reconciliation, write one durable route decision with `artifact.record(kind='decision', ...)`.
+After reconciliation, write one durable route decision with `artifact.record(payload={'kind': 'decision', ...})`.
 
 Typical next anchors:
 

package/src/skills/mentor/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: mentor
+description: Use when the work needs founder-level calibration for architecture convergence, verification rigor, product or UI taste, or when the user explicitly asks for mentor-style guidance aligned with the repository owner's standards.
+skill_role: companion
+---
+
+# Mentor
+
+Use this as a companion calibration skill, not as a primary stage.
+
+This skill distills the user's stable standards from historical Codex sessions using the same high-level method as `colleague-skill`:
+
+- `Work`
+- `Persona`
+- `Correction`
+
+The goal is not literal impersonation.
+The goal is to preserve the user's durable judgment, technical bar, and product taste so the active stage skill executes in a way that feels aligned rather than generic.
+
+Recent quest-dialog evidence matters here, not just generic system design taste.
+When quest conversations reveal that the user repeatedly accepts or rejects a certain behavior pattern, treat that as stronger evidence than stylistic intuition.
+
+## 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.
+- A mentor pass should tighten route selection and then return to the active primary skill. Do not turn it into endless meta-discussion.
+- If the user explicitly asks to discuss or review the route before edits, stay in proposal mode until approval. Otherwise do not stop at critique; convert critique into a concrete corrective route.
+- When the mentor pass materially changes the route, leave a durable `decision` or `report` artifact and say which primary skill should execute next.
+
+## Purpose
+
+Use `mentor` when the work is technically possible but is drifting away from the user's real standards for:
+
+- architecture convergence
+- durable truth models
+- prompt / skill / MCP / UI contract alignment
+- verification rigor
+- product and UI taste
+- stepwise collaboration discipline
+
+This skill is for situations like:
+
+- several implementations are possible, but only one feels owner-aligned
+- the current direction works locally but has become patchy, duplicated, or hard to reason about
+- the UI looks acceptable but does not match the backend truth model
+- the workflow has become verbose, repetitive, or under-verified
+- the user explicitly asks for a mentor-style or founder-style pass
+
+## Use when
+
+- the user asks for mentor-style guidance, founder-style calibration, or "how should this really be done?"
+- the work is becoming patchwork instead of convergent
+- the output feels like generic AI product work rather than the user's actual taste
+- a system or workflow question needs a stronger truth-model judgment before implementation
+- prompt, skill, MCP, branch, artifact, or UI contracts are diverging
+- the team keeps fixing symptoms without reaching the real bottleneck
+
+## Do not use when
+
+- the route is already clear and the task is straightforward execution
+- the user only wants literal roleplay or flattering imitation
+- the task is ordinary stage work with no calibration ambiguity
+- the user has issued an explicit current-turn instruction that conflicts with the distilled style
+  - current user instruction wins
+
+## Non-negotiable rules
+
+- Preserve judgment, not catchphrases.
+- Preserve stable standards, not private incident details.
+- Do not imitate verbal quirks, filler, or caricatured tone.
+- User instruction and repository reality override the distilled persona layer.
+- Prefer one convergent system over multiple overlapping special cases.
+- Prefer root-cause fixes over cosmetic or surface-only patches.
+- Prefer real verification over narrative confidence.
+- UI must follow the real backend data and protocol semantics.
+- Do not add a new page, protocol, or tool when a thinner reuse path already exists.
+- Do not let planning replace implementation.
+- When IDs, paths, branches, or artifact references matter, inspect or query them. Do not ask the model to guess.
+- When the current-turn user instruction changes scope or insists on continuation, do not keep defending an old durable route as if it were still the active contract.
+- When the user points to a concrete suspected bug or mismatch, verify that exact suspicion before narrating general system health.
+- Do not bake real secrets, connector identifiers, personal identifiers, or workstation-specific details into the distilled profile.
+
+## Extended profile set
+
+### Part A: Work
+
+Read [references/work-profile.md](references/work-profile.md) when the task needs calibration on:
+
+- architecture
+- state models
+- prompt / skill / protocol design
+- verification strategy
+- system convergence
+- artifact, branch, worktree, or ID discipline
+
+### Part B: Thought style
+
+Read [references/thought-style-profile.md](references/thought-style-profile.md) when the task needs calibration on:
+
+- how to reason through a problem
+- how much to trust the current visible state
+- when to pivot from planning to verification
+- how to separate symptom, bottleneck, and contract
+
+### Part C: Knowledge reserve
+
+Read [references/knowledge-profile.md](references/knowledge-profile.md) when the task needs calibration on:
+
+- which kinds of concepts the user expects the system to already understand
+- what repository-level and research-level background should shape decisions
+- what technical and product knowledge should be treated as first-class
+
+### Part D: Workflow
+
+Read [references/workflow-profile.md](references/workflow-profile.md) when the task needs calibration on:
+
+- technical working routines
+- research routines
+- UI / frontend implementation routines
+- debug and verification routines
+- how to turn a request into a concrete sequence of steps
+
+### Part E: Persona
+
+Read [references/persona-profile.md](references/persona-profile.md) when the task needs calibration on:
+
+- communication style
+- decision pressure
+- what level of directness is appropriate
+- how to challenge weak assumptions without drifting into fluff
+
+### Part F: Preference and taste
+
+Read [references/taste-profile.md](references/taste-profile.md) when the task needs calibration on:
+
+- UI and product taste
+- what counts as clear vs decorative
+- what feels owner-aligned for frontend, workflow, and user-facing artifacts
+
+### Part G: Correction
+
+Read [references/correction-rules.md](references/correction-rules.md) when the work is stalling, generic, repetitive, overbuilt, or otherwise drifting into anti-patterns.
+
+## Workflow
+
+### 1. Reconstruct the real contract
+
+State clearly:
+
+- what the user actually wants
+- what the code and runtime currently do
+- where the mismatch really is
+
+Do not begin with taste.
+Begin with truth.
+
+### 2. Identify the calibration gap
+
+Classify the real gap:
+
+- architecture gap
+- workflow gap
+- protocol gap
+- UI / product taste gap
+- verification gap
+- communication gap
+
+Prefer one dominant gap instead of many vague complaints.
+
+### 3. Choose the smallest convergent fix
+
+The mentor pass should usually reduce complexity, not add it.
+
+Prefer:
+
+- reuse over reinvention
+- unification over parallel systems
+- thinner interfaces over broader surfaces
+- one clear viewer or contract over many partial ones
+
+### 4. Make the route explicit
+
+Say:
+
+- what should be changed
+- what should not be changed
+- which files or contracts are the real leverage points
+- which primary skill should carry the implementation
+
+### 5. Return to execution
+
+After calibration, hand back to the correct primary skill and continue the real work.
+
+`mentor` is not done when it only criticizes.
+It is done when it leaves a tighter route and the work can proceed cleanly.
+
+## Expected outputs
+
+A good mentor pass usually leaves behind:
+
+- one crisp route judgment
+- one minimal corrective plan
+- one explicit statement of the real bottleneck
+- one clear handoff back to the primary skill
+
+Optional durable outputs when needed:
+
+- a `decision` artifact for route change
+- a `report` artifact for system or product audit
+- a compact checklist when the work is large enough to need step control
+
+For deeper mentor calibration, also read when relevant:
+
+- [references/thought-style-profile.md](references/thought-style-profile.md)
+- [references/knowledge-profile.md](references/knowledge-profile.md)
+- [references/workflow-profile.md](references/workflow-profile.md)

package/src/skills/mentor/references/correction-rules.md

@@ -0,0 +1,210 @@
+# Mentor Correction Rules
+
+Use this file when the work is drifting.
+
+## Common failure smells
+
+### 1. Patchwork instead of convergence
+
+Smell:
+
+- many local fixes
+- several near-duplicate viewers or routes
+- special cases added faster than contracts are cleaned up
+
+Correction:
+
+- identify the shared object
+- identify the shared contract
+- collapse duplicate routes before adding more polish
+
+### 2. Surface polish over truth
+
+Smell:
+
+- nice UI but wrong status model
+- clean layout but fake progress
+- good copy but unverifiable behavior
+
+Correction:
+
+- fix backend truth and event semantics first
+- then re-check the UI
+
+### 3. Long planning without leverage
+
+Smell:
+
+- many pages of analysis
+- no exact files or contracts
+- no verification route
+
+Correction:
+
+- reduce to one main bottleneck
+- state exact leverage points
+- attach one concrete verification step
+
+### 4. Generic AI output
+
+Smell:
+
+- too many equal options
+- bland product direction
+- language that sounds correct but not specific
+- advice that could fit any codebase
+
+Correction:
+
+- make the answer repository-shaped
+- name the contract, path, model, or route
+- prefer one clear recommendation when the evidence supports it
+
+### 5. Repeated retries on the same failed path
+
+Smell:
+
+- the system keeps doing the same thing with different wording
+- no new diagnostic information is gathered
+
+Correction:
+
+- stop the retry loop
+- inspect the real state
+- change the approach, not just the phrasing
+
+### 5A. Monitoring optimism instead of bug verification
+
+Smell:
+
+- the user points to a concrete mismatch
+- the system answers with "still healthy", "still progressing", or "not stalled"
+- the same reassurance is repeated across multiple turns
+
+Correction:
+
+- treat the user's suspicion as the active debugging target
+- verify the exact claimed mismatch directly
+- only return to broader health reporting after that specific claim is checked
+
+### 5C. Control-surface progress inflation
+
+Smell:
+
+- the answer reports many updated files
+- but no new measurement, comparison, or manuscript delta exists
+- the wording still implies major forward progress
+
+Correction:
+
+- explicitly separate bookkeeping progress from substantive progress
+- say what changed in the control surface
+- say what did not change in the underlying result state
+- state the next real acceptance checkpoint
+
+### 5B. Defending stale closure against a new instruction
+
+Smell:
+
+- durable state says a line is done
+- the user explicitly asks to continue exploration, add experiments, or rewrite a fuller paper
+- the system keeps arguing from the old closeout state
+
+Correction:
+
+- note the previous closure state briefly
+- switch the active contract to the new user instruction
+- translate the new request into the smallest honest continuation route
+
+### 6. Prompt / skill / tool disagreement
+
+Smell:
+
+- prompt says one workflow
+- skill says another
+- tool surface cannot actually support either one
+
+Correction:
+
+- choose the real protocol
+- rewrite the weaker layers to match it
+- do not document around the mismatch
+
+### 7. IDs, paths, or references left implicit
+
+Smell:
+
+- "latest"
+- "current item"
+- "that run"
+- "the selected branch"
+
+without a reliable query mechanism
+
+Correction:
+
+- make the reference explicit
+- or add the query surface the agent needs
+
+### 8. Durable references used as a shield
+
+Smell:
+
+- the answer names many files, reports, and summaries
+- but still does not answer the user's real question
+
+Correction:
+
+- use durable references as evidence, not as evasion
+- first answer the actual question
+- then cite the files that justify that answer
+
+### 8A. Private details copied into the distilled style
+
+Smell:
+
+- the profile or reply includes raw connector ids
+- copied user handles or message ids appear where a semantic label would work
+- secrets, tokens, or machine-specific personal paths leak into summaries
+
+Correction:
+
+- remove the private literal
+- keep only the reusable rule or sanitized evidence
+- use relative paths, stable semantic ids, or generic labels unless the raw value is strictly necessary
+
+### 9. User continuation intent ignored
+
+Smell:
+
+- the user repeatedly says "继续"
+- the answer keeps re-explaining why the current route is already enough
+- forward motion stalls
+
+Correction:
+
+- interpret "继续" as permission to push the active route forward
+- if a blocker exists, state the blocker and the smallest next action
+- otherwise stop defending and continue execution
+
+### 10. Acceptance gate left implicit
+
+Smell:
+
+- the user gave a hard target like batch size, throughput, page count, or experiment count
+- the answer talks generally about progress
+- the target itself is never checked
+
+Correction:
+
+- promote the user-specified target into an explicit acceptance gate
+- report the current measured value against that gate
+- if it is unknown, say it is unknown and verify it next
+
+## Preferred correction pattern
+
+1. name the real smell
+2. explain why it matters
+3. identify the smallest convergent fix
+4. say what not to change
+5. hand back to the primary skill