flonat-research 0.1.0

package/skills/init-project-research/references/interview-round3.md

@@ -0,0 +1,34 @@
+# Interview Round 3 — Research Content Questions
+
+> Paper-type-specific questions for Phase 1, Round 3 of `/init-project-research`. Adapted from Lopez-Lira's idea evaluation template.
+
+## Common Questions (all types)
+
+1. **Paper type** — Empirical / Theoretical / Methodological / Mixed
+2. **Abstract / elevator pitch** — 1-2 sentences
+3. **Key research questions** — up to 3
+
+## If Empirical
+
+4. **Identification strategy** — How will you establish causality? What is your source of exogenous variation? Name the specific shock, instrument, or natural experiment. (If unknown, note "TBD — pipeline will help identify")
+5. **Data sources** — List every dataset. Be specific: name the database, key variables, and sample period. (e.g., "CRSP Monthly Stock File (1970-2025): returns, market cap")
+6. **Proposed specification** — Write the main regression equation if possible, or describe the empirical test in words.
+
+## If Theoretical
+
+4. **Model setup** — Key agents, frictions, or market failures. Which assumptions drive results? Which are new vs standard?
+5. **Key predictions** — 2-3 testable predictions or comparative statics that distinguish this model from existing ones.
+6. **Relation to existing models** — Which models are closest? What friction/agent/structure is added or changed? Why does this matter?
+
+## If Methodological
+
+4. **The problem** — What existing method fails, and in what setting? What bias, inconsistency, or limitation is addressed?
+5. **Proposed method** — What is the new estimator, test, or procedure? Key properties (consistency, efficiency, robustness)?
+6. **Demonstration plan** — Monte Carlo, analytical proofs, empirical application to a known setting? What existing results would change?
+
+## If Mixed
+
+Ask the relevant subset of the above based on which types apply.
+
+## Storing the Answers
+

package/skills/init-project-research/references/literature-discovery.md

@@ -0,0 +1,43 @@
+# Literature & Discovery — Phase 8 Details
+
+> Referenced from: `init-project-research/SKILL.md` Phase 8
+
+After scaffolding and syncing, automatically run a literature review and scout novelty assessment. These run in parallel via sub-agents to save time.
+
+## 8a. Literature Review
+
+Launch `/literature` targeting the project's research topic. Uses the working title, abstract, key research questions, and any references from the Atlas topic file as search seeds.
+
+1. Spawn a sub-agent (`Task` tool) that runs the literature skill:
+   - Search query: derived from the working title + key concepts from the interview
+   - Sources: OpenAlex + Scopus (or multi-source if available)
+   - Output: `docs/literature-review/YYYY-MM-DD-initial-review.md` — structured literature map with verified citations
+   - Also generate: `docs/literature-review/references.bib` — verified BibTeX entries for discovered papers
+2. Scope: foundational papers + recent work (last 3 years) + closest competitors
+3. Target: 15-25 papers for an initial literature map
+
+## 8b. Scout Discovery Audit
+
+Launch `/scout` in novelty mode to assess the topic's competitive landscape.
+
+```bash
+scout novelty "<working-title-or-research-question>" --source multi
+```
+
+1. Save the scout report to `docs/YYYY-MM-DD-scout-novelty.md`
+2. If the novelty score is **below 5/10**, flag in the confirmation report: "Low novelty score — consider reframing before investing further"
+3. If the novelty score is **above 7/10**, note as a positive signal
+
+## 8c. Results Integration
+
+After both complete:
+
+1. Update the Atlas topic file's `## Key References` section with the top 5-8 foundational papers discovered
+2. Add the novelty score to the Atlas topic file: `## Novelty Assessment\n\n**Score: X/10** (scouted YYYY-MM-DD). [one-line summary]`
+3. If scout identifies specific competitors, add them to `## Key References` with differentiation notes
+
+## Error Handling
+
+- If literature search returns no results: note in report, continue (topic may be too novel or too niche for API coverage)
+- If scout CLI is not installed or fails: skip with warning, suggest running `/scout` manually later
+- These phases should NOT block project creation — if they fail, the project is still fully scaffolded

package/skills/init-project-research/references/scaffold-details.md

