research-pilot
Use when the user wants an agent to track, inspect, or operate Research Pilot project memory through natural chat.
SKILL.mdskills/research-pilot/SKILL.md
GitHubResearch Pilot
Research Pilot is the primary intent router for chat-first, agent-operated research memory.
User-facing interface is chat. The user should not need to know command names, skill names, workflow files, server commands, graph deltas, or read-model mechanics.
Product Model
user asks agent
-> agent uses Research Pilot resources
-> workspace-local research-pilot.db stores project data
-> dashboard observes read models
-> user keeps researching through chat
Default Boundaries
research-pilot.dbis the primary workspace dataset.- Dashboard is read-only observation.
- Skills and tools are agent-operated resources.
- UnderstandingUpdates / DB-backed project memory are normal update path.
- Graph events and D* deltas are advanced strict review mode.
- Zotero is an optional supported adapter, not a first-run requirement.
- Program context is taste and north-star background only; it is not evidence, project truth, or an automatic decision source.
Workspace Detection
A directory is a Research Pilot workspace when it has:
research-pilot.db
AGENTS.md
wiki/index.md
wiki/log.md
.research-pilot/config.example.toml or .research-pilot/config.toml
Legacy workspaces may not yet have research-pilot.db; if workspace markers exist, inspect status before deciding whether initialization/import is needed.
DB Write Route
For normal project memory writes, use the dataset writer:
from pathlib import Path
import sys
PLUGIN_ROOT = Path("...").expanduser().resolve()
WORKSPACE_PATH = Path("...").expanduser().resolve()
sys.path.insert(0, str(PLUGIN_ROOT))
from tools.research_dataset_writer import ProjectDatasetWriter
result = ProjectDatasetWriter(WORKSPACE_PATH, actor="agent").write_project_update(packet)
Packet minimum:
- required top-level:
project_id,activity_type,summary - optional sections:
project,sources,understanding_nodes,understanding_links,experiments,experiment_runs,experiment_metrics,experiment_artifacts,literature_lanes,literature_items,literature_relations,project_positionings,entity_links
Required field examples:
- source needs
source_idat minimum; usually include title, type, locator, status, and depth. - understanding node needs
node_id,scope,node_type,text. - understanding link needs
link_id,link_type,relation, andendpoints. - every
understanding_links[]item includesendpoints: [...]; each endpoint hasroleandnode_id. - real reasoning/translation links should include meaningful endpoints.
- experiment needs
experiment_id,title. - run needs
run_id,experiment_id,origin_type. - metric needs
metric_id,run_id,name,value_text.
Intent Routes
start_or_track_project
User examples:
Use Research Pilot to track this project.
Start Research Pilot for this research idea.
Track my project memory here.
Agent behavior:
- Resolve workspace path only if needed.
- Initialize or inspect workspace with
tools/research_pilot_init.py/tools/research_pilot_status.py. - Create or select project.
- Record initial project brief or UnderstandingUpdate.
- Offer to open dashboard.
- Do not require D* review for first-run unless user asks for strict review.
inspect_workspace_or_project
User examples:
What does this project currently understand?
Where does this workspace stand?
Agent behavior:
- Run
tools/research_pilot_status.py --repo "$WORKSPACE_PATH" --json. - Prefer DB-backed read models where available.
- Summarize state in product terms: project, sources, understanding, literature, experiments, dashboard readiness.
- Avoid exposing read-model rebuild mechanics unless needed for diagnosis.
open_dashboard
User examples:
Open the Research Pilot dashboard.
Show me the dashboard.
Agent behavior:
- Detect workspace; if current directory is plugin repo, use
examples/workspaces. - Reuse or start
tools/research_browser_server.py. - Wait until dashboard URL responds.
- Open browser or report URL.
- Keep boundary: dashboard is read-only.
record_source
User examples:
Track this PDF.
Read this arXiv link.
Use this DOI as a source.
Add this note to the project.
Agent behavior:
- Accept PDF path, URL, arXiv, DOI, Markdown note, experiment result, manual reference, or Zotero item.
- Write packet through
ProjectDatasetWriter.write_project_update. - Use
activity_type: "source_record"for source identity/status/relevance capture. - Include
sourceswithsource_id; usually includesource_type,title,locatororurl/doi/arxiv_id,reading_status, andreading_depth. - Add
understanding_nodesonly when the source changes project understanding. - Use Zotero only when provided/configured or when user asks.
- If project understanding changes, include an UnderstandingUpdate-style
summaryand project-scoped nodes/links.
deep_read_source
User examples:
Read this paper deeply in project context.
Extract the claims and limitations that matter for this project.
Agent behavior:
- Create or update source/paper note and DB source record.
- Separate source-level understanding from project-level understanding.
- Write packet through
ProjectDatasetWriter.write_project_update. - Use
activity_type: "deep_read". - Include
sourcesfor the source, paper-scopedunderstanding_nodesfor extracted claims/evidence/limitations, and project-scopedunderstanding_nodesorunderstanding_linksfor project impact. - Include link
endpointswhen connecting nodes. - Use D* only under strict review.
update_project_understanding
User examples:
This changes our hypothesis.
Compare this with the current claim.
Record this experiment result as project evidence.
Agent behavior:
- Classify the update.
- Write normal project memory update through
ProjectDatasetWriter.write_project_update. - Use
activity_type: "understanding_update". - Include
understanding_nodesfor questions, claims, evidence, warrants, or limitations; includeunderstanding_linkswithendpointswhen recording relations. - Preserve uncertainty/status with status, confidence, confirmation, and metadata fields.
- Use strict review for high-impact formal graph updates or when user asks.
map_literature
User examples:
Map related work around this project.
Build a technical lineage around this baseline paper.
Agent behavior:
Use related-work-lineage; keep output paper-only and read-only. Do not append graph events or mutate project graph truth.
If the user gives a broad map request, ask the user to narrow or split maps and exclude low-signal follow-ups before creating the map.
record_experiment
User examples:
Track this planned experiment.
Record these completed experiment results.
Agent behavior:
- Write packet through
ProjectDatasetWriter.write_project_update. - Use
activity_type: "experiment_record"for planned experiments. - Use
activity_type: "experiment_result"for completed runs/results. - Include
experimentswithexperiment_id,title; includeexperiment_runswithrun_id,experiment_id,origin_type; includeexperiment_metricswithmetric_id,run_id,name,value_text. - Connect to claims/evidence with
entity_linksorunderstanding_linkswhen available. - Do not call proposal-only framing normal product language.
strict_review
User examples:
Use strict review for this claim update.
Make this a formal graph update.
Agent behavior:
- Draft D* proposal.
- Dry-run.
- Summarize effect.
- Wait for human accept/reject/park/revise.
- Append accepted graph event only after explicit approval.
Internal Tools
Tools are internal implementation APIs. Use exact CLI commands from tool docs or advanced workflow docs when needed, but do not ask users to memorize them.