research-copilot 0.1.0

package/bin/cli.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for Research Copilot.
+ *
+ * Usage:
+ *   npx research-copilot            # Run directly
+ *   npm i -g research-copilot       # Install globally
+ *   research-copilot                # Then run anywhere
+ */
+
+import { spawn } from 'child_process'
+import { createRequire } from 'module'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import { existsSync } from 'fs'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const require = createRequire(import.meta.url)
+
+// Resolve the Electron binary from this package's node_modules
+let electronPath
+try {
+  electronPath = require('electron')
+} catch {
+  console.error(
+    'Error: Electron is not installed.\n' +
+    'Run: npm install\n'
+  )
+  process.exit(1)
+}
+
+// The app entry is at ../app/ (has package.json with "main" pointing to built output)
+const appDir = join(__dirname, '..', 'app')
+const mainEntry = join(appDir, 'out', 'main', 'index.mjs')
+
+if (!existsSync(mainEntry)) {
+  console.error(
+    'Error: App has not been built yet.\n' +
+    'Run: npm run build\n'
+  )
+  process.exit(1)
+}
+
+// Launch Electron with the app directory
+const child = spawn(String(electronPath), [appDir], {
+  stdio: 'inherit',
+  env: { ...process.env },
+})
+
+child.on('close', (code) => process.exit(code ?? 0))
+child.on('error', (err) => {
+  console.error('Failed to start Electron:', err.message)
+  process.exit(1)
+})

package/lib/README.md

@@ -0,0 +1,145 @@
+# Research Pilot (Current Design)
+
+This README documents the current runtime architecture in `examples/research-pilot` after simplifying memory management.
+
+## 1. Design Direction
+
+The project has moved away from complex in-prompt memory objects (`Fact`, `Focus`, `TaskAnchor`) and now uses:
+
+- durable **Artifacts** on disk as the source of truth
+- lightweight **Session Summary** for cross-turn continuity
+
+In short: persist only what matters, keep chat context lean, and recover continuity via periodic summaries.
+
+Runtime profile:
+
+- `kernelV2.profile = "minimal"` (no task anchor / facts / evidence cards scaffolding)
+
+## 2. Memory Model
+
+### 2.1 Durable memory: Artifact only
+
+Primary persistence is the artifact surface:
+
+- `artifact-create`
+- `artifact-update`
+- `artifact-search`
+
+Legacy `save-paper` / `save-data` wrappers have been removed from the runtime path.
+
+Implemented in:
+
+- `examples/research-pilot/tools/entity-tools.ts`
+- `examples/research-pilot/memory-v2/store.ts`
+
+Artifact files are stored under:
+
+- `.research-pilot/artifacts/notes`
+- `.research-pilot/artifacts/papers`
+- `.research-pilot/artifacts/data`
+- `.research-pilot/artifacts/web-content`
+- `.research-pilot/artifacts/tool-output`
+
+### 2.2 Cross-turn continuity: Session Summary
+
+Session summaries are stored under:
+
+- `.research-pilot/memory-v2/session-summaries/<sessionId>/<timestamp>.json`
+
+Type definition:
+
+- `SessionSummary` in `examples/research-pilot/types.ts`
+
+Store/load functions:
+
+- `writeSessionSummary(...)`
+- `readLatestSessionSummary(...)`
+
+Both in `examples/research-pilot/memory-v2/store.ts`.
+
+### 2.4 Legacy artifact migration
+
+On project init / coordinator startup, legacy artifact payloads are migrated in place:
+
+- `type: "literature"` -> `type: "paper"`
+- `data.name` -> `data.title` (then remove `data.name`)
+
+Implemented in `migrateLegacyArtifacts(...)` in `examples/research-pilot/memory-v2/store.ts`.
+
+### 2.3 Debug explain snapshots
+
+Per-turn explain snapshots are written to:
+
+- `.research-pilot/memory-v2/explain/*.turn.json`
+
+Used by command/UI debugging (`memoryExplainTurn`).
+
+## 3. Coordinator Flow
+
+Main entry:
+
+- `createCoordinator(...)` in `examples/research-pilot/agents/coordinator.ts`
+
+Per user message:
+
+1. Detect intent (rules first, then lightweight router model fallback).
+2. Preload relevant non-script skills for the detected intent.
+3. Build selected context from:
+   - mention selections
+   - latest session summary (if any)
+   - no legacy task/facts/evidence injection in minimal profile
+4. Run agent with additional intent module instructions.
+5. Write turn explain snapshot.
+6. Append turn history and trigger `maybeGenerateSummary()`.
+
+## 4. Session Summary Generation Strategy
+
+`maybeGenerateSummary()` runs only when trigger conditions are met:
+
+- every 5 turns, or
+- heavy tool usage in recent turns, or
+- large recent response volume
+
+It asks a small model for JSON:
+
+```json
+{"summary":"...","topicsDiscussed":["..."],"openQuestions":["..."]}
+```
+
+Then persists a `SessionSummary` record to disk.
+
+## 5. Persistence Policy
+
+Coordinator prompt and routing logic bias toward **ephemeral responses by default**.
+Artifacts are created/updated only when persistence is justified (user asks, reusable output, traceability, etc.).
+
+Relevant files:
+
+- `examples/research-pilot/agents/prompts/index.ts`
+- `examples/research-pilot/agents/coordinator.ts` (`classifyPersistenceDecision`)
+
+## 6. Document Conversion + Skills
+
+`convert_to_markdown` is now a wrapper that dynamically discovers conversion scripts from installed skills and executes them via:
+
+- `skill-script-run`
+
+It records which skill/script was used in the tool result (`converterSkill`, `converterScript`) for UI transparency.
+
+Builtin skills are shipped under `lib/skills/builtin/` and discovered at runtime by the skill loader.
+
+## 7. Public API Surface
+
+Library exports are centralized in:
+
+- `examples/research-pilot/index.ts`
+
+Important commands:
+
+- artifact CRUD/search commands
+- `sessionSummaryGet`
+- `memoryExplainTurn`
+
+## 8. Notes / Known Gaps
+
+- Legacy comments/docs may still mention `Fact/Focus/TaskAnchor`; current behavior is Artifact + Session Summary.

