init-project-research

name	init-project-research
description	Use when you need to bootstrap a full research project with directory scaffold and Overleaf symlink.
allowed-tools	Bash(mkdir*), Bash(ln*), Bash(ls*), Bash(git*), Bash(touch*), Bash(jq*), Bash(uv*), Bash(curl*), Bash(wget*), Read, Write, Edit, Glob, Grep, Task, WebSearch, WebFetch, AskUserQuestion
argument-hint	[project-name or no arguments for guided setup]

Init Project Research

Interview-driven skill that scaffolds a research project directory, creates an Atlas topic, syncs to vault (Atlas + Pipeline + Venues), and integrates with the user's Task Management system.

Scope pre-flight. During the interview (Phase 1), read the global paper scope checklist at ~/Task-Management/.context/paper-scope-checklist.md (resolve the TM root via cat ~/.config/task-mgmt/path) and apply its eight gates to the proposed project — confirm a one-sentence research question and right-sized contributions before scaffolding. Flag (don't block) any failed gate so the project starts with scope discipline set.

When to Use

• Starting a new research paper or project from scratch
• When the user says "new project", "set up a project", "init project", "bootstrap project"
• After deciding to pursue a new research idea that needs its own folder

Modes

Invocation	Behaviour
/init-project-research (no args)	Guided: full interview, no auto-detection unless CWD already contains project files
/init-project-research <name>	Targeted: uses <name> as the proposed slug, runs auto-detection if the directory exists, still walks the interview

Both modes execute Phases 1–10 in order. The argument only seeds the slug guess in Round 1.

Overview

Ten phases, in order:

1. Interview — gather project details via three structured rounds
2. Validate — pre-scaffold checks (atlas dup, sibling directories, existing files)
3. Scaffold — create directory structure based on project type
4. Seed files — populate CLAUDE.md, README.md, .gitignore from interview answers
5. Overleaf symlink — link paper/ to Overleaf folder via mkdir + symlink
6. Git init — initialise repo and make first commit (conditional)
7. Atlas sync — create Atlas topic file, vault atlas entry, venue links
8. Task Management integration — update context library files
9. Literature & Discovery — run /literature + in parallel
10. Confirmation — report what was created

---

Phase 1: Interview

Use AskUserQuestion for structured input. Three rounds to avoid overwhelming.

Pre-Interview: Auto-Detection

Before asking questions, scan the project directory (if it already exists) for metadata:

• LaTeX files — extract \title{}, \author{}, \begin{abstract}, \begin{keyword} from .tex files
• Markdown files — check for README.md, notes.md with # Title headings
• BibTeX files — note .bib presence for later phases
• Overleaf symlink — if paper/ is a symlink, follow and scan the target

Present detected values as the first option (marked "Detected from paper") in interview questions. Always allow override. If the directory doesn't exist yet, skip auto-detection.

Round 1 — Core Identity

1. Project slug — kebab-case identifier (e.g., costly-voice). Folder name on disk is Title Case with spaces (Costly Voice). Confirm the derived folder name.
2. Working title — full paper/project title.
3. Authors / collaborators — names and affiliations.
4. Research area — which parent folder under Projects/. Scan for existing theme folders and present as options. Also offer "New topic folder" and "Other location".
5. Target venue — journal, conference, or preprint. Ranking lookup, deadline capture, and CSV paths: references/round-1-venue.md.
6. Deadline — submission deadline if known.

Round 2 — Setup Details

1. Overleaf project — exists or create? Read root from ~/.config/task-mgmt/overleaf-root (fallback ~/Apps/Overleaf/). Creating a folder under that root auto-creates the Overleaf project. Symlink details deferred to Phase 5.
2. LaTeX template — scan Task Management/templates/ for options. Default: Working Paper (templates/latex-wp/). Also offer "None".
3. Overleaf external sharing link — read-only URL for collaborators.
4. Git repository? — Local git (Recommended) / GitHub remote / No git.
5. GitHub release repo? — only ask for Experimental, Computational, or Mixed projects. Yes / No / Later. Convention details: references/round-2-github.md.
6. Project type — Experimental (code/, data/, output/) / Computational (src/, tests/, experiments/, results/) / Theoretical (minimal) / Mixed.
7. HPC scaffold? — only ask for Experimental, Computational, or Mixed. Yes / No / Later. Sbatch templates, sync scripts, project conventions: references/round-2-hpc.md.

Round 3 — Research Content

Paper type, abstract, key research questions, then paper-type-specific questions (empirical/theoretical/methodological/mixed) adapted from Lopez-Lira's idea evaluation template.

Full question set: references/interview-round3.md.

---

Phase 2: Validate

Pre-scaffold checks. Run before any directory creation. If any near-match is found, present the list to the user and confirm whether to proceed, merge, or extend. Do not silently scaffold alongside a duplicate.

1. Atlas topic search — grep for near-matches by title, slug keywords, theme:

   grep -ril "<title-keyword>" ~/vault/atlas/ 2>/dev/null
   

2. Sibling directory listing — list siblings in the parent theme folder, flag near-duplicates (same keywords, same stem with different venue suffix, typo-distance ≤ 2):

   ls -d "$RESEARCH_ROOT/<theme>/"*/ 2>/dev/null
   

3. Paper sub-project check — if scaffolding a new paper-{venue}/ inside an existing project, list existing paper*/ dirs and check for manuscript-content overlap (not just venue) before creating.
4. Existing-files reorganisation — if the target directory already exists with files, scan (excluding .claude/), read documents, present a reorganisation plan: keep in place / move to docs/ / move to docs/readings/ / move to paper/ / move to to-sort/ / absorb into seed files. Wait for approval, execute, double-check before deletions. Use any extracted interview content to reduce Round 3 questions.

If the directory doesn't exist, create it and proceed.

---

Phase 3: Scaffold Directory

Naming Convention

• Slug (kebab-case): example-project — citation keys, git refs.
• Folder name (Title Case with spaces): Example Project — directory on disk.

Hard Rules

• paper/ is for LaTeX source files ONLY. No code, data, scripts, computational artifacts. See .claude/rules/overleaf-separation.md.
• Research papers are drafted in LaTeX (.tex), never Markdown. Seed paper-{venue}/paper/main.tex from the LaTeX working-paper template. No Markdown drafts under paper*/ — papers compile via /latex and sync to Overleaf. Markdown is reserved for README, notes, and context files outside paper*/.

Common Core + Conditional Structure

Common core (always created): CLAUDE.md, README.md, MEMORY.md, .gitignore, .context/, .claude/, docs/ (literature-review, readings, venues), log/, paper-{venue}/ (with symlink + correspondence/referee-reviews/), github-repo/ (optional), knowledge/, reviews/INDEX.md (manifest only — per-scope/per-check subdirs created lazily, per rules/review-artefact-routing.md), correspondence/editorial/, correspondence/referee-reviews/, to-sort/.

Note: the legacy REVIEW-STATE.md at project root + reviews/ empty dir + correspondence/internal-reviews/ layout is superseded by rules/review-artefact-routing.md. New projects scaffold the new layout directly; existing projects retrofit via /tidy-project-reviews. Per-paper backup/ directories are created lazily by the LaTeX-compile PostToolUse hook and are gitignored via paper-*/backup/.

Project type	Adds
Experimental	code/python/, code/R/, data/raw/, data/processed/, output/{figures,tables,logs}/
Computational	src/<project>/, tests/, experiments/configs/, results/, pyproject.toml, .python-version
Theoretical	—
Mixed	Prompt user

HPC scaffold (optional, when Round 2 Q7 = Yes): adds hpc/{submit.sbatch,sweep.sbatch,env-setup.sh,sync-up.sh,sync-down.sh,README.md}. Full template list and sbatch invariants: references/round-2-hpc.md.

Venues: seed docs/venues/<venue-slug>/submission/; conference venues also get a submission checklist.

Preprint targets (arXiv / SSRN / OSF / institutional repos): seed the atlas topic's outputs[*] with venue: arXiv (or equivalent), format: Preprint, status: Planned, plus an optional internal target date. Do NOT seed a vault submission file for the preprint target — preprint posts are not venue submissions per rules/preprint-vs-submission.md. Vault submissions are reserved for events with reviewer pipelines (journals, conferences). A project with only a preprint target gets zero vault submission files at init.

Conference/journal targets: seed each outputs[*] with venue: '[[Name]]' (slug must resolve to a ~/vault/venues/ file) + format + status + paper_title (kept in sync with the registry canonical_title). When you seed a near-term Conference/Workshop target at a submission-active status (or with a known edition), also set cycle: <Venue> <edition-year> (e.g. cycle: NeurIPS 2026) per rules/atlas-status-vocabulary.md § submission-join completeness — journals get no cycle. Idea-stage targets may omit cycle until an edition is committed.

Python tooling: always uv — never bare pip, python, or requirements.txt.

Full scaffold tree, hook details, .gitkeep placement, implementation commands: references/scaffold-tree.md.

---

Phase 4: Seed Files

CLAUDE.md vs README.md

• CLAUDE.md — instructions for Claude: safety rules, folder structure, conventions, symlink paths. Follow the lean-claude-md rule.
• README.md — human-readable overview: title, authors, abstract, status checklist, links.

Both overlap on basic metadata but diverge in purpose.

Full templates: templates/seed-files.md.

File	Purpose
CLAUDE.md	Claude instructions: overview, venue, RQs, setup, conventions
README.md	Human overview: title, authors, abstract, links, status
.gitignore	Standard ignores: OS, IDE, data, paper, Python, R, LaTeX
MEMORY.md	Knowledge base: notation, estimands, decisions, pitfalls
reviews/INDEX.md	Review-artefact manifest. Header only at scaffold; populated by review-producing skills/agents writing to reviews/<scope>/<check>/<YYYY-MM-DD-HHMM>.md where <scope> is the paper name (e.g. paper-jtp) or _project for project-level reviews, and <check> is the producer slug (e.g. paper-critic, proofread). Maintained by /review-recap. See rules/review-artefact-routing.md. Supersedes the legacy REVIEW-STATE.md at project root.
.context/current-focus.md	Initial "just initialised" state
.context/field-calibration.md	Per-project domain profile placeholder (/interview-me populates)
.context/project-recap.md	Research design notes
.claude/hooks/copy-paper-pdf.sh	PDF copy hook
log/YYYY-MM-DD-HHMM-setup.md	Initial setup log
docs/pipeline-manifest.md	Experimental/Computational only — script/data/figure manifest. Template: templates/pipeline-manifest.md
run_all.sh	Experimental/Computational only — multi-language pipeline executor. Template: templates/run-all.sh. chmod +x after creation.

Permissions Sync

After writing .claude/settings.local.json, merge global permissions from ~/.claude/settings.json into it so the new project starts with full permissions from day one. jq union command and deny-array handling: references/paper-directory.md § Permissions Sync.

---

Phase 5: Overleaf Symlink & Template

Nested pattern: each paper submission is a real directory at project root (e.g., paper-ccs/) containing a paper/ symlink to the Overleaf folder. Venue-specific files (checklists, cover letters, R&R responses) live alongside the symlink without being synced to Overleaf.

Overleaf naming: Paper {THEME_PREFIX} {Title Cased Slug} ({VENUE}) — theme prefix AND venue suffix both required, even for single-venue papers. Examples: Paper T1 Example Topic One (CCS), Paper T2 Example Topic Two (NeurIPS 26).

Create the Overleaf folder via mkdir under the root from ~/.config/task-mgmt/overleaf-root. Overleaf auto-creates a project from a new folder. Never rename or delete Overleaf folders — see .claude/rules/overleaf-separation.md.

Backup: create backup/<paper-dir-name>/ for each paper. Daily backup-overleaf-papers.sh populates them.

Full nested structure, theme-prefix table, symlink commands, backup loop: references/paper-directory.md.

---

Phase 6: Git Init (conditional)

Skip entirely if the user chose "No git" in Round 2.

cd "<project-path>" && git init && git branch -m main
# Activate the shared Paperpile citation pre-commit hook (per rules/paperpile-citations.md):
git config core.hooksPath "$(cat ~/.config/task-mgmt/path)/scripts/git-hooks"
git add . && git commit -m "Initialize project: <working-title>"

Setting core.hooksPath points this project's git hooks at the shared body in Task-Management (scripts/git-hooks/), so the citation lint runs on every commit with a single, centrally-maintained hook. core.hooksPath lives in .git/config (not committed), so it is re-set here at init for each project/checkout.

If GitHub remote requested: gh repo create "user/<project-name>" --private --source=. --remote=origin --push.

If local git only: remind to push before switching machines. Do NOT push unless a remote was explicitly requested.

---

Phase 7: Atlas Sync

Creates the research topic in all systems: local file → vault atlas → Venues → project folder → documentation.

Full steps, Atlas defaults, and Atlas anti-patterns ("Never Do These"): references/atlas-sync.md.

---

Phase 8: Task Management Integration

Three sub-steps writing into the Task Management context library: index update, paper context file, current-focus integration.

Full sub-steps, templates, edit policies: references/task-mgmt-sync.md.

---

Phase 9: Literature & Discovery

After scaffolding and syncing, run /literature and in parallel via sub-agents for initial literature review + novelty assessment.

Full steps and error handling: references/literature-discovery.md.

---

Phase 10: Confirmation Report

Print the structured confirmation after all phases complete.

Full template: references/confirmation-report.md.

---

Error Handling & Rollback

Per the multi-system-completeness rule, partial state is the dominant failure mode for this skill. Track which phases completed, surface incomplete state, do not silently move on.

Error	Response
Overleaf path doesn't exist	Create symlink anyway (resolves when Overleaf syncs). Warn user.
gh CLI not available	Skip GitHub remote, note in Phase 10 report.
taskflow MCP server fails	Skip vault entry, offer to retry. Note as incomplete in Phase 10.
Directory already exists with files	Phase 2 handles via reorganisation plan, not an error.
Duplicate Atlas slug	Flag and skip Atlas creation — may need merge into existing topic.
Phase fails after a previous phase wrote to disk	Phase 10 must list which systems were touched (local dir / Overleaf / vault / atlas / git remote) and which were not, so manual cleanup is targeted, not a guess.

---

Cross-References

Skill	Relationship
/literature	Runs in Phase 9 — initial literature review
	Runs in Phase 9 — novelty assessment
/project-safety	Already handled — .gitignore and settings created during init
/save-context	Context library entries created during Phase 8
/session-log	Offer to create a session log after init completes
/interview-me	To develop the research idea before scaffolding
packages/atlas-vault/generate_recap.py	Optional after init — regenerates RECAP.md portfolio index. Not required for atlas.example.com (atlas-workspace reads vault directly via Syncthing).
/atlas-deploy	Manual-only skill — user can run for schema validation + Mac Mini launchd restart. NOT needed for atlas.example.com to surface a new topic; that's automatic via Syncthing.
/audit-project-research	Must mirror this scaffold. When init adds a new directory or convention, add a matching audit phase there and update /atlas-audit SA1.
/atlas-audit	Drift trigger: new projects change theme dir counts — see atlas-audit/references/drift-checks.md. SA1 structure checks must stay consistent with this scaffold.
references/domain-profile-template.md	Template for economics/field-specific domain profiles — copy to project's docs/domain-profile.md during init for economics papers.

Citation Contract

1. Paperpile is the only source of truth for committed citation keys and BibTeX metadata.
2. Before writing \cite{key}, verify with paperpile get-item key and paperpile export-bib key.
3. Resolve unknowns in order: DOI lookup → Paperpile substring search → refpile semantic search → Paperpile verify.
4. A DOI miss is not non-membership; continue with title/author search and refpile.
5. If unresolved, write \CiteTodo{slug}{title/author/year/DOI hint} — never a guessed key.
6. Drafting sub-agents must not write/edit the active .bib; only the orchestrator regenerates it from Paperpile exports.
7. Stage genuine new refs under .paperpile-import/ for manual Paperpile import; don't cite until Paperpile mints the key.
8. Run scripts/bib/citation_lint.py before commit; zero placeholders, zero non-Paperpile keys, zero hand-authored metadata.

See rules/paperpile-citations.md for the full workflow.

Topic-folder papers layout (2026-07-03)

Scaffold paper-<venue>/submission/archive/ (empty, with .gitkeep) and a top-level presentations/ dir. Do NOT create PAPER-HISTORY.md — it is generated by scripts/generate-paper-history.py once the paper has events (rules/submission-file-archive.md § Topic-folder layout).