flonat-research 0.1.0

package/skills/quarto-deck/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: quarto-deck
+description: "Use when you need to generate a Reveal.js HTML presentation from Markdown."
+allowed-tools: Bash(reveal-md*), Bash(npx*), Bash(mkdir*), Bash(ls*), Bash(cp*), Bash(open*), Bash(R*), Bash(Rscript*), Bash(python*), Read, Write, Edit, Task
+argument-hint: [topic, content-path, or project-name]
+---
+
+# Reveal.js Deck Skill
+
+> Generate HTML presentations from Markdown using reveal-md. Applies the same rhetoric framework as `/beamer-deck` but outputs browser-native slides ideal for teaching, informal talks, and web sharing.
+
+## Purpose
+
+Create polished Reveal.js presentations from Markdown files. Every deck gets assertion-driven titles, narrative arc, and rhetoric review. Output is an HTML presentation that runs in any browser — no LaTeX needed.
+
+**Use this for:** Teaching, informal research talks, web-shareable presentations, interactive demos.
+**Use `/beamer-deck` for:** Conference talks, formal seminars, supervisor meetings, anything that needs PDF-native output.
+
+## When to Use
+
+- Teaching lectures (undergraduate or PhD) — interactive, live in browser
+- Informal research presentations or lab meetings
+- Talks where you want to share a URL instead of a PDF
+- Presentations with live code demos or embedded content
+- Quick decks where LaTeX overhead isn't justified
+
+**Python:** Always use `uv run python`. Never bare `python`, `python3`, `pip`, or `pip3`.
+
+## Prerequisites
+
+- `reveal-md` (installed globally): `npm install -g reveal-md`
+- Node.js 18+ (via nvm)
+
+---
+
+## Critical Rules
+
+0. **Python: ALWAYS use `uv run python` or `uv pip install`.** Never use bare `python`, `python3`, `pip`, or `pip3`. Include this instruction in any sub-agent prompts that may run Python.
+1. **One Markdown file = one presentation.** All slides live in a single `.md` file with `---` separators.
+2. **Titles are assertions, not labels.** "Distance increases abortion rates" — not "Results". Every slide title states a claim.
+3. **One idea per slide.** Not a guideline. A law. If a slide has two ideas, split it.
+4. **Speaker notes use the `Note:` keyword.** Place after slide content, before the next `---`.
+5. **Custom CSS goes in a separate file.** Never inline styles in the Markdown.
+6. **Figures first, slides second.** Generate figures via R or Python scripts before referencing them.
+7. **Test in browser before finalising.** Run `reveal-md <file>.md` and check every slide.
+
+---
+
+## Rhetoric Principles
+
+Same framework as `/beamer-deck`. Full reference (Three Laws, MB/MC, Aristotelian Triad, Narrative Arc, Pyramid Principle, Devil's Advocate, audience-specific guidance): [`../shared/rhetoric-principles.md`](../shared/rhetoric-principles.md)
+
+---
+
+## Quality Scoring
+
+Apply numeric quality scoring using the shared framework and skill-specific rubric:
+
+- **Framework:** [`../shared/quality-scoring.md`](../shared/quality-scoring.md) — severity tiers, thresholds, verdict rules
+- **Rubric:** [`references/quality-rubric.md`](references/quality-rubric.md) — issue-to-deduction mappings for this skill
+
+Start at 100, deduct per issue found, apply verdict. Compute the score in Phase 6 and report it in the final output.
+
+## Reveal.js Markdown Format
+
+Full format reference with basic structure, vertical slides, fragments, custom themes, and CSS examples: [`references/markdown-format.md`](references/markdown-format.md)
+
+**Reference palettes** (Professional, Energetic, Academic) with both LaTeX and CSS variants: [`../shared/palettes.md`](../shared/palettes.md)
+
+---
+
+## Workflow: 6 Phases
+
+```
+You (orchestrator)
+├── Phase 1: Gather context        (direct)
+├── Phase 2: Design structure       (direct)
+├── Phase 3: Build deck             (direct)
+├── Phase 4: Preview & fix          (direct)
+├── Phase 5: Rhetoric review        (sub-agent — Explore)
+└── Phase 6: Apply & finalise       (direct)
+```
+
+### Phase 1: Gather Context (Direct)
+
+Read project files, content sources, and audience brief. Ask the user:
+
+- **Audience**: Teaching? Lab meeting? Informal talk?
+- **Duration**: How long?
+- **Content source**: Paper draft? Notes? Existing slides?
+- **Special requirements**: Code demos? Interactive elements? Specific theme?
+- **Export needs**: Browser only, or also need static HTML/PDF?
+
+### Phase 2: Design Structure (Direct)
+
+1. **Choose rhetoric balance** based on audience
+2. **Outline slide sequence** with assertion titles
+3. **Plan narrative arc** — identify Act I/II/III transitions
+4. **Choose colour palette** — create `custom.css`
+5. **Identify figures needed** — which need code generation?
+
+Present outline to the user for approval.
+
+### Phase 3: Build Deck (Direct)
+
+1. **Generate figures first** — R/Python scripts, save to `figures/`
+2. **Write the `.md` file** with YAML frontmatter and slide content
+3. **Write `custom.css`** if custom theming is needed
+4. **Test locally**: `reveal-md deck.md`
+5. **Add speaker notes** using `Note:` blocks
+
+### Phase 4: Preview and Fix (Direct)
+
+1. Run `reveal-md deck.md` to preview in browser
+2. Check every slide for:
+   - Text overflow or cramped content
+   - Figure sizing and alignment
+   - Math rendering (MathJax)
+   - Code highlighting
+   - Transitions between slides
+3. Fix issues and re-preview
+
+### Phase 5: Rhetoric Review (Sub-Agent — Explore)
+
+Launch the same rhetoric review as `/beamer-deck`, adapted for Markdown:
+
+```
+subagent_type: Explore
+prompt: |
+  You are a rhetoric reviewer for an academic Reveal.js presentation.
+
+  Read the file at: [PATH TO .md FILE]
+
+  Evaluate against these criteria:
+
+  ## 1. Narrative Arc
+  - Three-act structure (Problem → Investigation → Resolution)?
+  - Opening: provocative question, statistic, or bold claim?
+  - Closing: single memorable takeaway?
+
+  ## 2. MB/MC Balance
+  - Cognitive load distributed smoothly?
+  - Overloaded or underloaded slides?
+
+  ## 3. Title Quality
+  - Every title an assertion (a claim), not a label?
+
+  ## 4. One Idea Per Slide
+  - Any slide trying to convey multiple ideas?
+
+  ## 5. Transitions
+  - Are transitions between slides explicit?
+  - Does the audience know where they are in the argument?
+
+  ## 6. Pyramid Principle
+  - Conclusions before support?
+
+  Return structured markdown with ratings and specific slide suggestions.
+```
+
+### Phase 6: Apply and Finalise (Direct)
+
+1. Incorporate rhetoric review feedback
+2. Re-preview in browser
+3. **Compute quality score** — read `references/quality-rubric.md`, log all issues from Phases 4-5, compute score and verdict
+4. **Export if needed:**
+   - Static HTML: `reveal-md deck.md --static _site`
+   - PDF: `reveal-md deck.md --print deck.pdf`
+5. Confirm all files are in place
+
+---
+
+## Commands Reference
+
+| Command | What it does |
+|---------|-------------|
+| `reveal-md deck.md` | Live preview with hot reload (default port 1948) |
+| `reveal-md deck.md --css custom.css` | Preview with custom CSS |
+| `reveal-md deck.md --static _site` | Export to static HTML (shareable folder) |
+| `reveal-md deck.md --print deck.pdf` | Export to PDF (uses Puppeteer) |
+| `reveal-md deck.md --port 3000` | Preview on custom port |
+| `reveal-md deck.md --theme moon` | Use built-in theme (moon, night, serif, etc.) |
+
+Press `s` during preview to open **speaker notes view**.
+Press `f` for fullscreen. Press `o` for slide overview.
+
+---
+
+## Output Checklist
+
+A completed deck directory should contain:
+
+```
+project/
+├── deck.md               # Markdown presentation
+├── custom.css             # Custom theme (if used)
+├── figures/               # Generated figures (if any)
+│   ├── figure_1.png
+│   └── ...
+├── scripts/               # R/Python scripts for figures (if any)
+│   ├── figure_1.R
+│   └── ...
+├── _site/                 # Static HTML export (if generated)
+└── deck.pdf               # PDF export (if generated)
+```
+
+- [ ] All slide titles are assertions
+- [ ] One idea per slide
+- [ ] Narrative arc: Problem → Investigation → Resolution
+- [ ] Rhetoric review completed (Phase 5)
+- [ ] Speaker notes present for key slides
+- [ ] Math renders correctly (if used)
+- [ ] Tested in browser — no overflow or layout issues
+- [ ] Quality score computed and reported
+
+---
+
+## Cross-References
+
+| Skill | When to use instead/alongside |
+|-------|-------------------------------|
+| `/beamer-deck` | For formal academic presentations (conferences, seminars) that need PDF-native output |
+| `/project-deck` | For project status updates (supervisor meetings, coauthor handoffs) |
+| `/proofread` | For post-hoc review of text quality |
+| `/literature` | For finding and verifying citations to include |
+| `/quarto-course` | For full course websites with multiple lectures, exercises, and navigation |

package/skills/quarto-deck/references/markdown-format.md

@@ -0,0 +1,143 @@
+# Reveal.js Markdown Format Reference
+
+> Format reference for `/quarto-deck`. All slides live in a single `.md` file with `---` separators.
+
+## Basic Structure
+
+```markdown
+---
+title: "Presentation Title"
+theme: white
+highlightTheme: github
+revealOptions:
+  transition: slide
+  slideNumber: true
+  hash: true
+  center: true
+  math:
+    mathjax: https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+    config: TeX-AMS_HTML-full
+---
+
+# Main Title
+
+Subtitle or key question
+
+---
+
+## Assertion title for slide 2
+
+Content goes here.
+
+Note:
+Speaker notes go here. Press 's' to open speaker view.
+
+---
+
+## Another assertion title
+
+- Point one
+- Point two
+
+---
+
+<!-- .slide: data-background="#003366" -->
+
+## White text on dark background
+
+Use for emphasis slides.
+
+---
+
+## Slide with math
+
+The treatment effect is $\tau = E[Y(1) - Y(0)]$
+
+$$\hat{\tau}_{ATT} = \frac{1}{N_T} \sum_{i: D_i=1} \left( Y_i - \hat{Y}_i^{(0)} \right)$$
+
+---
+
+## Slide with code
+
+```python
+import pandas as pd
+df = pd.read_csv("data.csv")
+print(df.describe())
+```
+
+---
+
+## Slide with image
+
+![Description](figures/figure_1.png)
+
+---
+
+## Key takeaway
+
+One sentence that the audience remembers.
+```
+
+## Vertical Slides (Sub-sections)
+
+Use `----` (four dashes) for vertical slides within a section:
+
+```markdown
+## Main Topic
+
+Overview
+
+----
+
+### Detail 1
+
+First sub-point
+
+----
+
+### Detail 2
+
+Second sub-point
+```
+
+## Fragments (Progressive Reveal)
+
+```markdown
+- First point <!-- .element: class="fragment" -->
+- Second point <!-- .element: class="fragment" -->
+- Third point <!-- .element: class="fragment" -->
+```
+
+## Custom Themes
+
+Create a `custom.css` file alongside the Markdown:
+
+```css
+/* custom.css */
+:root {
+  --r-background-color: #FAFBFC;
+  --r-main-color: #2C3E50;
+  --r-heading-color: #003366;
+  --r-link-color: #E94560;
+  --r-heading-font: 'Source Sans Pro', Helvetica, sans-serif;
+  --r-main-font: 'Source Sans Pro', Helvetica, sans-serif;
+  --r-heading-text-transform: none;
+  --r-main-font-size: 32px;
+}
+
+.reveal .slides section {
+  text-align: left;
+}
+
+.reveal h2 {
+  font-size: 1.4em;
+  margin-bottom: 0.5em;
+}
+
+/* Emphasis slide */
+.reveal section[data-background-color] h2 {
+  color: white;
+}
+```
+
+For colour palette starting points, see [`skills/shared/palettes.md`](../shared/palettes.md).

package/skills/quarto-deck/references/quality-rubric.md

@@ -0,0 +1,54 @@
+# Quality Rubric: Quarto Deck
+
+> Scoring rubric for `/quarto-deck`. Uses the shared framework in [`../../shared/quality-scoring.md`](../../shared/quality-scoring.md).
+
+## Deduction Table
+
+### Blocker (-100)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| `reveal-md` render fails — no HTML output | -100 | Deck is broken |
+| Markdown syntax error breaking slide structure | -100 | Slides don't parse correctly |
+
+### Critical (-15 to -25)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| No narrative arc (no Problem → Investigation → Resolution structure) | -20 | Fundamental rhetoric failure |
+| Label title instead of assertion (e.g., "Results" not a claim) | -15 | Per slide |
+| Multiple ideas on a single slide | -15 | Per slide |
+| MathJax rendering failure (broken equations) | -15 | Per broken equation |
+| Image/figure not found (broken `![](path)`) | -15 | Per broken image |
+
+### Major (-5 to -14)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| Content overflow (text runs off slide) | -5 | Per slide |
+| Missing transitions between sections | -8 | Per missing transition |
+| Aristotelian balance off for audience type | -5 | Once for the deck |
+| Code block syntax highlighting broken | -5 | Per block |
+| Inline styles in Markdown (should be in CSS) | -5 | Per instance — violates Critical Rule 5 |
+| Figure sizing wrong (too small/large for slide) | -5 | Per figure |
+| Colour palette not accessible | -5 | Once for the deck |
+
+### Minor (-1 to -4)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| Conclusion-last instead of conclusion-first (Pyramid Principle) | -3 | Per slide |
+| Speaker notes missing on key slides | -2 | Per key slide |
+| Slide visually cramped | -3 | Per slide |
+| Inconsistent formatting between slides | -2 | Once for the deck |
+| `---` separator issues (extra blank lines, inconsistent spacing) | -1 | Per instance |
+| Cognitive load spike | -3 | Per instance |
+
+## Category Mapping
+
+| Rubric category | Phase |
+|----------------|-------|
+| Rendering & structure | Phase 3-4 |
+| Rhetoric (arc, titles, one-idea) | Phase 5 |
+| Visual quality (figures, code, layout) | Phase 4 |
+| Final polish | Phase 6 |

package/skills/save-context/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: save-context
+description: "Use when you need to save information from the current conversation to the context library."
+allowed-tools: Read, Write, Edit
+---
+
+# Save to Context Library
+
+Save information from the current conversation to the user's task management context files for future reference.
+
+## Context Library Location
+
+```
+$TM/.context/
+```
+
+## Available Context Files
+
+### 1. Profile (`profile.md`)
+**Save here:** Personal details, roles, research areas, working style, preferences
+
+**Triggers:**
+- "Add this to my profile"
+- "Remember that I prefer..."
+- "Save my research interests"
+
+**Format:** Update the relevant section, preserving existing content
+
+### 2. Current Focus (`current-focus.md`)
+**Save here:** What the user is actively working on, recent progress, next steps
+
+**Triggers:**
+- "Update my current focus"
+- "I'm now working on..."
+- "Save where I left off"
+
+> **Preferred:** For structured end-of-session updates, use `/update-focus` instead. It preserves the full document structure and handles session rotation, open loops, and mental state. Use `/save-context` only for quick, targeted saves (e.g., adding a single note or updating one field). If `/update-focus` is not available, read the file first and merge carefully — never overwrite with a blank template.
+
+**Format:** Read the existing file and update the relevant section. Do not use a template — the file has a rich structure that must be preserved.
+
+### 3. Projects Index (`projects/_index.md`)
+**Save here:** Project overviews, paper status, collaborations
+
+**Triggers:**
+- "Add this project"
+- "Update my journal paper status"
+- "Save this research idea"
+
+**Format:** Update the appropriate table or section
+
+### 4. Individual Project Files (`projects/papers/[name].md`)
+**Save here:** Detailed notes on specific papers/projects
+
+**Triggers:**
+- "Save these notes to my [project] file"
+- "Create a project file for [name]"
+
+**Format:** Create new file if doesn't exist:
+```markdown
+# [Project Name]
+
+## Overview
+[Brief description]
+
+## Status
+[Current stage]
+
+## Key Decisions
+- [Important choices made]
+
+## Notes
+[Detailed notes]
+
+## Action Items
+- [ ] [Tasks]
+```
+
+### 5. People (`people/supervisors.md` or `people/collaborators.md`)
+**Save here:** Information about supervisors, collaborators, contacts
+
+**Triggers:**
+- "Add [name] to my contacts"
+- "Remember that [person] works on..."
+- "Save [person]'s details"
+
+**Format:**
+```markdown
+### [Name]
+- **Institution:** [Where they work]
+- **Role:** [Their position]
+- **Collaboration:** [What you work on together]
+- **Contact:** [Email/preferred method]
+- **Notes:** [Relevant context]
+```
+
+### 6. Preferences (`preferences/`)
+**Save here:** Task naming conventions, priority definitions, workflow preferences
+
+**Triggers:**
+- "Remember I prefer tasks named like..."
+- "Save my priority rules"
+
+### 7. Workflows (`workflows/`)
+**Save here:** How the user wants certain processes to work
+
+**Triggers:**
+- "Update my daily review workflow"
+- "Change how I want meetings processed"
+
+## How to Save
+
+### Step 1: Identify the target file
+Based on the information type, determine which context file to update.
+
+### Step 2: Read the existing file
+Always read the current content first to preserve existing information.
+
+### Step 3: Merge intelligently
+- Don't overwrite existing content unless explicitly asked
+- Add new information in the appropriate section
+- Update timestamps where relevant
+
+### Step 4: Write the updated file
+Save the merged content back to the file.
+
+### Step 5: Confirm
+Tell the user what was saved and where:
+> "Saved to `.context/[file]`: [brief summary of what was added]"
+
+## Examples
+
+**User:** "Remember that my supervisor is [Supervisor] [Supervisor], he specialises in multi-objective optimisation"
+
+**Action:**
+1. Read `.context/people/supervisors.md`
+2. Find or create the Supervisor section
+3. Update with: Name: [Supervisor] [Supervisor], Focus: Multi-objective optimisation
+4. Save file
+5. Respond: "Saved to `.context/people/supervisors.md`: Added [Supervisor] [Supervisor] as your supervisor (multi-objective optimisation)"
+
+---
+
+**User:** "Update my current focus - I'm now deep in the journal revision, specifically rewriting section 4"
+
+**Action:**
+1. Read `.context/current-focus.md`
+2. Update "What I'm Working On" section
+3. Add timestamp
+4. Save file
+5. Respond: "Updated `.context/current-focus.md`: Now working on journal revision, section 4 rewrite"
+
+---
+
+**User:** "Save this meeting summary to my context"
+
+**Action:**
+1. Determine if it's project-specific or general
+2. If project-specific: save to `projects/papers/[project].md`
+3. If general: save key points to `current-focus.md`
+4. Extract any action items and offer to create vault tasks
+
+## Integration with vault
+
+After saving to context files, offer to:
+- Create related tasks in vault tasks
+- Update Research Pipeline if paper-related
+- Link context to specific vault files
+
+## Tips
+
+- Always preserve existing content unless asked to replace
+- Use timestamps for time-sensitive information
+- Keep entries concise but complete
+- Cross-reference between files when relevant

package/skills/session-log/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: session-log
+description: "Use when you need to create a timestamped progress log for a research session."
+allowed-tools: Read, Write, Edit, Bash(mkdir*), Bash(ls*)
+argument-hint: [project-name-or-path]
+---
+
+# Session Log Skill
+
+> Automatically create timestamped progress logs for research sessions.
+
+## Purpose
+
+Based on Scott Cunningham's Claude Code workflow: "Progress logs are my autosave of the workflow." When sessions end or crash, the next Claude can read logs and pick up exactly where you left off.
+
+## When to Use
+
+At the end of any significant work session, or when asked to "log this session" or "update progress".
+
+## Workflow
+
+### Step 1: Identify Projects Touched
+
+Before writing anything, inventory which projects were affected during this session. A "project" is any directory with its own `CLAUDE.md` or `log/` directory. Common splits:
+
+| Scope | Where the log goes |
+|-------|--------------------|
+| Work inside a specific project | That project's `log/` |
+| Global infrastructure (skills, hooks, rules, settings) | Task Management's `log/` |
+| Course/module-level changes (reorganisation, new CLAUDE.md) | That module's `log/` |
+
+**Signs of a multi-project session:**
+- Files changed under `~/.claude/` (skills, hooks, settings) → global/infrastructure log
+- Files changed in the CWD project → project-specific log
+- Files changed in a parent or sibling directory → check if that's a separate project
+
+### Step 2: Create One Log Per Project
+
+For each project identified in Step 1:
+
+1. **Read existing context** — check that project's `.context/current-focus.md` and recent `log/` entries
+2. **Create `log/` directory** if it doesn't exist
+3. **Write the log** to `log/YYYY-MM-DD-HHMM.md` within that project
+4. **Scope the content** — each log only covers what happened in that project, not the whole session
+
+If there's only one project, this reduces to a single log (the common case).
+
+### Step 3: Cross-Reference
+
+When multiple logs are created, add a brief cross-reference at the top of each:
+
+```markdown
+> Also logged: [other project name] — `[relative or absolute path to other log]`
+```
+
+This lets a future session in one project discover that related work happened elsewhere.
+
+### Step 4: Offer Follow-Up
+
+- **Offer to run `/update-focus`** for a structured update (session rotation, open loops), rather than making ad-hoc edits to `current-focus.md`
+- If multiple projects were touched, offer to update focus for each
+
+## Log Template
+
+```markdown
+# Session Log: [Date] [Time]
+
+## Project: [Project Name]
+
+## What We Did
+- [Bullet points of accomplishments]
+
+## Key Decisions
+- [Any choices made and why]
+
+## Problems/Blockers
+- [Issues encountered]
+
+## Next Steps
+- [ ] [Actionable next items]
+
+## Files Changed
+- [List of modified files — only those in THIS project]
+```
+
+## Examples
+
+### Single-project session
+"Please log this session — we worked on the research paper, fixed the simulation code, and decided to target Journal B instead of Journal A."
+
+→ One log in the MCDM project's `log/`
+
+### Multi-project session
+"Please log this session — we did Workshop 17, reorganised the module folder, and created two new global skills."
+
+→ Three logs:
+1. **Module project** `log/` — workshop completion, reorganisation, CLAUDE.md creation
+2. **Task Management** `log/` — new skills (`init-project-course`, `audit-project-course`), new hook (`ensure-latexmkrc.sh`), settings.json changes