flonat-research 0.1.0

package/skills/init-project-research/templates/seed-files.md

@@ -0,0 +1,337 @@
+# Seed File Templates
+
+> Templates for Phase 3 of `/init-project-research`. Replace `<placeholders>` with interview answers.
+
+## CLAUDE.md
+
+```markdown
+# Claude Context for <Working Title>
+
+## Project Overview
+- **Working title:** <title>
+- **Authors:** <names>
+- **Venue type:** <journal/conference/preprint>
+- **Target venue:** <name>
+- **Deadline:** <date or "No fixed deadline">
+- **Type:** <experimental/computational/theoretical/mixed>
+
+### Venue Details
+<!-- Use ONE of the blocks below based on venue type -->
+
+<!-- IF JOURNAL -->
+- **CABS AJG:** <ranking>
+- **WBS 60:** <yes/no>
+- **FT 50:** <yes/no>
+<!-- END JOURNAL -->
+
+<!-- IF CONFERENCE -->
+- **CORE ranking:** <A*/A/B/C>
+- **Page limit:** <N pages + refs>
+- **Format:** <template name>
+- **Review type:** <double-blind/single-blind/open>
+- **Anonymisation:** <yes/no>
+- **Submission deadline:** <date>
+- **Notification:** <date>
+- **Camera-ready:** <date>
+- **CfP link:** <URL>
+<!-- END CONFERENCE -->
+
+## Research Questions
+1. <RQ1>
+2. <RQ2>
+3. <RQ3>
+
+## Methodology
+<One-line methodology overview>
+
+## Setup
+
+### Overleaf
+- **Symlink:** `paper/` → `<overleaf-path>/`
+- **External link:** <URL>
+- **To recreate symlink:** `ln -s "<overleaf-path>" "<project-path>/paper"`
+
+### GitHub
+<URL or "Local-only">
+
+### Collaborators
+<Names, affiliations, contact if provided>
+
+## Folder Structure
+```
+<tree of the created structure>
+```
+
+## Conventions
+- Compile LaTeX: build artifacts to `out/`, PDF copied back to source directory via `.latexmkrc`
+- Use `uv` for Python, never bare `pip` or `python`
+- Canonical bibliography: `paper/references.bib`
+- Citation keys: Better BibTeX format (e.g., `AuthorYYYY-xx`)
+- **Overleaf separation:** `paper/` is LaTeX source ONLY — no code, data, or scripts. All code goes in `code/` or `src/`, all data in `data/`. Only exported figures/tables go into `paper/`.
+
+## Session Continuity
+- Update `.context/current-focus.md` at end of each session
+- Use `.context/project-recap.md` for research design notes
+- Session logs go in `log/`
+```
+
+## README.md
+
+```markdown
+# <Working Title>
+
+**Authors:** <names>
+**Affiliation:** <institution>
+**Target:** <venue> (<deadline or "ongoing">)
+
+## Abstract
+<elevator pitch>
+
+## Links
+- **Overleaf:** <external link>
+- **GitHub:** <URL or "local-only">
+
+## Status
+- [ ] Literature review
+- [ ] Research design
+- [ ] Data collection
+- [ ] Analysis
+- [ ] Drafting
+- [ ] Submission
+```
+
+## .gitignore
+
+```gitignore
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Data (regenerable or too large for git)
+data/
+output/
+results/
+
+# Paper (tracked in Overleaf)
+paper/
+
+# Logs
+log/
+
+# Unsorted inbox
+to-sort/
+
+# Machine-specific memory (gitignored, never synced)
+.claude/state/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+
+# R
+.Rhistory
+.RData
+.Rproj.user/
+
+# LaTeX build artifacts
+*.aux
+*.bbl
+*.blg
+*.fdb_latexmk
+*.fls
+*.log
+*.out
+*.synctex.gz
+*.toc
+out/
+```
+
+## MEMORY.md
+
+Seed MEMORY.md at project root based on project type. Use the **research** template by default; use the **teaching** template for teaching or workshop projects.
+
+### Research Template
+
+```markdown
+# Memory — <Working Title>
+
+## Notation Registry
+
+| Variable | Convention | Anti-pattern |
+|----------|-----------|--------------|
+| | | |
+
+## Citations
+
+<!-- One-liner [LEARN:citation] corrections go here -->
+
+## Estimand Registry
+
+| What we estimate | Identification | Key assumptions |
+|-----------------|---------------|-----------------|
+| | | |
+
+## Key Decisions
+
+| Decision | Rationale | Date |
+|----------|-----------|------|
+| | | |
+
+## Anti-Patterns
+
+| What went wrong | Correction |
+|----------------|------------|
+| | |
+
+## Code Pitfalls
+
+| Bug | Impact | Fix |
+|-----|--------|-----|
+| | | |
+```
+
+### Teaching Template
+
+```markdown
+# Memory — <Course/Workshop Name>
+
+## Lecture Progression
+
+| Topic | Core question | Key method |
+|-------|--------------|------------|
+| | | |
+
+## Student Misconceptions
+
+| Misconception | Correction | How to address |
+|--------------|------------|----------------|
+| | | |
+
+## Empirical Applications
+
+| Paper | Dataset | Purpose |
+|-------|---------|---------|
+| | | |
+
+## Code Pitfalls
+
+| Bug | Impact | Fix |
+|-----|--------|-----|
+| | | |
+```
+
+## .claude/state/personal-memory.md (optional)
+
+Not created during init — only created on first machine-specific `[LEARN]` tag. Seed template for reference:
+
+```markdown
+# Personal Memory — Machine-Specific
+
+> Gitignored. Machine-specific workarounds and local paths.
+> Generic learnings go in MEMORY.md (committed).
+
+## Local Environment
+
+| Issue | Workaround |
+|-------|-----------|
+
+## Tool Quirks
+
+| Tool | Version | Gotcha |
+|------|---------|--------|
+```
+
+## .context/field-calibration.md
+
+Copy the template from `skills/init-project-research/templates/field-calibration.md`, replacing `<Working Title>` with the project title. All other placeholders remain — `/interview-me` Phase 7 populates them.
+
+## .context/current-focus.md
+
+```markdown
+# Current Focus
+
+> Project just initialised. Update this file at the end of each session.
+
+## Next Steps
+1. <First logical step based on project type>
+2. Set up bibliography in Overleaf
+3. Begin literature review
+```
+
+## .context/project-recap.md
+
+```markdown
+# Project Recap: <Working Title>
+
+## Abstract
+<elevator pitch>
+
+## Research Questions
+1. <RQ1>
+2. <RQ2>
+3. <RQ3>
+
+## Methodology
+<overview>
+
+## Key Decisions
+<empty — to be populated as the project evolves>
+
+## References
+<empty — add key papers as literature review progresses>
+```
+
+## .claude/hooks/copy-paper-pdf.sh
+
+PostToolUse hook that copies compiled paper PDFs to the backup folder after LaTeX compilation. Multi-paper-safe: scans for all `paper-*` directories/symlinks and copies each `main.pdf` to `<paper-wrapper>/backup/<dirname>_vcurrent.pdf`.
+
+```bash
+#!/usr/bin/env bash
+# PostToolUse hook: copy compiled paper PDFs to backup folder after LaTeX compilation
+# Scans for all paper-* directories and copies each main.pdf → backup/<dirname>_vcurrent.pdf
+# Only copies when source is newer; silently skips missing PDFs
+
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+for paper_dir in "$PROJECT_ROOT"/paper-*; do
+    [ -d "$paper_dir" ] || [ -L "$paper_dir" ] || continue
+    dirname="$(basename "$paper_dir")"
+    src="$paper_dir/paper/main.pdf"
+    [ -f "$src" ] || src="$paper_dir/main.pdf"
+    backup_dir="$paper_dir/backup"
+    dest="$backup_dir/${dirname}_vcurrent.pdf"
+    if [ -f "$src" ]; then
+        if [ ! -f "$dest" ] || [ "$src" -nt "$dest" ]; then
+            mkdir -p "$backup_dir"
+            cp "$src" "$dest"
+        fi
+    fi
+done
+```
+
+After creating the hook script, the PostToolUse hook must also be registered in `.claude/settings.local.json`. Add the following to the `hooks` key:
+
+```json
+"hooks": {
+    "PostToolUse": [
+        {
+            "matcher": "Bash",
+            "hooks": [
+                {
+                    "type": "command",
+                    "command": ".claude/hooks/copy-paper-pdf.sh"
+                }
+            ]
+        }
+    ]
+}
+```