@@ -0,0 +1,197 @@
+# Scaffold Details
+
+> Templates, directory structures, and reference material used by `/init-project-research`. The SKILL.md has pointers here — read this when executing the relevant phase.
+
+---
+
+## Venues & Correspondence Structure
+
+When a target venue is known from the interview, seed the venue folder and correspondence directory:
+
+```
+docs/venues/<venue-slug>/      # e.g., docs/venues/ejor/, docs/venues/mcdm-2026/
+└── submission/                # .gitkeep — for initial submission materials
+
+correspondence/
+└── referee-reviews/            # .gitkeep — for review rounds (seeded by /process-reviews)
+```
+
+As the project progresses through submission and revision cycles, material splits across two locations:
+
+**`docs/venues/`** — submission and venue material only:
+```
+docs/venues/<venue-slug>/
+├── submission/                # Original submission
+│   ├── <Paper Title>.pdf      # Compiled PDF as submitted
+│   └── source/                # LaTeX source snapshot (optional)
+└── camera-ready/              # Final accepted version
+```
+
+**`correspondence/referee-reviews/`** — reviewer exchanges per round:
+```
+correspondence/referee-reviews/<venue>-round<N>/
+├── reviews-original.pdf       # What reviewers sent
+├── rebuttal.md                # What we send back
+└── analysis/                  # Our work on their feedback
+    ├── comment-tracker.md
+    ├── review-analysis.md
+    └── reviewer-comments-verbatim.tex
+```
+
+**`docs/<venue>/internal-reviews/`** — internal review work (not round-specific):
+```
+docs/<venue>/internal-reviews/
+├── referee2-report.md         # Referee2 agent analysis
+└── referee2-deck.tex          # Summary deck
+```
+
+---
+
+## Conference Submission Checklist Template
+
+For **conference venues**, seed a `submission-checklist.md` inside the venue folder:
+
+```markdown
+# <Conference Name> Submission Checklist
+
+## Venue Details
+- **Conference:** <name> (<acronym>)
+- **CORE ranking:** <ranking>
+- **Page limit:** <N pages + refs>
+- **Format:** <template>
+- **Review type:** <type>
+- **Anonymisation:** <yes/no>
+
+## Key Dates
+- [ ] Submission deadline: <date>
+- [ ] Notification: <date>
+- [ ] Camera-ready: <date>
+- [ ] Conference: <dates>
+
+## Pre-Submission
+- [ ] Page count within limit
+- [ ] Correct LaTeX template used
+- [ ] Anonymisation applied (if required) — use `/replication-package` Blind mode
+- [ ] All figures render correctly
+- [ ] Bibliography complete — run `/bib-validate`
+- [ ] Proofread — run `/proofread`
+- [ ] AI traces removed — use `/replication-package` Assemble mode
+
+## Submission
+- [ ] Paper uploaded to submission system
+- [ ] Supplementary materials attached (if any)
+- [ ] Author information entered correctly
+- [ ] Conflicts of interest declared
+```
+
+---
+
+## Papers Context File Template
+
+Used in Phase 6 when creating `.context/projects/papers/<short-name>.md`:
+
+```markdown
+# <Working Title>
+
+## Overview
+<Abstract/elevator pitch>
+
+## Status
+<Stage> — project just initialised
+
+## Key Details
+- **Authors:** <names>
+- **Affiliation:** <institution>
+- **Target:** <venue> (<deadline>)
+- **Design:** <methodology>
+
+## Links
+- **Overleaf:** <external link>
+- **GitHub:** <URL or "local-only">
+- **Vault:** <vault path auto-populated>
+- **Project folder:** <relative path>
+
+## Research Questions
+1. <RQ1>
+2. <RQ2>
+3. <RQ3>
+
+## Key Decisions
+<empty — to be populated>
+
+## Completed
+- [x] Project folder structure + Overleaf symlink
+- [x] Git initialised
+- [x] Context library entries created
+- [x] vault research pipeline entry
+
+## Action Items
+- [ ] Literature review
+- [ ] <First concrete next step based on project type>
+```
+
+---
+
+## Expected Post-Init Growth
+
+Projects naturally grow beyond the initial scaffold. These items are **not** created by `/init-project-research` but are recognized as valid by `/audit-project-research`:
+
+| Growth item | When it appears | Purpose |
+|-------------|----------------|---------|
+| `experiments/` | Computational projects with parameter sweeps | Experiment configs, sweep logs, results |
+| `experiments/configs/` | Sub-directory for sweep YAML/JSON files | Parameter sweep definitions |
+| `scripts/` | When utility scripts accumulate | One-off data processing, plotting scripts |
+| `legacy/` | After refactoring or restructuring | Preserves old code/data safely (per `/project-safety`) |
+| `correspondence/referee-reviews/<venue>-roundN/` | After receiving R&R | Reviewer comments, rebuttal, analysis |
+| `docs/<venue>/internal-reviews/` | After running referee2 agent | Internal review reports (not round-specific) |
+| `docs/venues/<venue>/camera-ready/` | After acceptance | Final camera-ready version |
+| `notes.md` | Early research phase | Quick research notes, meeting summaries |
+| `SETUP.md` | Computational projects with dependencies | Environment setup for collaborators |
+| `pyproject.toml` / `.venv/` | Python-heavy projects | Package management |
+| `.planning/` | After running `/init-project-orchestration` | Project roadmap and state tracking |
+| `.claude/agents/` | After running `/init-project-orchestration` | Project-level role-specific agents |
+| `.claude/commands/` | After running `/init-project-orchestration` | Project-level repeatable task commands |
+
+---
+
+## Overleaf Symlink Commands (Phase 4)
+
+### 4a. Create symlink
+
+```bash
+OVERLEAF_PATH="$HOME/Library/CloudStorage/YOUR-CLOUD/Apps/Overleaf/<overleaf-name>"
+PROJECT_PATH="<project-path>"
+
+# Verify Overleaf directory exists
+ls "$OVERLEAF_PATH"
+
+# Create symlink
+ln -s "$OVERLEAF_PATH" "$PROJECT_PATH/paper"
+
+# Verify it resolves
+ls "$PROJECT_PATH/paper/"
+```
+
+If the Overleaf directory doesn't exist, warn the user but still create the symlink (it will resolve once Overleaf creates the folder).
+
+### 4b. Seed template files
+
+If a template was selected in Round 2 (not "None"):
+
+1. Check whether the Overleaf folder already has `.tex` files
+2. If existing content, ask: "The Overleaf folder already has files. Overwrite with template, or skip?"
+3. If empty or overwrite confirmed:
+
+```bash
+TEMPLATE_PATH="<Task Management>/templates/<template-slug>"
+rsync -av --exclude='.git' --exclude='.gitignore' --exclude='out/' "$TEMPLATE_PATH/" "$PROJECT_PATH/paper/"
+```
+
+### 4c. Ensure `.latexmkrc` exists
+
+Check whether `paper/.latexmkrc` exists. If not, create it:
+
+```perl
+$out_dir = 'out';
+END { system("cp $out_dir/*.pdf . 2>/dev/null") if defined $out_dir; }
+```

