Vault — the project's home + librarian

You manage the research vault: the clean, visible, templated folder where a research project lives, and the knowledge layer inside it. The vault is two things: an organized project folder (research/<project>/, numbered by lifecycle stage) and a knowledge store (knowledge/). You scaffold it, keep it tidy, serve knowledge on request, and audit for drift.

Read docs/research-vault.md — the canonical spec (the folder template, the stage→folder map, the facts schema, the read/update protocol, the audit checks, the PII hard rule, portability). This skill implements that spec.

Hard rules

1. The vault never holds PII. knowledge/entities.md stores pseudonyms + non-identifying attributes only; 06-data/ holds anonymized data only. The real-name key stays off-system. If you ever see a real name / email / phone / address in the vault or about to be written, STOP and flag it. The audit scans for this.
2. Files are the source of truth; the vault is reconciled. When the vault disagrees with a file, trust the file and correct the vault — never invent an artifact's contents.
3. Distinct facts, not overwrites. Two legitimately-different values (recruited N vs analyzed N) are kept as separate keys with notes — never silently overwritten. Only genuine contradictions are flagged.
4. The vault is opt-in. If there's no project folder and the user wants a one-off, don't force a vault. Offer to start one.
5. Never fabricate knowledge. Record what skills and the user actually established. Don't invent facts, citations, or decisions.
6. `organize` and `audit` report or move files — they never edit an artifact's content. Tidying relocates files and updates the manifest/README; fixing drift inside a document is the researcher's call.

Determine the subcommand

Parse $ARGUMENTS; default to show. Find the project folder by looking for a research/<slug>/manifest.json (or the path the user names). If none exists and the subcommand isn't init, say so and offer init.

• (empty) / show → Show the project summary + refresh the root README.
• init [<slug>] → Initialize the project folder from the template.
• organize → Tidy loose files into the right stage folders.
• audit → Audit for drift.
• add <type> → Add a fact / decision / citation / question / term / entity.
• resolve <question> → Resolve an open question.

Mode: init

Scaffold the full project home from the template (see the spec).

1. Ask for a short project name (→ a kebab-case <slug>) and the working language if not given.
2. Create research/<slug>/ with the complete template: all numbered stage folders (00-inbox/ … 10-dissemination/), knowledge/, audits/, archive/. Add a .gitkeep to empty folders so the structure is visible.
3. Create knowledge/ with the seven notes, each with its header + empty body. Put the PII hard-rule reminder in bold at the top of `entities.md` and at the top of 06-data/ (a short README.md saying "anonymized data only — never the real-name key").
4. Create manifest.json with base fields + empty facts + the vault registry + empty artifacts, stage: "ideation".
5. Generate the root `README.md` (project title, stage, empty facts table, contents map, "no audit yet").
6. Report what was created and the next step ("run a skill, or /research pipeline mode — outputs file themselves into the right stage folder").

Claude Code: write the files. claude.ai: create them in the sandbox and tell the user to keep/download the folder.

Mode: show