package/skills/insights-deck/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: insights-deck
+description: "Use when you need a timestamped Claude Code insights report and Beamer presentation."
+allowed-tools: Bash(latexmk*), Bash(pdflatex*), Bash(xelatex*), Bash(mkdir*), Bash(ls*), Bash(cp*), Read, Write, Edit, Glob, Grep, Task
+argument-hint: (no arguments)
+---
+
+# Insights Deck Skill
+
+> Archive a Claude Code `/insights` HTML report and generate a Beamer presentation summarising the findings. All outputs go to `log/insights/` with date stamps.
+
+## When to Use
+
+- After running `/insights` to review your Claude Code usage patterns
+- When you want a shareable deck summarising how you use Claude Code
+- For periodic self-reflection on AI-assisted workflow
+
+## Scope
+
+This skill produces **two outputs only**: an archived HTML report and a Beamer deck. Do NOT use insights suggestions to create plans, rules, CLAUDE.md edits, or other follow-up actions during this skill's execution. If the user wants to act on suggestions, that happens after the deck is delivered — as a separate conversation.
+
+---
+
+## Phase 1 — Generate & Archive Insights
+
+### Step 1: Prompt the user to run `/insights`
+
+`/insights` is a built-in Claude Code command that cannot be invoked programmatically. Tell the user:
+
+> Please run `/insights` now. Once the HTML report opens in your browser, let me know and I'll continue.
+
+### Step 2: Locate the generated HTML
+
+After `/insights` completes, find the most recent insights HTML file:
+
+```bash
+ls -t /tmp/claude-insights-*.html 2>/dev/null | head -1
+```
+
+If not found in `/tmp/`, check the user's home directory and common download locations. Ask the user for the path if it can't be located automatically.
+
+### Step 3: Archive the HTML
+
+Each insights run gets its own date folder:
+
+```bash
+mkdir -p log/insights/YYYY-MM-DD
+cp <source-html> log/insights/YYYY-MM-DD/insights-YYYY-MM-DD-log.html
+```
+
+Use today's date for the timestamp.
+
+---
+
+## Phase 2 — Build Beamer Deck
+
+### Step 1: Read and extract findings
+
+Read the archived HTML file (`log/insights/YYYY-MM-DD/insights-YYYY-MM-DD-log.html`). Extract:
+
+1. **Usage patterns** — most-used tools, session frequency, typical session length
+2. **Strengths** — what's working well in the workflow
+3. **Friction points** — repeated failures, slow patterns, underused features
+4. **Recommendations** — suggested improvements
+
+### Step 2: Design the deck structure
+
+Apply rhetoric principles from the `beamer-deck` skill (condensed — no sub-agent reviews needed for an internal deck):
+
+- **Assertion titles** — every frame title states a claim, not a label
+- **One idea per slide** — split if a slide has two ideas
+- **Three-act arc:**
+  - Act I (Tension): Current usage snapshot — what does the data show?
+  - Act II (Development): Patterns, strengths, friction points
+  - Act III (Resolution): Recommendations and next steps
+- **MB/MC balance** — vary dense and light slides deliberately
+- **Pyramid principle** — lead with conclusions, then support
+
+### Step 3: Generate the `.tex` file
+
+Write to `log/insights/YYYY-MM-DD/insights-YYYY-MM-DD-deck.tex` with:
+
+- `\documentclass[aspectratio=169,11pt]{beamer}`
+- Original inline theme (no default Beamer themes)
+- Professional colour palette:
+  ```latex
+  \definecolor{Midnight}{HTML}{1A1A2E}
+  \definecolor{DeepBlue}{HTML}{16213E}
+  \definecolor{RoyalBlue}{HTML}{0F3460}
+  \definecolor{Coral}{HTML}{E94560}
+  \definecolor{SoftGray}{HTML}{BDC3C7}
+  \definecolor{CloudWhite}{HTML}{FAFBFC}
+  ```
+- Suggested structure (adapt based on findings):
+  1. Title slide — "Claude Code Usage: [Month Year]"
+  2. Opening claim — lead with the most striking finding
+  3. Usage overview — session count, tool distribution, time patterns
+  4. Top strengths (1–2 slides)
+  5. Key friction points (1–2 slides)
+  6. Recommendations (1–2 slides)
+  7. Closing — single actionable takeaway
+
+### Step 4: Compile
+
+Create a `.latexmkrc` in the date folder if not present:
+
+```perl
+$out_dir = 'out';
+# Copy PDF back to source directory after build
+END { system("cp $out_dir/*.pdf . 2>/dev/null") if defined $out_dir; }
+```
+
+Then compile:
+
+```bash
+cd log/insights/YYYY-MM-DD && latexmk -pdf insights-YYYY-MM-DD-deck.tex
+```
+
+### Step 5: Fix all warnings
+
+Parse `out/*.log` for overfull/underfull hbox/vbox warnings. Fix every one. Recompile until clean.
+
+The `.latexmkrc` copies the PDF from `out/` back to the date folder automatically.
+
+---
+
+## Output
+
+When complete, the date folder should contain:
+
+```
+log/insights/YYYY-MM-DD/
+├── insights-YYYY-MM-DD-log.html     # Archived /insights HTML
+├── insights-YYYY-MM-DD-deck.tex     # Beamer source
+├── insights-YYYY-MM-DD-deck.pdf     # Compiled PDF
+├── .latexmkrc                       # Build config
+└── out/                             # Build artifacts
+```
+
+Each `/insights-deck` run creates a new date folder, keeping the parent `log/insights/` clean.
+
+---
+
+## Cross-References
+
+| Skill | Relationship |
+|-------|-------------|
+| `/beamer-deck` | Full rhetoric framework and multi-agent review (this skill uses a condensed version) |
+| `/latex-autofix` | **Default compiler** — use for compilation with auto error resolution |
+| `/latex` | Manual compilation config details, `.latexmkrc` setup |
+| `/session-log` | Complements insights with session-level detail |

