Init Project Research

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

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 AGENTS.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>" ~/Research-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 .Codex/), 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 .Codex/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): AGENTS.md, README.md, MEMORY.md, .gitignore, .context/, .Codex/, docs/ (literature-review, readings, venues), log/, paper-{venue}/ (with symlink + correspondence/referee-reviews/), github-repo/ (optional), knowledge/, reviews/INDEX.md (manifest only — per-source 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/.

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.

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

AGENTS.md vs README.md

• AGENTS.md — instructions for Codex: safety rules, folder structure, conventions, symlink paths. Follow the lean-Codex-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.

Permissions Sync

After writing .Codex/settings.local.json, merge global permissions from ~/.Codex/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 ASG Privacy Compliance Gaming (CCS), Paper MechDes Strategic Compliance (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 .Codex/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 && git add . && git commit -m "Initialize project: <working-title>"

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.

Cross-References