bip-ms

name	bip-ms
description	Cold-start for a manuscript session — the paper is the source of truth and shared context; discuss results, orchestrate research through issues/PRs, and update the paper as threads complete

/bip-ms

Cold-start for a manuscript session. Run from a TeX repository (e.g. ~/writing/cosine or ~/re/peak-origins/paper). The manuscript is the source of truth about the project: one should be able to understand the project's state by reading it. This session practices manuscript-driven development — its first job is to act as a scientific discussant and orchestrate the research (in the context of the paper, directed through issues and PRs), updating the manuscript itself as each thread of research completes.

Use this at session start to establish context. For mid-session updates, use /bip-ms-poll.

Conventions

Naming

• iN = issue #N, pN = PR #N. Never bare #N.
• First mention in bullet lists: full URL inline.
• EPIC issues are referenced as EPIC-N when ambiguous across repos.

Session role

The manuscript is the source of truth about the project — it holds the background, framing, and current understanding, and one should be able to grasp the project's state by reading it. It is the shared context you reason from, not a running log you append to.

Within that context, the agent's first job is to be a scientific discussant and to orchestrate the research: read new results closely enough to argue about them as a collaborator, judge whether a result holds up and what it means, weigh it against related work and against what the manuscript already claims, and decide what should happen next. This is manuscript-driven development: the PI directs the science at the level of the paper while agents handle the implementation.

Research is directed through issues and PRs, not through constant edits to the paper. Comment on PRs/issues to request analyses, draft issues for the implementor (via the Issue quality gate), and advise the code-side owner on what to build next.

The manuscript is updated when a thread of research is complete — you then reconcile the finished result into the paper (the manuscript prevails on disagreement; cf. /bip-ms-audit), rather than appending every incremental finding as it lands. Until then the paper stays the stable context the discussion runs against.

Supporting mechanics, in service of the above: monitor tracked EPICs, pull clones and run Makefile fetch targets, import SVGs into prep-figures/, open HTML notebooks in Chrome.

Out of scope — a safety boundary, not a limit on what you may think about or direct: this session does not itself run experiments or modify remote server state (other agents are actively working there — see the next rule). Guiding, scoping, and requesting that work is central and in scope. Do not create issues on your own initiative — surface gaps to the user; when the user explicitly asks to file one, follow the Issue quality gate below.

Never modify remote server state. Do not run snakemake (even dry-run), zig build, git pull, snakemake --unlock, or any write command on remote servers (ermine, quokka, orca, etc.). Other agents are actively running experiments there. SSH is fine for read-only inspection (ls, cat, head, grep, checking file dates/sizes), but never run anything that modifies files, locks, or builds. Report what you observe and let the user or the responsible agent handle modifications.

Issue quality gate: When the user asks to file an issue during a manuscript session, always run /bip-issue-check on the draft before submitting via /bip-issue-file. Do not shortcut to gh issue create directly, regardless of perceived simplicity.

Configuration

The skill reads .ms-config.json from the manuscript root (gitignored).

{
  "manuscript": "main.tex",
  "prep_figures_dir": "prep-figures",
  "tracked_repos": [
    {
      "repo": "matsen/peak-origins",
      "local_path": "~/re/peak-origins",
      "epics": [281, 295],
      "fetch_cmds": [
        "make remote-fetch DIR=experiments/2026-03-benchmark/results",
        "make artifacts-pull DIR=figures/final"
      ],
      "remote_watch": {
        "host": "orca02",
        "paths": [
          "~/re/peak-origins/experiments/2026-03-benchmark/results",
          "~/re/peak-origins/figures/final"
        ],
        "patterns": ["*.svg", "*.html", "*.tsv"]
      }
    }
  ]
}

Fields:

• manuscript: Main TeX file to edit
• prep_figures_dir: Where SVGs go for inkscape conversion (default: prep-figures)
• tracked_repos: List of code repositories this manuscript depends on
  • repo: org/repo for gh commands
  • local_path: Local checkout of the repo
  • epics: EPIC issue numbers to monitor
  • fetch_cmds: Shell commands to run inside local_path to fetch specific result directories from remote. Each command should be selective — pull only the results the manuscript needs, not the entire experiment tree. Uses the repo's own Makefile targets (which know the remote host and rsync config).
  • remote_watch (optional): Configuration for the persistent result monitor (Step 5). Fields:
    • host: SSH hostname for the remote server
    • paths: Remote directories to watch for new results
    • patterns: File glob patterns to match (e.g. *.svg, *.html, *.tsv)

