research-onboard

name	research-onboard
description	Use when bridging a raw or existing workspace into the Scope SSOT with /research-onboard: detect/scaffold or analyze the workspace, write prior knowledge, draft a Project objective, and create a PM-ratifiable Project Scope proposal. Always show the proposed Scope clearly to the PM with the next ratification step. The skill only proposes through Triage; it never commits the SSOT or creates packages.
argument-hint	[<cwd, defaults to .>]
allowed-tools	Bash(python3 *), Read, Edit, Write, Grep, Glob
disable-model-invocation	false

research-onboard (the steps 1->3 bridge)

/research-dashboard stands up the HTML chrome; /research-scope ratifies intent into the Scope SSOT. Between them is a gap: a raw workspace has no objective yet, and the agent has historically dropped the user at an empty dashboard with no help. This skill closes that gap. It turns "I opened a repo" into a pending Project proposal the PM can ratify — without ever writing the SSOT itself.

The trust invariant is unchanged: the agent proposes; the PM disposes. This skill submits a pending Triage item through the same triage.py gate research-scope uses; the human accepts and commits the scope-transition. Onboarding never mutates transitions.jsonl.

The PM visibility invariant is also mandatory: never ask the PM to accept, reject, or revise a Scope proposal without showing the exact Scope content first. Every candidate or pending Project Scope must be presented as a clear review block that names the current state and the next PM action.

Resources

Pipeline root: /home/uqzzha35/Project/Trustworthy-Research-Pipeline/Trustworthy-Research-Pipeline

Resource	Path
Onboard CLI	<pipeline-root>/skills/research-onboard/scripts/onboard.py
Scope SSOT lib	<pipeline-root>/lib/scope_ssot/__init__.py
Triage CLI	<pipeline-root>/skills/research-scope/scripts/triage.py
Prior-knowledge artifact	outputs/_scope/prior_knowledge.md
Transition log (SSOT commits)	outputs/_scope/transitions.jsonl
Triage queue	outputs/_scope/triage.jsonl
Hand-off skill (commit path)	research-scope

Onboard CLI commands (drive via Bash(python3 *)):

python3 skills/research-onboard/scripts/onboard.py detect --cwd .
python3 skills/research-onboard/scripts/onboard.py scaffold --cwd .
python3 skills/research-onboard/scripts/onboard.py write-prior-knowledge --state-root outputs --content '<markdown>'
python3 skills/research-onboard/scripts/onboard.py build-proposal --node-id project/<slug> --spec '<json>' --source '<files read>'
python3 skills/research-onboard/scripts/onboard.py has-project-scope --transitions outputs/_scope/transitions.jsonl

Precondition

The dashboard must exist (run /research-dashboard first). If a Project node is already committed (has-project-scope prints true), there is nothing to bootstrap — stop and point the user at /research-brainstorm (vague idea) or /research-scope (clear Direction) to add a Direction (step 3) instead.

Procedure

1. Detect the workspace state.

python3 skills/research-onboard/scripts/onboard.py detect --cwd .

"state": "empty" means nothing but pipeline-managed/noise entries exist. "existing" means there is project content to analyze (listed under "content").

2a. Empty workspace — scaffold, then elicit.

Scaffold the in-place deep-learning skeleton (idempotent; writes AGENTS.md and CLAUDE.md stubs only if absent):

python3 skills/research-onboard/scripts/onboard.py scaffold --cwd .

There is no repo to mine, so elicit the objective from the user in plain dialogue, one question at a time: the goal, the core contributions, and what is out of scope. Do not invent these. Source for the proposal is user-dialogue:onboarding.

2b. Existing workspace — analyze, then draft.

Read the content entries detect reported — typically README.md, any AGENTS.md / CLAUDE.md, configs/, the src/ tree, dataset locations, and existing baselines/ or reported metrics. From them, draft:

• prior knowledge — a human-readable digest the later roles (R2 lit, R3 ideate, R4 experiment) read: dataset inventory, existing baselines and any current-best metric, the key file map, training/eval commands. Write it (this is content, not an SSOT write):

  python3 skills/research-onboard/scripts/onboard.py write-prior-knowledge --state-root outputs --content '<markdown>'
  