package/skills/init-project-research/templates/field-calibration.md

@@ -0,0 +1,60 @@
+# Field Calibration — <Working Title>
+
+> Per-project domain profile. Agents read this to calibrate reviews to the field's norms.
+> Populated by `/interview-me` Phase 7 or manually. Distinct from `profile.md` (personal identity).
+
+## Field & Subfields
+
+- **Primary field:** <e.g., Operations Research, Organisational Behaviour, Computer Science>
+- **Subfield(s):** <e.g., Multi-Criteria Decision Making, Category D>
+- **Adjacent fields:** <fields reviewers might draw from>
+
+## Target Venues (ranked)
+
+| Venue | Type | Ranking | Fit | Notes |
+|-------|------|---------|-----|-------|
+| <venue 1> | journal/conference | <CABS/CORE> | Primary | |
+| <venue 2> | journal/conference | <CABS/CORE> | Fallback | |
+
+## Common Data Sources
+
+| Source | Type | Access | Notes |
+|--------|------|--------|-------|
+| <source 1> | <survey/admin/experimental/simulation> | <open/restricted/to-collect> | |
+
+## Identification Strategies Typical in This Field
+
+| Strategy | When used | Key assumptions | Common critiques |
+|----------|-----------|-----------------|------------------|
+| <e.g., RCT, DiD, simulation> | <context> | <assumptions> | <what reviewers attack> |
+
+## Notation Conventions
+
+| Symbol | Meaning | Field standard | Anti-pattern |
+|--------|---------|---------------|--------------|
+| <e.g., $D_i$> | <treatment indicator> | <standard in field> | <common mistake> |
+
+## Seminal References
+
+> Papers a reviewer in this field would expect to see cited.
+
+- <Author (Year)> — <one-line contribution>
+- <Author (Year)> — <one-line contribution>
+- <Author (Year)> — <one-line contribution>
+
+## Common Referee Concerns
+
+> Typical objections reviewers raise in this subfield.
+
+1. <e.g., "External validity of lab experiments to real organisations">
+2. <e.g., "Endogeneity of AI adoption decisions">
+3. <e.g., "Sensitivity to weight specification in MCDM">
+
+## Quality Thresholds
+
+| Dimension | Field expectation | Notes |
+|-----------|------------------|-------|
+| Sample size | <e.g., N > 200 for survey, N > 30 per cell for experiment> | |
+| Effect size reporting | <e.g., Cohen's d expected, partial eta-squared for ANOVA> | |
+| Robustness | <e.g., at least 3 alternative specifications> | |
+| Replication | <e.g., pre-registration expected for experiments> | |

