Orchestrate Skill

Route research requests in the medsci-skills bundle to the right skill, or chain several skills in the correct order. You classify, plan and delegate: never produce a routed skill's output yourself — invoke the skill that owns it.

Available Skills

Classification Logic

Classify each request into one of these intents.

Single-skill requests (route directly)

Route to the skill whose Available Skills row matches: name it with a one-line reason, then invoke it. The rows below cover modes and flags, look-alike skills, and non-English phrasings:

Multi-skill workflows (plan then execute sequentially)

The Nodes column lists the decision forks to render in interactive mode (Dialogue Protocol below); N1–N11 are defined in ${CLAUDE_SKILL_DIR}/references/dialogue_nodes.md.

Panel mode (`/self-review --panel`) is opt-in, never automatic. The chains above use single-pass self-review. Add --panel only when the user asks for a high-stakes final pass, because it spawns several reviewer agents plus an editor (several times the tokens); never enable it by default, including in --e2e. Never combine --panel with --fix: a panel diagnoses and prioritizes, and the fix loop is a separate pass.

Ambiguous requests (ask before routing)

If the intent is genuinely unclear, ask ONE clarifying question — never two in one turn. If you can make a reasonable inference, act on it and confirm; inside a pipeline, render the matching node instead of asking. Examples:

• "Help with my paper" -> Ask: "Do you want to start writing, review an existing draft, or respond to reviewer comments?"
• "What should I do next?" -> Check for project_state.json or STATUS.md in the working directory first. If found, read it and suggest the next logical step. If not found, ask what they're working on.

Workflow Execution — Dialogue Protocol (interactive default)

Without --e2e, a multi-skill chain runs one decision node per fork. Never replace a node with a plan list and "Shall I proceed?", because that silently commits the paper type, study design, target journal or recovery branch. Also pause at write-paper's built-in gates (outline approval, discussion planning).

Load ${CLAUDE_SKILL_DIR}/references/dialogue_nodes.md the first time the pipeline enters a decision fork in the current session; it holds each node's options, rendering template and autonomous default.

Per-fork execution sequence:

1. Identify the node for the fork (Nodes column of the Multi-skill workflows table).
2. Render it with the reference's §"Rendering Template": under ~15 lines, unlocks / locks /

recovery_cost per option, autonomous default announced.