• a candidate objective — goal, contributions, out_of_scope inferred from what you read. Keep these as intent, never readings (no measured values inside the spec). Provenance lists the files you read, e.g. read:README.md,AGENTS.md,CLAUDE.md,configs/train.yaml. goal is a 3-100 word string so an exact short Project objective can be ratified; contributions and out_of_scope are non-empty lists where each item is 5-50 words.

Confirm the drafted objective with the user before proposing — they may correct the goal. This is the HCI-alignment moment (核心问题 #2): the agent shows its inferred understanding and the user steers it. Do not call triage.py propose until this clear review has been shown and the user has confirmed that the displayed content is the proposal they want to ratify.

Use this PM-facing format whenever showing a candidate or pending Project Scope:

**Project Scope Review**
- Status: Candidate, not yet proposed to Triage | Pending Triage, not yet committed
- Level: project
- Node: project/<slug>
- Objective / Goal: <exact text that would enter the Project node>
- Contributions: <each proposed contribution exactly as it would enter the Project node>
- Out of Scope: <each boundary exactly as it would enter the Project node>
- Provenance: <user dialogue and/or files read>
- Next Step: <CONFIRM to submit to Triage, REVISE with changes, or REJECT the draft; if already pending, ACCEPT to ratify or REJECT to archive>

If the user supplied an exact objective, show it verbatim in Objective / Goal. Any inferred wording, interpretation, or rationale must be shown separately and cannot replace the user's exact objective unless the PM explicitly accepts that rewritten text.

3. Build the validated Project proposal.

python3 skills/research-onboard/scripts/onboard.py build-proposal \
    --node-id project/<slug> \
    --spec '{"goal":"<3-100 word project goal>","contributions":["<5-50 word contribution>"],"out_of_scope":["<5-50 word boundary>"]}' \
    --source '<dialogue or files read>'

build-proposal validates the spec against the SSOT schema (reject-before-propose): a reading or a non-project field is refused before anything is written. Fix the spec if it raises.

4. Submit through the Triage gate and STOP.

Pipe the proposal into the same gate research-scope uses:

python3 skills/research-scope/scripts/triage.py propose --log outputs/_scope/triage.jsonl --item '<proposal json>'
python3 skills/research-scope/scripts/triage.py pending --log outputs/_scope/triage.jsonl

Show the pending item using the same Project Scope Review format, including the exact next PM action. Then stop. Onboarding is done — committing the objective is the PM's decision.

Hand-off (PM action, not agent)

This mirrors research-scope's human-accept path. Tell the PM which one applies:

1. Accept: dispose the Triage item with --decision ACCEPTED, then commit the Project node with research-op --pkg _scope --op scope-transition --from-triage <item-id> (the Project gate is carried by the accepted proposal).
2. Revise: say what field should change; the agent updates the proposal and shows the full Project Scope Review again before any new Triage proposal.
3. Reject: dispose or archive the Triage item; no Scope SSOT transition is written.
4. Once the Project is committed, the journey advances to step 3 — forming a Direction under the ratified Project. If the user only has a vague idea, route through /research-brainstorm (shape it, ground uncertainties, converge to a Direction proposal). If they already have a clear Direction (hypothesis / metric / baselines / success_gate), /research-scope proposes it directly.

Scope (what this skill does NOT do)

• Does not commit the SSOT — only proposes a pending Triage item.
• Does not create Directions, Tasks, milestones, or research packages — those are /research-scope and /research-package, after the Project is ratified.
• Does not edit the dashboard chrome or rule files.

Output contract

Path	Written by	Contents
<cwd>/src, configs/, … + AGENTS.md / CLAUDE.md stubs	this skill (empty case only)	in-place DL skeleton
outputs/_scope/prior_knowledge.md	this skill (existing case)	analysis digest for later roles
outputs/_scope/triage.jsonl	triage.py propose	one pending Project item
outputs/_scope/transitions.jsonl	PM only (via research-op)	committed Project node — never this skill

Done condition

A pending project-level Triage item is visible in triage.jsonl and has been shown to the user in the Project Scope Review format with an explicit next step; for an empty workspace the skeleton is scaffolded; for an existing one prior_knowledge.md is written. The objective is not yet in effect — it takes effect only after PM acceptance and the research-op --pkg _scope --op scope-transition --from-triage <item-id> commit.