package/skills/init-project-research/templates/pipeline-manifest.md

@@ -0,0 +1,63 @@
+# Pipeline Manifest
+
+**Project:** <!-- Project title -->
+**Last Updated:** <!-- Date -->
+
+---
+
+## Script Status
+
+| Step | Script | Language | Status | Notes |
+|------|--------|----------|--------|-------|
+<!-- | 01 | code/python/01_import.py | Python | Done | Imports raw data, cleans IDs | -->
+<!-- | 05 | code/R/05_merge.R | R | Done | Merges datasets | -->
+<!-- | 10 | code/R/10_summary_stats.R | R | Done | Summary statistics table | -->
+<!-- | 20 | code/python/20_estimate.py | Python | In progress | Main estimation | -->
+
+**Naming convention:** Step numbers use gaps (01, 05, 10, 20...) to allow insertion. Letter suffixes (10a, 10b) for variants of the same step.
+
+---
+
+## Data Files
+
+| File | Purpose | Created by | Used by |
+|------|---------|------------|---------|
+<!-- | data/processed/clean_data.csv | Cleaned import | Step 01 | Step 05 | -->
+<!-- | data/processed/analysis_file.parquet | Analysis-ready | Step 05 | Steps 10, 20 | -->
+
+**Rule:** `data/raw/` is READ-ONLY. All processed data goes to `data/processed/`.
+
+---
+
+## Manuscript Figure Manifest
+
+This table maps every figure and table in the manuscript back to its source script and input data. Use it to trace any output upstream to its code, or to identify which outputs need regeneration when a script or dataset changes.
+
+| Manuscript ref | Filename | Source script | Step | Input data |
+|---------------|----------|---------------|------|------------|
+<!-- | Figure 1 | descriptive_plot.pdf | code/R/10_summary_stats.R | 10 | analysis_file.parquet | -->
+<!-- | Figure 2 | event_study.pdf | code/python/20_estimate.py | 20 | analysis_file.parquet | -->
+<!-- | Table 1 | summary_stats.tex | code/R/10_summary_stats.R | 10 | analysis_file.parquet | -->
+<!-- | Table 2 | main_results.tex | code/python/20_estimate.py | 20 | analysis_file.parquet | -->
+
+### Tracing Workflow
+
+**Figure → Source (downstream to upstream):**
+1. Find the `\includegraphics{filename}` or `\input{filename}` in your paper
+2. Look up the filename in the manifest above to find the source script and step
+3. Read the source script to find its input data file
+4. Check the Script Status table to find what upstream step creates that data
+
+**Script change → Affected figures (upstream to downstream):**
+1. Identify which step's script was changed
+2. Look up that step in the manifest to find all figures/tables it produces
+3. Rerun the script (via `./run_all.sh "script_name"` if available)
+4. Output goes to `output/figures/` or `output/tables/`, which the paper picks up
+
+---
+
+## Notes
+
+- All outputs go to `output/` — figures in `output/figures/`, tables in `output/tables/`
+- The Script Status table must stay in sync with actual scripts in `code/`
+- Uncomment and fill in rows as you add scripts and outputs to the project