package/lib/skills/_generated.ts

@@ -0,0 +1,13 @@
+/**
+ * AUTO-GENERATED — do not edit manually.
+ * Run: node examples/research-pilot/skills/generate-skill-content.mjs
+ *
+ * Source of truth: SKILL.md files in sibling directories.
+ */
+
+export const dataAnalysisContent = "---\nid: data-analysis-skill\nname: Data Analysis\nshortDescription: Python data analysis, visualization, statistics, and ML modeling\ncategory: Data & Analysis\ntools: [data-analyze]\nloadingStrategy: lazy\ntags: [data, analysis, python, visualization, statistics, ml]\n---\n\nPython data analysis guidance:\n- **Runtime Variables**: Use DATA_FILE, FIGURES_DIR, TABLES_DIR, DATA_DIR, RESULTS_FILE (pre-defined)\n- **STRICT OUTPUT RULE**: Generate ONLY what user requested (count nouns = count outputs)\n- **Results Manifest**: Always call write_results() at end with outputs and summary\n- **No Extras**: No bonus plots, summary tables, or supplementary files unless explicitly requested\n\n## Procedures\n\n### Critical Path Rules\n\n#### Pre-defined Runtime Variables\nThe following variables are defined BEFORE your code runs:\n```python\nDATA_FILE    # Absolute path to input data file\nFIGURES_DIR  # Absolute path for saving figures\nTABLES_DIR   # Absolute path for saving CSV tables\nDATA_DIR     # Absolute path for transformed data\nRESULTS_FILE # Absolute path for results manifest JSON\n```\n\n#### Path Usage Rules (MUST FOLLOW)\n- Use `DATA_FILE` to read input: `pd.read_csv(DATA_FILE)`\n- Use `os.path.join(FIGURES_DIR, \"name.png\")` for outputs\n- Do NOT compute or derive paths\n- Do NOT use `os.path.dirname(__file__)`\n- Do NOT hardcode any file paths\n- Do NOT save to directories other than the pre-defined ones\n\n### STRICT MINIMAL OUTPUT RULE\n\n**This is critical—violation is a failure.**\n\n1. Count the nouns in user request:\n   - \"a plot\" = 1 figure\n   - \"two charts\" = 2 figures\n   - \"statistics\" = 1 summary table\n\n2. Generate EXACTLY that many outputs:\n   - User asks for \"a plot\" → produce 1 PNG, not 2, not 5\n   - User asks for \"statistics\" → produce 1 CSV, not 10\n\n3. Before every `plt.savefig()` or `df.to_csv()`:\n   - Ask: \"Did the user request THIS specific output?\"\n   - If NO → DELETE that code\n\n4. Do NOT create:\n   - Summary tables unless requested\n   - Intermediate DataFrames as CSV\n   - \"Bonus\" outputs like activity plots\n   - Supplementary analyses\n\n### Results Manifest\n\nAlways call `write_results()` at the end:\n\n```python\nwrite_results(\n    outputs=[\n        {\n            \"path\": os.path.join(FIGURES_DIR, \"scatter.png\"),\n            \"type\": \"figure\",\n            \"title\": \"X vs Y Scatter Plot\",\n            \"description\": \"Correlation visualization\",  # optional\n            \"tags\": [\"correlation\", \"scatter\"]           # optional\n        },\n        {\n            \"path\": os.path.join(TABLES_DIR, \"stats.csv\"),\n            \"type\": \"table\",\n            \"title\": \"Summary Statistics\"\n        }\n    ],\n    summary={\n        \"correlation\": 0.85,\n        \"n_rows\": 1000,\n        \"key_finding\": \"Strong positive correlation\"\n    }\n)\n```\n\n### Analysis Tasks\n\n#### analyze (Statistical Analysis)\n- Compute only the statistics explicitly requested by the user\n- Identify correlations/outliers only when requested\n- Print key findings to stdout\n- Save summary as CSV table only if the user asked for file output\n\n#### visualize (Data Visualization)\n- Create appropriate plots for data types\n- Use matplotlib + seaborn for publication quality\n- Add titles, axis labels, legends\n- Use clean style (seaborn whitegrid)\n- Save as PNG (never plt.show())\n\n#### transform (Data Transformation)\n- Clean, reshape, or transform data\n- Handle missing values, type conversions\n- Save transformed dataset as CSV only when requested\n- Print summary of changes\n\n#### model (Statistical Modeling)\n- Build statistical/ML models (sklearn, statsmodels)\n- Report performance metrics\n- Save results summary as CSV only when requested\n- Print key metrics to stdout\n\n### Code Standards\n\n#### Required Setup\n```python\nimport os\nimport json\nimport pandas as pd\nimport numpy as np\nimport matplotlib\nmatplotlib.use('Agg')  # Non-interactive backend\nimport matplotlib.pyplot as plt\nimport seaborn as sns\nimport warnings\nwarnings.filterwarnings('ignore')\n```\n\n#### Figure Best Practices\n```python\nplt.figure(figsize=(10, 6), dpi=150)\n# ... plotting code ...\nplt.tight_layout()\nplt.savefig(os.path.join(FIGURES_DIR, \"name.png\"))\nplt.close()  # Always close after saving\n```\n\n#### Data Quality Checks\n```python\n# Check for missing values\nprint(f\"Missing values: {df.isnull().sum().sum()}\")\n\n# Check data types\nprint(df.dtypes)\n\n# Basic statistics\nprint(df.describe())\n```\n\n## Examples\n\n### Single Plot Request\n\nUser: \"Create a scatter plot of column A vs column B\"\n\n```python\nimport os\nimport pandas as pd\nimport matplotlib\nmatplotlib.use('Agg')\nimport matplotlib.pyplot as plt\nimport seaborn as sns\n\n# Read data\ndf = pd.read_csv(DATA_FILE)\n\n# Create the ONE requested plot\nplt.figure(figsize=(10, 6), dpi=150)\nsns.scatterplot(data=df, x='A', y='B')\nplt.title('A vs B')\nplt.xlabel('A')\nplt.ylabel('B')\nplt.tight_layout()\nplt.savefig(os.path.join(FIGURES_DIR, 'scatter_a_vs_b.png'))\nplt.close()\n\n# Write results manifest\nwrite_results(\n    outputs=[\n        {\"path\": os.path.join(FIGURES_DIR, 'scatter_a_vs_b.png'), \"type\": \"figure\", \"title\": \"A vs B Scatter\"}\n    ],\n    summary={\"correlation\": df['A'].corr(df['B'])}\n)\n```\n\n### Statistics Request\n\nUser: \"Calculate summary statistics for the dataset\"\n\n```python\nimport os\nimport pandas as pd\n\ndf = pd.read_csv(DATA_FILE)\n\n# Calculate statistics\nstats = df.describe()\nstats.to_csv(os.path.join(TABLES_DIR, 'summary_stats.csv'))\n\n# Print to stdout\nprint(\"Summary Statistics:\")\nprint(stats)\n\nwrite_results(\n    outputs=[\n        {\"path\": os.path.join(TABLES_DIR, 'summary_stats.csv'), \"type\": \"table\", \"title\": \"Summary Statistics\"}\n    ],\n    summary={\"n_rows\": len(df), \"n_cols\": len(df.columns)}\n)\n```\n\n### Anti-Pattern: Over-Generation\n\nUser: \"Create a histogram of values\"\n\nBAD (creates 5 outputs for 1 request):\n```python\n# Histogram\nplt.savefig('histogram.png')\n# Box plot (NOT REQUESTED)\nplt.savefig('boxplot.png')\n# Summary stats (NOT REQUESTED)\nstats.to_csv('stats.csv')\n# Data sample (NOT REQUESTED)\ndf.head(100).to_csv('sample.csv')\n# Correlation matrix (NOT REQUESTED)\nplt.savefig('correlation.png')\n```\n\nGOOD (creates exactly 1 output):\n```python\nplt.figure(figsize=(10, 6), dpi=150)\nplt.hist(df['values'], bins=30, edgecolor='black')\nplt.title('Distribution of Values')\nplt.xlabel('Value')\nplt.ylabel('Frequency')\nplt.tight_layout()\nplt.savefig(os.path.join(FIGURES_DIR, 'histogram.png'))\nplt.close()\n\nwrite_results(\n    outputs=[{\"path\": os.path.join(FIGURES_DIR, 'histogram.png'), \"type\": \"figure\", \"title\": \"Value Distribution\"}]\n)\n```\n\n## Troubleshooting\n\n### \"FileNotFoundError for data file\"\n- Use DATA_FILE variable, not hardcoded path\n- Check: `print(DATA_FILE)` to verify path\n- Ensure file exists before reading\n\n### \"Permission denied saving figure\"\n- Use FIGURES_DIR, TABLES_DIR, DATA_DIR only\n- Do not save to arbitrary directories\n- Check directory exists: `os.makedirs(FIGURES_DIR, exist_ok=True)`\n\n### \"Figure not appearing in results\"\n- Call `plt.close()` after `plt.savefig()`\n- Use `matplotlib.use('Agg')` before importing pyplot\n- Include figure in write_results() outputs list\n\n### \"Results manifest missing\"\n- Always call write_results() at end of script\n- Check RESULTS_FILE path is used correctly\n- Ensure outputs list includes all generated files\n\n### \"Too many outputs generated\"\n- Re-read user request: count the nouns\n- Delete any code that creates unrequested outputs\n- Ask: \"Did user ask for THIS?\" for each savefig/to_csv\n\n### \"Plot quality issues\"\n- Set `dpi=150` for good resolution\n- Use `plt.tight_layout()` to prevent clipping\n- Add proper titles and labels\n\n### \"Memory issues with large data\"\n- Use chunked reading: `pd.read_csv(DATA_FILE, chunksize=10000)`\n- Select only needed columns\n- Use appropriate dtypes: `dtype={'col': 'category'}`\n"
+
+/** All skill content keyed by directory name */
+export const skillContent: Record<string, string> = {
+  'data-analysis': dataAnalysisContent,
+}