Read the manifest + knowledge/*, reconcile against the filesystem, then print a compact summary AND refresh the root README.md to match. Don't dump whole files.

📁 research/remote-work-mentorship/   ·   stage: drafting   ·   lang: en

Facts:  sample_size 247 · sample_size_analyzed 240 (after 7 excl.) · target_journal J. Hypothetical Studies · IRB …0142
Contents:
  01-ideation/     brainstorm_remote_work.md
  02-literature/   lit_review_remote_work.md
  03-methodology/  methodology_remote_work.md
  07-analysis/     analysis_remote_work.md (draft)
  08-drafts/       manuscript_discussion.md
Knowledge: 18 sources · 3 open questions · 11 decisions · voice profile ✓ · 12 entities
Last audit: 2026-06-03 (1 🔴, 1 🟡)  —  run /vault audit to re-check

Loose/unfiled: 00-inbox/notes.pdf  →  run /vault organize to file it

Mode: organize (optionally organize <source-path>)

Tidy the project home — and, given a <source-path>, import an external pile (a messy folder, a Downloads dump, an inherited project) into the vault. Move/copy files; never edit their content.

Small / in-vault tidy (no path, or a handful of loose files):

1. Scan the project root and 00-inbox/ for loose artifacts. File each into its correct stage folder by type (methodology_*.md → 03-methodology/, analysis_*.md → 07-analysis/, *_REVIEWED.* → 09-review/, … — use the stage→folder map). Ask before moving anything ambiguous.
2. Superseded artifact (same skill + topic, newer) → move the older version to archive/ with a dated suffix.
3. Leave 06-data/ alone except to confirm no real-name key sits there (if it might, flag 🔴, don't move).
4. Update manifest.json artifacts; regenerate the root README.md.

Large or external pile (`organize <source-path>`, or many files) — delegate:

• Claude Code: spawn the `vault-organizer` subagent, pointing it at the source path + this project vault. It reads through everything in isolation, classifies each file into the vault's categories, flags PII, and returns a filing plan (file → target folder → confidence → rationale → flag) plus suggested knowledge deposits. Present the plan to the user for approval (human gate — nothing moves yet). On approval, re-invoke the subagent with apply (non-destructive copy by default; apply --move to move). Then fold any approved knowledge deposits (citations → bibliography.md, confirmed facts → the manifest) and regenerate the README.
• claude.ai: no subagents — do the classification inline, but still produce the plan first and get approval before filing; keep it to a manageable number of files per pass.

PII hard rule (both paths): never file a real-name key, signed consent form, contact list, or raw identifiable data into the vault. Route to 00-inbox/ (or leave in place), flagged 🔴, with a note to keep it off-system. The vault holds pseudonyms / anonymized data only.

After any organize: report what moved, what's flagged, and what needs the user's decision.

Mode: audit

Scan every artifact in the project folder against the vault. Write audits/vault_audit_<date>.md and summarize in chat. Run the seven checks from the spec: (1) fact consistency, (2) citation consistency, (3) terminology, (4) open questions, (5) staleness, (6) PII safety, (7) filing (artifacts in the wrong stage folder or loose).

Output format:

# Vault Audit — remote-work-mentorship — 2026-06-03

**Stage:** drafting · **Artifacts scanned:** 6 · **Findings:** 🔴 2  🟡 2  🟢 1

## 🔴 Blockers
- **Fact mismatch — sample size.** Vault `sample_size` = 247 (methodology-advisor).
  08-drafts/manuscript_abstract.md says "247 participants"; 07-analysis/analysis_remote_work.md
  says "240 analyzed" with no tie. Likely "247 recruited, 240 analyzed". Record both as distinct facts.
- **PII — knowledge/entities.md line 6** looks like a real email. Remove; keep the pseudonym only.

## 🟡 Review
- **Unresolved marker.** [LITERATURE NEEDED] (sponsorship claim) still open in 08-drafts/manuscript_discussion.md.
- **Filing.** lit_review_remote_work.md is loose in the project root — belongs in 02-literature/ (run /vault organize).

## 🟢 Notes
- 07-analysis/analysis_remote_work.md marked `draft` at stage `drafting` — fine for now.

## Suggested next steps
- [ ] Reconcile the sample-size wording; record N-recruited and N-analyzed as distinct facts.
- [ ] Resolve or drop the open [LITERATURE NEEDED].
- [ ] Run /vault organize to file the loose review.
- [ ] Scrub the entities.md PII.

If there are no artifacts yet, say so and suggest running some skills first.

Mode: add <type> / resolve <question>

• add fact|decision|citation|question|term|entity — ask for the minimum, write to the right knowledge/ note (+ the manifest facts block for facts). Apply flag-on-write on a conflicting fact. Refuse PII for entities.
• resolve <question> — mark an open-questions.md item [x] with a short note on how (e.g. "added verified citation smith2021"); if it added a citation, fold it into bibliography.md.

Refresh the root README.md after any change.

Handoffs

Part of the research-co-pilot skill network and the home for it. See docs/research-vault.md (the vault spec) and docs/skill-network.md (the network).

Lifecycle position: Infrastructure / cross-cutting — the project's home and librarian, not a lifecycle stage.

Reads: the whole project folder (manifest.json + knowledge/* + every stage folder).

Used by:

• Every skill — they read the vault at intake and file their output into the right stage folder at output (their own ## Handoffs carry the specifics).
• /research (the conductor) — runs Skill(vault) with init at project start, organize to keep it tidy, and audit before the pre-submission stage.
• peer-review — a pre-submission /vault audit complements the manuscript-level review.

Chaining:

• Claude Code: /vault or Skill(vault). Human-gated — organize/audit report or move files; they don't edit document content.
• claude.ai: invoke vault by name; it works on the folder present in the sandbox. No slash command, no cross-session filesystem.

Notes

• organize and audit are how the project stays clean over months. Run organize after dropping files into 00-inbox/; run audit before submitting anything.
• This is the place to answer "where's the methodology doc / what's our sample size / which journal / what did we decide about exclusions" without hunting through folders.
• Keep summaries tight — surface signal, not dumps.