package/skills/init-project-research/templates/run-all.sh

@@ -0,0 +1,116 @@
+#!/bin/bash
+# run_all.sh — Multi-language pipeline executor
+# Usage:
+#   ./run_all.sh "script_name"    Run a single script (auto-detects language)
+#   ./run_all.sh --all            Run all pipeline steps in order
+#
+# Supported languages: Python (via uv), R, Stata
+# Logs saved to: output/logs/<script>_<timestamp>.log
+
+set -euo pipefail
+
+# --- Configuration ---
+PROJECT_ROOT="$(cd "$(dirname "$0")" && pwd)"
+LOG_DIR="$PROJECT_ROOT/output/logs"
+mkdir -p "$LOG_DIR"
+
+# --- Language runners ---
+
+run_python() {
+    local script="$1"
+    local logfile="$2"
+    echo "Running Python: $script"
+    uv run python "$script" 2>&1 | tee "$logfile"
+    return "${PIPESTATUS[0]}"
+}
+
+run_r() {
+    local script="$1"
+    local logfile="$2"
+    echo "Running R: $script"
+    Rscript "$script" 2>&1 | tee "$logfile"
+    return "${PIPESTATUS[0]}"
+}
+
+run_stata() {
+    local script="$1"
+    local logfile="$2"
+    echo "Running Stata: $script"
+    local script_name
+    script_name=$(basename "$script" .do)
+    stata-mp -b do "$script" 2>&1 | tee "$logfile"
+    # Stata writes its own log; append it
+    if [ -f "${script_name}.log" ]; then
+        cat "${script_name}.log" >> "$logfile"
+        rm "${script_name}.log"
+    fi
+    return "${PIPESTATUS[0]}"
+}
+
+# --- Dispatcher ---
+
+run_script() {
+    local script="$1"
+    local script_name
+    script_name=$(basename "$script")
+    local timestamp
+    timestamp=$(date +"%Y-%m-%d_%H%M%S")
+    local logfile="$LOG_DIR/${script_name}_${timestamp}.log"
+
+    echo "========================================"
+    echo "  Script: $script_name"
+    echo "  Log:    $logfile"
+    echo "  Time:   $(date)"
+    echo "========================================"
+
+    local exit_code=0
+
+    case "$script" in
+        *.py)   run_python "$script" "$logfile" || exit_code=$? ;;
+        *.R)    run_r "$script" "$logfile" || exit_code=$? ;;
+        *.do)   run_stata "$script" "$logfile" || exit_code=$? ;;
+        *)
+            echo "ERROR: Unknown file type: $script"
+            echo "Supported: .py, .R, .do"
+            return 1
+            ;;
+    esac
+
+    echo ""
+    if [ $exit_code -eq 0 ]; then
+        echo "SUCCESS: $script_name completed (exit code 0)"
+    else
+        echo "FAILED: $script_name (exit code $exit_code)"
+    fi
+    echo "Log saved: $logfile"
+
+    # Open log on macOS
+    if command -v open &> /dev/null; then
+        open "$logfile"
+    fi
+
+    return $exit_code
+}
+
+# --- Main ---
+
+if [ $# -eq 0 ]; then
+    echo "Usage:"
+    echo "  ./run_all.sh \"script_name\"    Run a single script"
+    echo "  ./run_all.sh --all            Run all pipeline steps"
+    exit 1
+fi
+
+if [ "$1" = "--all" ]; then
+    echo "Running full pipeline..."
+    echo ""
+    # Add pipeline steps here in order, e.g.:
+    # run_script "code/python/01_import.py"
+    # run_script "code/R/05_merge.R"
+    # run_script "code/R/10_summary_stats.R"
+    # run_script "code/python/20_estimate.py"
+    echo "No pipeline steps configured yet. Add them to run_all.sh."
+    exit 0
+else
+    run_script "$1"
+fi