package/skills/interview-me/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: interview-me
+description: "Use when you need to conduct a structured interview to extract knowledge or preferences."
+disable-model-invocation: true
+argument-hint: "[brief topic or 'start fresh']"
+allowed-tools: Read, Write, Edit
+---
+
+# Research Interview
+
+Conduct a structured interview to help formalise a research idea into a concrete specification.
+
+**Input:** `$ARGUMENTS` — a brief topic description or "start fresh" for open-ended exploration.
+
+---
+
+## How This Works
+
+This is a **conversational** skill. Instead of producing a report immediately, you conduct an interview by asking questions one at a time, probing deeper based on answers, and building toward a structured research specification.
+
+**Do NOT use AskUserQuestion.** Ask questions directly in your text responses, one or two at a time. Wait for the user to respond before continuing.
+
+Before starting, read `.context/profile.md` and `.context/projects/_index.md` to understand the researcher's areas and active projects. If the topic relates to an existing project, read its context file too.
+
+---
+
+## Interview Structure
+
+### Phase 1: The Big Picture (1–2 questions)
+- "What phenomenon or puzzle are you trying to understand?"
+- "Why does this matter? Who should care about the answer?"
+
+### Phase 2: Theoretical Motivation (1–2 questions)
+- "What's your intuition for why X happens / what drives Y?"
+- "What would standard theory predict? Do you expect something different?"
+
+### Phase 3: Data and Setting (1–2 questions)
+- "What data do you have access to, or what data would you ideally want?"
+- "Is there a specific context, time period, or institutional setting you're focused on?"
+
+### Phase 4: Identification (1–2 questions)
+- "Is there a natural experiment, policy change, or source of variation you can exploit?"
+- "What's the biggest threat to a causal interpretation?"
+
+### Phase 5: Expected Results (1–2 questions)
+- "What would you expect to find? What would surprise you?"
+- "What would the results imply for policy or theory?"
+
+### Phase 6: Contribution (1 question)
+- "How does this differ from what's already been done? What's the gap you're filling?"
+
+---
+
+## Adapting to the Research Area
+
+the user's work spans multiple disciplines. Adapt the interview to the domain:
+
+- **Human-AI collaboration / MCDM**: Focus on decision architecture, experimental design, behavioural measures, and what "better" decisions look like.
+- **Multi-agent systems**: Focus on agent design, interaction protocols, equilibrium concepts, and simulation methodology.
+- **Organisational behaviour**: Focus on mechanisms, field vs. lab settings, mediators/moderators, and internal validity.
+- **Carbon markets / environmental**: Focus on policy variation, compliance data, market microstructure, and welfare implications.
+
+If the research is non-quantitative (conceptual, design science, qualitative), adjust: replace "Identification" with "Analytical Framework" and "Data" with "Empirical/Evidence Strategy".
+
+---
+
+### Phase 7: Field Calibration (optional, auto-triggered)
+
+**Auto-triggers when:** the project has no `.context/field-calibration.md`, or it exists but still contains `<placeholders>`.
+
+**Skip when:** the file already exists with populated content, unless the user explicitly asks to update it.
+
+Ask 2–3 targeted questions:
+
+- "Which journals or conferences are you targeting? I can cross-reference venue rankings." (Use `.context/resources/venue-rankings.md` to validate and suggest alternatives.)
+- "Which seminal papers would a reviewer in this subfield expect to see cited?"
+- "What's the typical identification strategy in this subfield — and what do reviewers most often attack?"
+
+After the interview, populate `.context/field-calibration.md` from answers combined with Research Spec content. Use the template at `skills/init-project-research/templates/field-calibration.md`.
+
+If field-calibration already exists with content: ask the user whether to update specific sections or keep as-is.
+
+---
+
+## After the Interview
+
+Once you have enough information (typically 5–8 exchanges), produce a **Research Specification Document**:
+
+```markdown
+# Research Specification: [Title]
+
+**Date:** [YYYY-MM-DD]
+**Researcher:** the user
+
+## Research Question
+
+[Clear, specific question in one sentence]
+
+## Motivation
+
+[2–3 paragraphs: why this matters, theoretical context, policy relevance]
+
+## Hypothesis
+
+[Testable prediction with expected direction]
+
+## Empirical Strategy
+
+- **Method:** [e.g., DiD, experiment, simulation, case study]
+- **Treatment/Manipulation:** [What varies]
+- **Control/Comparison:** [Comparison group or baseline]
+- **Key identifying assumption:** [What must hold]
+- **Robustness checks:** [Pre-trends, placebo, alternative specifications]
+
+## Data
+
+- **Primary dataset:** [Name, source, coverage]
+- **Key variables:** [Treatment, outcome, controls]
+- **Sample:** [Unit of observation, time period, N]
+
+## Expected Results
+
+[What the researcher expects to find and why]
+
+## Contribution
+
+[How this advances the literature — 2–3 sentences]
+
+## Open Questions
+
+[Issues raised during the interview that need further thought]
+```
+
+**Save to:** the project root or `docs/` if inside a research project, or present to the user for placement.
+
+**Also produces** (if Phase 7 triggered): `.context/field-calibration.md` — the per-project domain profile that agents use to calibrate reviews.
+
+---
+
+## Interview Style
+
+- **Be curious, not prescriptive.** Your job is to draw out the researcher's thinking, not impose your own ideas.
+- **Probe weak spots gently.** If the identification strategy sounds fragile, ask "What would a sceptic say about...?" rather than "This won't work because..."
+- **Build on answers.** Each question should follow from the previous response.
+- **Know when to stop.** If the researcher has a clear vision after 4–5 exchanges, move to the specification. Don't over-interview.
+- **Use British English** throughout (the user's preference).
+
+---
+
+## Cross-References
+
+| Skill | When to use instead/alongside |
+|-------|-------------------------------|
+| `/scout generate` | When you have a topic but no specific idea yet — generates multiple RQs |
+| `/devils-advocate` | After the spec is written — stress-test the idea |
+| `/literature` | To find related work mentioned during the interview |
+| `/init-project-research` | To scaffold a project once the spec is approved (seeds empty field-calibration) |