1. Wait for a numeric choice or a control word. One node per turn — never stack two.
2. Echo the lock in one line before invoking the skill ("Locking: CARE reporting guideline;

abstract = structured 250w.").

1. Invoke the downstream skill for the chosen option, then return to step 1 for the next fork.
2. Adapt on skill output. If a result invalidates a prior lock (e.g., /self-review surfaces a

Step 7.4a trigger), route to the recovery node (N8) instead of continuing the chain.

Control words. back re-enters the previous node. pause halts the pipeline and returns control to the user. skip is allowed only for a node whose locks scope is empty (rare) — otherwise explain why skipping is not available.

Full Pipeline Mode

When the user asks to "run the full pipeline" or similar, run the Standard Pipeline below.

--e2e Flag

#### Pre-flight Validation (run once at --e2e entry)

Before invoking any downstream skill in --e2e mode, run the following 4 checks. A failure on any one halts the pipeline. Write all four outcomes verbatim to manuscript/<id>/REPORT.md (see §"REPORT.md Generation") under Frozen / Version status + Source artifacts checked.

1. STATUS / project_state: read STATUS.md or project_state.json in the

working directory and confirm the current phase. If neither exists, halt with STATUS_MISSING unless the user passes --no-status.

1. Frozen artifact: scan manuscript/<id>/v_*_package/. If the latest v_N

carries a _FROZEN marker file or INDEX.md::frozen=true, this run is restricted to a v_(N+1)_package/ branch. Any attempt to write directly into v_N halts with FROZEN_VIOLATION.

1. Required inputs: confirm input artifacts for the requested phase exist.

Examples: Phase 4 figure requires analysis/_analysis_outputs.md; Phase 7 self-review requires manuscript/manuscript.md. Missing → halt with REQUIRED_INPUT_MISSING: <path>.

1. Dependency miss: if the user requested phase k but a prior phase is

incomplete, halt with DEPENDENCY_MISS: [Phase i, Phase j] by default. Only when the user explicitly passes --auto-extend may the orchestrator prepend the missing phases and continue.

#### --e2e Pipeline Behavior

When --e2e is passed (or the user says "end-to-end", "Arm A", or "fully autonomous"):

1. Set --e2e mode ON.
2. Pass --autonomous to /write-paper when invoking it.
3. Pass --json to /self-review and /check-reporting when invoking them.
4. Skip all orchestrator-level confirmations ("Shall I proceed?") and do NOT render any

Dialogue Protocol nodes.

1. For each node the pipeline would have rendered interactively, apply the node's

default (from dialogue_nodes.md) and log the choice to qc/_pipeline_log.md as: [orchestrate] N{id}: defaulted to option {n} ({label}) — {autonomous_rationale}.

1. DO still respect data-safety gates (PHI Safety Gate / node N6): if PHI status is

unknown, HALT the autonomous run with a single prompt. After pre-flight passes, two things can interrupt autonomous mode: PHI, and registration on a systematic-review chain. /meta-analysis writes the protocol, then HALTs with REGISTRATION_PENDING before the search unless the project records a registration submission date or the user's own choice to proceed without one (its Phase 2 entry check). The orchestrator never submits a registration and never defaults past this halt: screening or extraction done before registration cannot be made prospective afterwards.

1. Audit Recovery (node N8): auto-invoke the routed recovery skill. If the route itself

fails validation twice, HALT with RECOVERY_HALT_HUMAN_DECISION in the log.

1. AIO (academic-aio) is OFF by default in --e2e, because AI-search visibility is a

pre-submission concern and running it on every autonomous iteration would waste tokens and invite silent rewrites that violate the skill's "never edit silently" contract. Enable it only when the user explicitly adds --aio (or the pipeline is preparing a preprint / GitHub README / HF card alongside submission). When enabled, schedule it after /humanize so the checklist anchors on QC-confirmed and human-readable text, and surface the PASS/PARTIAL/FAIL report to the user — never auto-apply its edits.

1. After each skill completes, run post-skill validation (see below); once it passes,

proceed to the next skill without asking.

Standard Pipeline: Data → Manuscript

1. /analyze-stats → analysis/tables/*.csv, analysis/figures/*, analysis/_analysis_outputs.md, analysis/analyze.py
2. /make-figures --study-type {type} → reads analysis/_analysis_outputs.md → analysis/figures/*.pdf, analysis/figures/*.png, analysis/figures/_figure_manifest.md
3. /write-paper --autonomous (if --e2e) → reads analysis/ → manuscript/manuscript.md (DOCX rendering delegated to step 7)

• Phase 7.4 internally calls /self-review --json --fix → qc/self_review.md

1. /check-reporting → reads manuscript/manuscript.md → qc/reporting_checklist.md + qc/reporting_checklist.json (Part D JSON; called within write-paper Phase 7, but orchestrator verifies output)
2. /verify-refs → reads manuscript/manuscript.md → qc/reference_audit.json (sole output; row-level status in records[])
3. /self-review --json --fix → reads manuscript/manuscript.md → qc/self_review.md + auto-fix (called within write-paper Phase 7.4, but orchestrator verifies final output)
4. /manage-refs (Workflow A pandoc citeproc, or B Zotero CWYW) → reads manuscript/manuscript.md + manuscript/_src/refs.bib → manuscript/manuscript_final.docx + qc/xref_audit.json. Submission gate: check_xref.py --strict must pass (no MISSING_DOCX / MISSING_BODY / MISMATCH).

Post-Skill Validation

After each skill completes, verify that expected output files exist, then pass the discovered file paths to the next skill as context. If validation fails, report the error and do NOT proceed to the next skill.

On validation failure:

• Log the failure: which skill, which output was missing, any error messages.
• In --e2e mode: report the error in qc/_pipeline_log.md and STOP. Do not proceed to the next skill. Output: "Pipeline halted at {skill}: {missing output}. Check the skill's output and re-run."
• In interactive mode: report the error and ask the user how to proceed.

REPORT.md Generation

At the termination of every --e2e invocation — whether the pipeline completed, halted at pre-flight, or halted on post-skill validation — the Worker MUST write manuscript/<id>/REPORT.md using the template at ${CLAUDE_SKILL_DIR}/references/report_template.md.

• Copy every section of the template verbatim. Never delete a section. Empty fields are

filled with (none) or (unknown) — never omitted, never collapsed.

• The §"Pipeline log" entry is a 5-line summary of qc/_pipeline_log.md (Dialogue

node defaults applied, skill invocations, halt reason if any) — not a paste of the full log.

• The §"Tier-3 Blocked Items" hook-vs-prompt-guard split is mandatory — see

§"Tier-3 Worker Guard" below.

• The §"Next safe command" line is the literal command the user can copy to

resume the next phase. Do not editorialize.

• REPORT.md is the single artifact the user reviews; every other QC output is

linked from it.

Tier-3 Worker Guard

The following actions are permanently forbidden inside --e2e autonomous flow. On detection, the Worker halts the pipeline and records the attempt under REPORT.md §"Tier-3 Blocked Items" as tier3_pending: <command>. Hook-confirmed blocks and prompt-only blocks are listed separately so a future hook regression cannot silently re-open a prompt-only block.

Hook-confirmed (where a Tier-3 confirm hook is installed):

• gws gmail +send / +reply
• YouTube upload

Prompt / skill guard only (no hook coverage — Worker prompt enforces):

• git push, gh pr create
• MCP Gmail send, MCP Calendar send
• MCP GitHub create-pr
• /sync-submission build external publication paths
• Phase 8 submission DOCX auto-build / journal submission
• Senior mentor automatic email reply

git commit is allowed; a subsequent git push attempt halts. Circulation emails are saved as a Gmail Draft only — never sent.

Data Flow Contract

Read ${CLAUDE_SKILL_DIR}/references/data_flow_contract.md when chaining a skill and you need what it reads or writes (the Standard Pipeline above already names its own files).

Post-E2E: Journal Selection & Submission Prep

After the E2E pipeline completes (or when the user requests journal targeting), this workflow is available. It is NOT part of --e2e: it runs only on explicit user invocation, because it needs the user's journal selection.

1. /find-journal → top 5 recommendations based on manuscript/manuscript.md abstract
2. /verify-refs → block fabricated or mismatched references before packaging
3. User selects a journal → create submission/{journal_short}/ directory
4. /sync-submission build --journal {journal_short} → create or refresh the derived manuscript package from the canonical manuscript
5. Generate inside submission/{journal_short}/:

• cover_letter.md: via /write-paper Phase 8+
• checklist.md: journal-specific submission checklist
• manuscript_final.docx: re-rendered by /manage-refs for the target journal (if format differs)

1. /self-review with the selected journal as the target → journal scope-aware final pass (not /peer-review, which reviews other authors' work only)

PHI Safety Gate

Before routing to any data-handling skill (clean-data, analyze-stats, make-figures), check if the data might contain PHI:

1. For each CSV/Excel file the task will read that is not itself a *_deidentified.* output (a

de-identified copy of one file says nothing about the others), ask: "Does the data contain patient identifiers (PHI)? (names, national ID / RRN, date of birth, contact details, etc.)"

• If yes → Route to /deidentify first, then continue to the originally requested skill

using the *_deidentified.* output file

• If no, or the user confirms the data is already de-identified → Proceed directly

1. De-identification is an INTERACTIVE process requiring the researcher's active participation.

Warn: "De-identification requires the researcher's direct review. You must run the script in the terminal and verify each item."

Context Detection

Before routing, check for context clues in the working directory:

Guardrails

• Never invent a skill. Only route to skills listed in the Available Skills table.
• Respect existing state. If a project scaffold exists, do not re-initialize it.