package/lib/skills/builtin/brainstorming-research-ideas/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: brainstorming-research-ideas
+description: Structured ideation frameworks for discovering high-impact research directions. Use when exploring new topics, pivoting research focus, or when current investigation yields diminishing returns.
+category: Research Ideation
+depends: []
+tags: [Research Ideation, Brainstorming, Problem Discovery, Research Strategy]
+triggers: [brainstorm, research ideas, new direction, explore topics, ideation, pivot research, research questions, 头脑风暴, 研究方向, 选题]
+---
+
+# Research Idea Brainstorming
+
+Ten complementary ideation lenses for moving from vague curiosity to concrete, defensible research proposals. Each framework targets a different cognitive mode — use them individually or combine them via the Integrated Workflow below for a full diverge-converge cycle.
+
+## Overview
+
+This skill provides structured frameworks for generating and evaluating research directions. It is most valuable during the exploratory phase of research — when you need to identify promising questions, broaden your scope, or escape a local optimum in your thinking.
+
+## When to Use This Skill
+
+- You need to explore new research directions or pivot from a current topic.
+- Your current line of investigation has stalled or yields diminishing returns.
+- The user asks for new research ideas and you need to generate and rank candidates.
+- You have a vague area of interest but no specific research question yet.
+
+**Do NOT use this skill when**:
+- You already have a well-defined research question and need execution guidance — proceed with normal task execution.
+- You need a literature survey — use the `literature-search` tool directly.
+- You are mid-task with productive work in progress — finish current work first.
+
+---
+
+## Core Ideation Frameworks
+
+### 1. Problem-First vs. Solution-First Thinking
+
+Research ideas originate from two distinct modes. Knowing which mode you are in prevents building solutions that lack real problems, or chasing problems without feasible approaches.
+
+**Problem-First** (pain point → method):
+- Start with a concrete failure, bottleneck, or unmet need
+- Naturally yields impactful work because the motivation is intrinsic
+- Risk: may converge on incremental fixes rather than paradigm shifts
+
+**Solution-First** (new capability → application):
+- Start with a new tool, insight, or technique seeking application
+- Often drives breakthroughs by unlocking previously impossible approaches
+- Risk: "hammer looking for a nail" — solution may lack genuine demand
+
+**Application**: When generating candidate directions, classify each as problem-first or solution-first. Problem-first candidates need a feasibility check; solution-first candidates need at least two genuine problems they address.
+
+---
+
+### 2. The Abstraction Ladder
+
+Every research problem sits at a particular level of abstraction. Deliberately moving up or down reveals ideas invisible at your current level.
+
+| Direction | Action | Outcome |
+|-----------|--------|---------|
+| **Move Up** (generalize) | Turn a specific result into a broader principle | Framework papers, theoretical contributions |
+| **Move Down** (instantiate) | Test a general paradigm under concrete constraints | Empirical papers, surprising failure analyses |
+| **Move Sideways** (analogize) | Apply same abstraction level to adjacent domain | Cross-pollination, transfer papers |
+
+**Application**: For any candidate direction, generate the up/down/sideways variants. Each variant is a potential research topic. Use the `literature-search` tool to validate the most promising variants.
+
+---
+
+### 3. Tension and Contradiction Hunting
+
+Breakthroughs often come from resolving tensions between widely accepted but seemingly conflicting goals. These contradictions are the research opportunity.
+
+**Common Research Tensions**:
+
+| Tension Pair | Research Opportunity |
+|-------------|---------------------|
+| Performance ↔ Efficiency | Can we match SOTA with 10x less compute? |
+| Privacy ↔ Utility | Can federated/encrypted methods close the accuracy gap? |
+| Generality ↔ Specialization | When does fine-tuning beat prompting, and why? |
+| Safety ↔ Capability | Can alignment improve rather than tax capability? |
+| Interpretability ↔ Performance | Do mechanistic insights enable better architectures? |
+| Scale ↔ Accessibility | Can small models replicate emergent behaviors? |
+
+**Application**: List the top 3-5 desiderata in your research area. Identify pairs treated as trade-offs. For each pair: is the trade-off fundamental or an artifact of current methods? If artifact → the reconciliation IS the research direction. If fundamental → characterizing the Pareto frontier is itself valuable.
+
+---
+
+### 4. Cross-Pollination (Analogy Transfer)
+
+Borrowing structural ideas from other disciplines is one of the most generative research heuristics. Attention mechanisms from cognitive science, genetic algorithms from biology, adversarial training from game theory.
+
+**Requirements for a Valid Analogy**:
+- **Structural fidelity**: The mapping must hold at the level of underlying mechanisms, not just surface similarity
+- **Non-obvious connection**: If the link is well-known, the novelty is gone
+- **Testable predictions**: The analogy should generate concrete hypotheses
+
+**High-Yield Source Fields**:
+
+| Source Field | Transferable Concepts |
+|-------------|----------------------|
+| Neuroscience | Attention, memory consolidation, hierarchical processing |
+| Physics | Energy-based models, phase transitions, renormalization |
+| Economics | Mechanism design, auction theory, incentive alignment |
+| Ecology | Population dynamics, niche competition, co-evolution |
+| Linguistics | Compositionality, pragmatics, grammatical induction |
+| Control Theory | Feedback loops, stability, adaptive regulation |
+
+**Application**: Describe the problem in domain-agnostic language (strip jargon). Identify which other field solves a structurally similar problem. Use the `literature-search` tool to search that field's solution at the mechanism level. Save the analogy as a note artifact before building on it.
+
+---
+
+### 5. The "What Changed?" Principle
+
+Strong ideas often come from revisiting old problems under new conditions. Advances in hardware, scale, data availability, or regulations can invalidate prior assumptions.
+
+**Categories of Change to Monitor**:
+
+| Change Type | Example | Research Implication |
+|------------|---------|---------------------|
+| **Compute** | GPUs 10x faster | Methods dismissed as too expensive become feasible |
+| **Scale** | Trillion-token datasets | Statistical arguments that failed at small scale may now hold |
+| **Regulation** | EU AI Act, GDPR | Creates demand for compliant alternatives |
+| **Tooling** | New frameworks, APIs | Reduces implementation barrier for complex methods |
+| **Failure** | High-profile system failures | Exposes gaps in existing approaches |
+| **Cultural** | New user behaviors | Shifts what problems matter most |
+
+**Application**: Pick a well-known negative result or abandoned approach (3-10 years old) from the literature. List the assumptions that led to its rejection. For each: is this still true today? If any assumption is invalidated → frame the direction as "X was previously impractical because Y, but Z has changed." Use `literature-search` to check whether anyone already revisited it.
+
+---
+
+### 6. Failure Analysis and Boundary Probing
+
+Understanding where a method breaks is often as valuable as showing where it works. Boundary probing systematically exposes the conditions under which accepted techniques fail.
+
+**Types of Boundaries to Probe**:
+- **Distributional**: What happens with out-of-distribution inputs?
+- **Scale**: Does the method degrade at 10x or 0.1x the typical scale?
+- **Adversarial**: Can the method be deliberately broken?
+- **Compositional**: Does performance hold when combining multiple capabilities?
+- **Temporal**: Does the method degrade over time (concept drift)?
+
+**Application**: Select a widely-used method in your research area. Identify the implicit assumptions in its evaluation. Design experiments that systematically violate each assumption. The failure mode often reveals both the root cause and a constructive path forward.
+
+---
+
+### 7. The Simplicity Test
+
+Before accepting complexity, ask whether a simpler approach suffices. Fields sometimes over-index on elaborate solutions when a streamlined baseline performs competitively.
+
+**Warning Signs of Unnecessary Complexity**:
+- The method has many hyperparameters with narrow optimal ranges
+- Ablations show most components contribute marginally
+- A simple baseline was never properly tuned or evaluated
+- The improvement over baselines is within noise on most benchmarks
+
+**Application**: For any research direction, strip the current approach to its simplest core. If the gap vs. full method is small → the contribution is the simplicity itself. If the gap is large → you now understand what the complexity buys. Either outcome sharpens the direction.
+
+---
+
+### 8. Stakeholder Rotation
+
+Viewing a system from multiple perspectives reveals distinct classes of research questions.
+
+| Stakeholder | Key Questions |
+|-------------|---------------|
+| **End User** | Is this usable? What errors are unacceptable? What is the latency tolerance? |
+| **Developer** | Is this debuggable? What is the maintenance burden? How does it compose? |
+| **Theorist** | Why does this work? What are the formal guarantees? Where are the gaps? |
+| **Adversary** | How can this be exploited? What are the attack surfaces? |
+| **Ethicist** | Who is harmed? What biases are embedded? Who is excluded? |
+| **Regulator** | Is this auditable? Can decisions be explained? Is there accountability? |
+| **Operator** | What is the cost? How does it scale? What is the failure mode? |
+
+**Application**: When evaluating candidate directions, cycle through at least 3 stakeholder perspectives. Unaddressed concerns with broad impact are high-value research questions.
+
+---
+
+### 9. Composition and Decomposition
+
+Novelty often emerges from recombination or modularization.
+
+**Composition** (combining existing techniques):
+- Identify two methods that solve complementary subproblems
+- Ask: What emergent capability arises from combining them?
+
+**Decomposition** (breaking apart monolithic systems):
+- Identify a complex system with entangled components
+- Ask: Which component is the actual bottleneck?
+
+**Application**: List the 5-10 key techniques in your research area. For compositions: pick pairs and hypothesize emergent capabilities. For decompositions: isolate each component's contribution. Save promising combinations as note artifacts for further exploration.
+
+---
+
+### 10. The Two-Sentence Pitch Test
+
+A strong research direction should be defensible in two sentences.
+
+**Template**:
+> **Sentence 1** (Problem): "[Domain] currently struggles with [specific problem], which matters because [concrete consequence]."
+> **Sentence 2** (Insight): "We [approach] by [key mechanism], which works because [reason]."
+
+**If you cannot fill this template**:
+- Problem not well-defined → return to Framework 1
+- Insight not clear → return to Framework 7 (simplify)
+- Significance not established → return to Framework 3 (find the tension)
+
+---
+
+## Integrated Workflow: Diverge → Converge → Refine
+
+Use this when a full exploration cycle is needed to generate and rank multiple candidate directions.
+
+### Phase 1: Diverge (Generate Candidates)
+
+**Goal**: Produce 10-20 candidate directions without filtering.
+
+1. **Scan for tensions** (F3): List 5 trade-offs in the research area
+2. **Check what changed** (F5): Use `literature-search` to identify 3 recent shifts
+3. **Probe boundaries** (F6): Pick 2 popular methods and find where they break
+4. **Cross-pollinate** (F4): Pick 1 idea from an adjacent field
+5. **Compose/decompose** (F9): Combine 2 existing techniques or split 1 apart
+6. **Climb the abstraction ladder** (F2): For each candidate, generate up/down/sideways variants
+
+Save the full candidate list as a note artifact so it persists across sessions.
+
+### Phase 2: Converge (Filter and Rank)
+
+**Goal**: Narrow to 3-5 strongest candidates.
+
+Apply these filters to each candidate:
+
+| Filter | Question | Kill Criterion |
+|--------|----------|----------------|
+| **Two-Sentence Test** (F10) | Can you state this in two sentences? | If no → idea is not yet clear enough |
+| **Problem-First Check** (F1) | Is the problem genuine and important? | If no one suffers from this → drop it |
+| **Simplicity Test** (F7) | Is the complexity justified? | If a simpler approach works → simplify or drop |
+| **Stakeholder Check** (F8) | Who benefits? Who might object? | If no clear beneficiary → drop it |
+| **Feasibility** | Can this be executed within project constraints? | If clearly infeasible given budget/compute → park it |
+
+### Phase 3: Refine (Sharpen the Winner)
+
+**Goal**: Turn the top candidate into a concrete research plan.
+
+1. Write the two-sentence pitch (F10)
+2. Identify the core tension being resolved (F3)
+3. Specify the abstraction level (F2)
+4. Draft 3 concrete validation questions that would confirm or refute the direction
+5. Anticipate the strongest objection and prepare a response
+6. Present the refined direction to the user for approval
+
+**Output mapping**:
+- Winning direction → concrete research plan for the user
+- Top 3 candidates → literature search tasks to validate each
+- Validation questions → next steps for the research
+- Full candidate list + analysis → saved as note artifact for future reference
+
+---
+
+## Framework Selection Guide
+
+| Your Situation | Start With |
+|---------------|------------|
+| No clear area, exploring broadly | Tension Hunting (F3) → What Changed (F5) |
+| Vague area but no specific direction | Abstraction Ladder (F2) → Failure Analysis (F6) |
+| Have a direction but unsure of its value | Two-Sentence Test (F10) → Simplicity Test (F7) |
+| Good direction but need a fresh angle | Cross-Pollination (F4) → Stakeholder Rotation (F8) |
+| Want to combine existing findings | Composition/Decomposition (F9) |
+| Found a technique, seeking application | Problem-First Check (F1) → Stakeholder Rotation (F8) |
+| Want to challenge current approach | Failure Analysis (F6) → Simplicity Test (F7) |
+
+---
+
+## Common Pitfalls in Research Ideation
+
+| Pitfall | Symptom | Fix |
+|---------|---------|-----|
+| **Novelty without impact** | "No one has done X" but no one needs X | Apply Problem-First Check (F1) |
+| **Incremental by default** | Idea is +2% on a benchmark | Climb the Abstraction Ladder (F2) |
+| **Complexity worship** | Method has 8 components, each helping marginally | Apply Simplicity Test (F7) |
+| **Echo chamber** | All ideas come from the same literature cluster | Use Cross-Pollination (F4) with `literature-search` on adjacent fields |
+| **Stale assumptions** | "This was tried and didn't work" (years ago) | Apply What Changed (F5) |
+| **Single-perspective bias** | Only considering one stakeholder | Use Stakeholder Rotation (F8) |
+| **Premature convergence** | Committed to first idea without exploring | Run full Diverge phase |