Updating fetch_cmds: As new experiments land and the manuscript needs different results, update this list. Old entries can be kept (re-fetching is idempotent) or removed when no longer relevant.

If the file does not exist, stop and ask the user:

1. What is the main TeX file? (e.g. main.tex)
2. Where is prep-figures/? (or equivalent)
3. Which code repos does this manuscript track? For each:
   • GitHub org/repo
   • Local checkout path
   • EPIC issue numbers
   • Which result directories should be fetched? (check the repo's Makefile for remote-fetch, artifacts-pull, etc. — run grep -E '^[a-z].*:' Makefile to see targets)

Then create .ms-config.json and proceed.

Workflow

Step 0: Load config and memory

cat .ms-config.json

Read MEMORY.md from the auto-memory directory. For each memory file listed there, read it and apply:

• Project memories (e.g., project_dasmfit_status.md): Use as the baseline for what's done vs pending. Cross-check against live GitHub state — memories can be stale. When a memory says "PR open" but gh pr view says merged, trust GitHub and update the memory.
• Pending decisions (e.g., project_pending_decisions.md): Check whether they've been resolved since last session. Remove resolved items, flag unresolved ones in the status table.
• Feedback memories: Apply silently — these are behavioral guidelines, not status items.

After loading, briefly note what the memory says the current state is, then verify it in Steps 1-4. Do not trust memory over live state.

Step 1: Check manuscript state

git status --porcelain | head -10
git log --oneline -5

Note any uncommitted changes or recent work.

Step 2: Fan out per-repo scanners

For each entry in tracked_repos, dispatch one general-purpose subagent in parallel — single message, multiple Agent tool calls. Follow the dispatch pattern in SUBAGENT-SCAN.md (bipartite repo root). Per-repo (not per-EPIC) granularity avoids racing on git pull when one repo has multiple EPICs.

Brief for each subagent:

Scan repo <org/repo> for the manuscript session. Local path: <local_path>. EPIC numbers: <epics>. Fetch commands: <fetch_cmds>.

Tasks:

1. git -C <local_path> pull --ff-only origin main (continue on failure; note it).
2. From <local_path>, run each fetch_cmd.
3. For each EPIC, gh issue view <N> --repo <org/repo> --json title,body,updatedAt. Parse Status dashboard, Key findings, and active clone assignments.
4. gh pr list --repo <org/repo> --search "is:merged sort:updated-desc" --limit 10 --json number,title,mergedAt,body. Note which produced figures or quantitative results.
5. Find SVGs and HTMLs under <local_path> modified in the last 120 minutes. For each, identify the EPIC or PR that produced it.

Return under 400 words, structured per SUBAGENT-SCAN.md:

• changes_since_baseline: EPIC items newly checked, new key findings, PRs merged that produced relevant results
• active_items: clone assignments from EPIC tables, brief status
• new_artifacts: paths to new SVGs/notebooks with EPIC/PR source
• action_candidates: figures to import, notebooks to open, text to draft
• surprises: anything else, including RECOMMEND DEEPER LOOK flags

Quote specific EPIC/PR lines that show what changed — do not paste full bodies. Use Read (not grep excerpts) for any PR body or finding you cite.

If any report has zero surprises and zero changes_since_baseline, dispatch a follow-up with a narrower question ("what changed in the last 7 days on this EPIC even if no boxes were checked?") before concluding "all quiet" for that repo.

Step 3: Build status table

Compose from the per-repo subagent reports (do not paste their prose verbatim). Cross-reference the reports against each other — the primary sees all of them; the subagents don't. Display a summary of what's happening across all tracked repos:

Repo	EPIC	New Results	Active Work	Action Needed
peak-origins	i281	2 new SVGs	3 clones active	Import figures
peak-origins	i295	notebook updated	PR in review	Draft results

Then list specific new artifacts:

New figures to import:

• peak-origins/experiments/benchmark/results/fig3-comparison.svg (fetched just now)

New notebooks to review:

• peak-origins/experiments/benchmark/results/analysis.html (from i281)

New findings to write up:

• EPIC i281 finding #7: "Clamping improves convergence by 3x"

Step 4: Propose actions

Based on what's new, propose concrete next steps:

1. Import figures: Copy new SVGs to prep-figures/, run make pdf-figures
2. Open notebooks: Open HTML notebooks in Chrome for review
3. Draft text: Summarize findings in bullets, then draft results/methods
4. Note gaps: If manuscript work reveals missing experiments or analyses, note them for the user; do not file issues on your own initiative. If the user asks you to file one, follow the Issue quality gate (/bip-issue-check → /bip-issue-file).

Wait for user confirmation before taking action.

Step 5: Start result monitor

If any tracked repo has a remote_watch configuration, offer to start a persistent Monitor that watches remote servers for new result files via SSH. This provides real-time awareness of experiment completion without waiting for the next /bip-ms-poll cycle.

Use the Monitor tool with persistent: true:

description: "Remote experiment results"
persistent: true
command: |
  # Built from .ms-config.json remote_watch entries
  touch /tmp/.ms-monitor-baseline

  while true; do
    CHANGED=0
    # For each tracked repo with remote_watch:
    #   HOST=<remote_watch.host>
    #   PATHS=<remote_watch.paths joined by space>
    #   PATTERNS=<-name "*.svg" -o -name "*.html" etc.>
    #
    # SSH to check for new files (read-only):
    NEW=$(ssh -o ConnectTimeout=5 "$HOST" \
      "find $PATHS \( $PATTERNS \) -newer /tmp/.ms-monitor-mark-\$USER 2>/dev/null" \
      || true)
    if [ -n "$NEW" ]; then
      echo "$NEW" | while read f; do
        echo "NEW on $HOST: $f"
      done
      CHANGED=1
      # Update remote marker
      ssh -o ConnectTimeout=5 "$HOST" "touch /tmp/.ms-monitor-mark-\$USER" || true
    fi

    [ "$CHANGED" -eq 0 ] || true
    sleep 60
  done

The conductor dynamically builds this script from .ms-config.json at startup — the template above shows the structure. Each repo's remote_watch contributes one SSH check block.

When a notification arrives showing new files:

1. Run the repo's fetch_cmds to pull the new results locally
2. Check if the files are SVGs/notebooks and react per the import workflows below
3. Notify the user with a summary of what arrived

Prerequisites: SSH access to the remote host with key-based auth (no password prompts). If SSH fails, the monitor logs the error to stderr and retries on the next cycle.

Alternative: sshfs + fswatch — For lower latency, mount the remote result directories via sshfs and use fswatch locally:

sshfs host:/remote/results /local/mount -o reconnect,ServerAliveInterval=15
fswatch --batch-marker=EOF /local/mount --include '*.svg' --include '*.html' --exclude '.*'

This gives true real-time notification but requires sshfs (brew install macfuse sshfs) and is less robust on flaky networks. The SSH poll approach is the default recommendation.

Figure import workflow

When importing an SVG from a fetched result:

PREP_DIR=$(jq -r .prep_figures_dir .ms-config.json)
cp "<local-path>/figure.svg" "$PREP_DIR/"
make pdf-figures

Then check if the figure is already referenced in the manuscript. If not, suggest where to add it and draft the \includegraphics block.

Notebook review workflow

When a new HTML notebook is found:

open -a "Google Chrome" "<path-to-notebook.html>"

Tell the user what notebook was opened and which EPIC/issue produced it. After they review, ask which plots or findings to incorporate.

Text drafting workflow

When drafting new results or methods text:

1. Read the relevant EPIC findings, PR descriptions, and experiment results
2. Read the current manuscript to understand style, notation, and structure
3. Present the key points as a bullet-point summary and ask the user which to include and where in the manuscript they belong
4. After confirmation, draft the paragraph(s) in LaTeX
5. Run the @scientific-tex-editor agent on the new text for style review
6. Present the edited draft for final approval before inserting into the TeX file

Remote server awareness

Experiment results and data live on remote servers (orca/ermine), not locally. When validating claims about experiment results — especially when drafting or checking issues — use ssh to verify:

• That data files exist at the stated paths
• That intermediate outputs (filtered FASTAs, DAG protobufs) match what READMEs and Snakefiles describe
• That result TSVs have the expected columns and row counts

Do not assume local READMEs and Snakefiles are the full picture. Experiments may produce filtered or transformed intermediates that change the data (e.g., filtered FASTAs with different taxa, condensed DAGs with extra leaves). Always check the actual files on disk.

Error handling

• Config missing: Ask user to configure (see above)
• Local path doesn't exist: Warn — repo may need cloning
• Git pull fails: Warn (dirty worktree? diverged?) and continue with stale state
• Fetch cmd fails: Warn — remote may be unreachable or path may have changed. Report and continue.
• EPIC not found: Check if issue number is correct
• No new results: Report "all quiet" and suggest checking back later

Session end

Before ending a manuscript session or resetting context, run /bip-ms-tuckin to persist session state to memory and commit any manuscript changes.