package/lib/skills/builtin/coding/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: coding
+description: Systematic coding workflow for implementing, debugging, and refactoring code. Covers test-first development, 300-line generation limits, edit-over-rewrite, error-feedback loops, and incremental verification patterns.
+category: General
+depends: []
+tags: [code, programming, development, debugging, refactoring, testing]
+triggers: [write code, implement, fix bug, debug, refactor, add feature, unit test, coding, code review, build error, test failure, programming, develop, 写代码, 编程, 调试, 重构]
+allowed-tools: [Read, Write, Edit, Bash, Grep, Find, Ls]
+---
+
+# Coding
+
+## Overview
+
+This skill provides a disciplined workflow for writing, modifying, and debugging code inside the workspace. The core principle is **small verified steps**: never generate large blocks without running tests, never rewrite a file when a targeted edit suffices, and always close the feedback loop by checking the result of every change.
+
+## When to Use This Skill
+
+- Implementing a new feature, function, or module
+- Fixing a bug or build error
+- Refactoring existing code
+- Adding or updating tests
+- Reviewing code and suggesting improvements
+- Any task that involves reading, writing, or running code in the workspace
+
+## Core Principles
+
+### 1. Understand Before Changing
+
+Before writing any code:
+1. Use `grep` and `find` to locate relevant files and understand the existing structure.
+2. Use `read` with offset+limit to inspect specific sections — avoid reading entire large files.
+3. Identify existing patterns, conventions, naming schemes, and test styles in the project.
+4. Check for existing tests related to the area you are changing.
+
+### 2. Test-First Development
+
+When the project has a test framework:
+1. **Write or update the test first** that captures the expected behavior.
+2. Run the test to confirm it fails (red).
+3. Implement the minimal code to make the test pass (green).
+4. Run the test again to confirm it passes.
+5. Refactor if needed, re-running tests after each change.
+
+When there is no test framework or when writing a quick script, verify by running the code and checking output instead.
+
+### 3. Small Generation Limit
+
+- **Never generate more than 300 lines of code in a single write/edit operation.** If the task requires more, break it into multiple steps, verifying each step before proceeding.
+- Prefer multiple small, tested increments over one large generation.
+- Each increment should leave the codebase in a working state.
+
+### 4. Edit Over Rewrite
+
+- **Use `edit` (oldText/newText) for targeted changes** to existing files. Do not rewrite an entire file when only a few lines need to change.
+- Use `write` only for new files or when the majority of a file must change.
+- Before editing, `read` the relevant section to get the exact `oldText` — do not guess.
+
+### 5. Error-Feedback Loop
+
+After every code change:
+1. **Run the relevant command** (build, test, lint, or the script itself) using `bash`.
+2. **Read the error output carefully.** Do not guess what went wrong.
+3. If the command fails, diagnose the root cause from the actual error message.
+4. Fix the specific issue. Do not make speculative bulk changes.
+5. Re-run to confirm the fix. Repeat until green.
+
+Never move on to the next step while the current step has failing tests or build errors.
+
+### 6. Iteration Awareness
+
+For multi-step tasks:
+- Plan the sequence of changes before starting.
+- After each step, verify the codebase is in a clean state (tests pass, no lint errors).
+- If you discover that your plan needs adjustment, state the revised plan before continuing.
+- Keep the user informed of progress: what was done, what comes next.
+
+## Workflow
+
+### New Feature Implementation
+
+1. **Locate**: `grep`/`find` to understand where the feature fits.
+2. **Read**: Inspect related modules, interfaces, and existing tests.
+3. **Plan**: State the files to create/modify and the order.
+4. **Test**: Write the test(s) first.
+5. **Implement**: Write code in increments of <=300 lines per operation.
+6. **Verify**: Run tests after each increment.
+7. **Clean up**: Remove dead code, add comments where non-obvious.
+
+### Bug Fix
+
+1. **Reproduce**: Run the failing test or command; read the error.
+2. **Locate**: Use `grep` to find the relevant code path.
+3. **Diagnose**: Read the code and identify the root cause.
+4. **Test**: Write a test that reproduces the bug (if one doesn't exist).
+5. **Fix**: Make the minimal targeted edit.
+6. **Verify**: Run tests to confirm the fix and no regressions.
+
+### Refactoring
+
+1. **Ensure coverage**: Confirm existing tests pass before refactoring.
+2. **Change incrementally**: One refactoring step at a time.
+3. **Verify after each step**: Run tests between every change.
+4. **Do not change behavior**: If tests break, the refactoring introduced a bug — fix it before continuing.
+
+## Anti-Patterns to Avoid
+
+- Generating an entire file from scratch when only a few lines need changing.
+- Writing code without checking existing patterns/conventions in the project.
+- Making multiple changes before running any verification.
+- Ignoring test failures and continuing to the next step.
+- Guessing at file contents instead of reading them.
+- Using `bash cat` or `bash grep` when the built-in `read`/`grep`/`find` tools are available.
+- Generating more than 300 lines in a single operation.