flonat/flonat-research

# Beamer Deck Skill

> Generate academic Beamer presentations with original themes, rhetoric-driven structure, and multi-agent review. Internalises Scott Cunningham's rhetoric framework and implements an adversarial review workflow.

## Purpose

Create polished, zero-warning Beamer decks for academic contexts: seminars, conference talks, teaching lectures, and working decks for coauthors. Every deck gets a custom theme, assertion-driven titles, and parallel review by rhetoric and graphics sub-agents.

**NOT for project status updates** — use `project-deck` for those.

## When to Use

- Academic seminar presentations
- Conference talks (15–45 min)

# Bibliography Coverage

**LIBRARY-FIRST RULE: ALWAYS check Paperpile (`paperpile search-library`) when assessing coverage.**

Compare a project's `.bib` file against a Paperpile project/topic folder to identify gaps between the project bibliography and the reference library.

## When to Use

- After a literature search, to see what % of the topic collection is cited
- Before submitting a paper, to catch references you forgot to cite
- When reviewing a Paperpile project/topic folder, to find items not yet in any project's `.bib`
- After a bibliography-quality check, as a complementary completeness check

## When NOT to Use

# Bibliography Filter

Produce and validate a cited-only bibliography, then replace the manuscript's canonical `.bib` only after explicit approval. In an Overleaf-linked project, the resolved Overleaf bibliography is canonical; a wrapper-local copy is not a second authority.

## When to Use

- Before submission — strip unused references from the bibliography
- When a shared `.bib` (e.g., Paperpile/Paperpile export) contains hundreds of entries but the paper cites a subset
- To reduce `.bib` file size for Overleaf or arXiv upload
- As a cleanup step after major revision (removed sections may leave orphan citations)

## Process

### Step 1: Locate files

# Bibliography Parser — PDF to .bib

**LIBRARY-FIRST RULE: ALWAYS check Paperpile membership by DOI (`paperpile lookup-by-doi`) for each parsed reference BEFORE generating new BibTeX entries.** Topic/title `search-library` is a lossy discovery aid, NOT a membership test — never tag a reference `NEW` off a title-search miss. Reuse existing library entries instead of constructing from scratch. Enforced in Phase 2.3 per [`shared/reference-resolution.md`](../shared/reference-resolution.md) § Membership Check.

**Goal:** given a PDF file, extract all cited references and produce a clean, validated `.bib` file.

## When to Use

- You have a PDF (paper, report, thesis) and need a `.bib` file for its references
- Importing references from a paper that doesn't have a companion `.bib` file
- Reconstructing a bibliography from a document with embedded `\begin{thebibliography}` or numbered references
- Converting a reference list from any format into BibTeX

## When NOT to Use

# Brief Compliance Check

> Given a PDF brief and a LaTeX submission, report exactly what is met, missing, or over-limit.
> **Report-only — never modifies files.**

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `brief-compliance-check`
- **Write reports to:** `reviews/<paper-slug>/brief-compliance-check/<YYYY-MM-DD-HHMM>.md` inside the project, where `<paper-slug>` is the paper directory name (e.g., `paper-jtp`, `paper-philtech`). Path is relative to the research project root, not the Task-Management repo.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** if today's file exists, append a same-day descriptor (`{date}-revision.md`, `{date}-r2.md`, `{date}-pre-submission.md`) — never overwrite.
- **Index update:** if `reviews/INDEX.md` exists, write a one-line entry under "Latest per source" pointing at the new file. Otherwise `review-recap` will rebuild the index next time it runs.

# camera-ready: Accepted Paper → Camera-Ready + Review Implementation

For a paper that has been **accepted** (no rebuttal stage): produce the camera-ready version and implement the reviewers' (typically minor) revisions. Distinct from `strategic-revision --external`, which handles **R&R** (rebuttal, DAG, resubmission strategy).

## When to Use

- Acceptance notification arrived; reviews are final; you implement rather than argue.
- Triggers: "prepare the camera-ready", "implement the reviews for the accepted paper", "de-anonymize and finalize".

## Operating Rules (read first)

- **Overleaf-canonical**: edit the Overleaf/`paper/` symlink target, not any git mirror (`overleaf-canonical-source.md`). The `.tex` is a **live edit surface** — obey `reconcile-before-rewriting.md` (fresh-read, narrow edits, no `replace_all`/full-`Write`, mtime check).
- **Phased-work**: stop after each phase, summarize, await `continue` (`phased-work.md`) unless `--autonomous`.
- **mark-unverified**: never assert a reviewer-suggested citation/venue fact you haven't verified.

# Causal Design

> Design and audit identification strategies for observational causal inference.

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `causal-design`
- **Write reports to:** `reviews/<scope>/causal-design/<YYYY-MM-DD-HHMM>.md` inside the project, where `<scope>` is the paper slug (e.g. `paper-philtech`) for paper-level audits or `_project` for project-level reviews. Path is relative to the research project root, not the Task-Management repo.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** if today's timestamp exists, append a same-day descriptor to the path base (`{date}-HHMM-revision.md`, `{date}-HHMM-r2.md`, `{date}-HHMM-pre-submission.md`) — never overwrite.
- **Index update:** if `reviews/INDEX.md` exists, write a one-line entry under "Latest per source" pointing at the new file. Otherwise `review-recap` will rebuild the index next time it runs.
- **Infrastructure repos** (Task-Management, atlas-workspace, etc.): this section does not apply — the path-scoped rule won't load there.

# Checkpoint — Save Session State

Snapshot the current session's progress to a YAML file so it can be restored after context compaction or in a new session. This is NOT a session log (narrative) or context save (profile/focus) — it's a machine-readable state dump for continuity.

## When to Use

- Before a session is likely to hit context compression (many tool calls, long outputs)
- At phase boundaries in multi-phase work
- When the user says "save state", "checkpoint", "save progress"
- Proactively when you sense context is getting large — don't wait to be asked

## When This Skill Is Invoked

### Step 1: Gather State

# Code Audit Skill

**CRITICAL RULE: Never delete data or code files.** Copy to legacy/, never move or delete originals.

> Systematically review and understand old code, data, and analysis files.

## Purpose

Based on Scott Cunningham's workflow of reviving old projects - understanding what exists, documenting it, and making it safe to work with.

**For formal audits with cross-language replication and referee reports, use the Referee 2 agent (`.claude/agents/referee2-reviewer.md`).** This skill is for understanding and documenting existing code, not formal verification.

## When to Use

# Compile Knowledge

> Reads raw inputs from a project and compiles/updates a `knowledge/` wiki — a collection of LLM-maintained markdown articles that synthesise everything known about the project's domain.

## When to Use

- After a literature review to consolidate findings
- After a series of sessions on a project to build up the knowledge base
- When starting work on a project and wanting to understand the state of knowledge
- Periodically to keep the knowledge wiki fresh

## When NOT to Use

- For structural project audits — use an installed research-project audit workflow

# Computational Experiments

> Lifecycle skill for algorithmic research projects where the code IS the scientific contribution.

## Modes

| Mode | What it does | Phases |
|------|-------------|--------|
| **Scaffold** | Create/audit package structure + algorithm skeleton | 1–2 |
| **Experiment** | Design and run pre-specified sweep campaigns | 1, 3–4 |
| **Explore** | Adaptive experiment loop: modify → run → evaluate → keep/discard | 1, 3E–4 |
| **Autonomous** | Parallel self-correcting sweep with sub-agents | 1, 3A–4 |
| **Figures** | Generate publication output from results | 1, 4 |
| **Full** | Complete pipeline | 1–5 |

# Cross-Language Replication Check

> Level 1 of the verification hierarchy: same specification → same estimate across languages. If two independent implementations disagree, at least one has a bug.

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `cross-language-check`
- **Write reports to:** `reviews/<scope>/cross-language-check/<YYYY-MM-DD-HHMM>.md` inside the project, where `<scope>` is the paper slug (e.g., `paper-jtp`) for paper-level checks or `_project` for project-level checks. Path is relative to the research project root, not the Task-Management repo.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** if today's file exists, append a same-day descriptor (`{date}-revision.md`, `{date}-r2.md`, `{date}-pre-submission.md`) — never overwrite.
- **Index update:** if `reviews/INDEX.md` exists, write a one-line entry under "Latest per source" pointing at the new file. Otherwise `review-recap` will rebuild the index next time it runs.
- **Infrastructure repos** (Task-Management, atlas-workspace, etc.): this section does not apply — the path-scoped rule won't load there.

# Data Analysis Pipeline

> Generate, execute, and verify analysis scripts across R, Python, Stata, and Julia.

## Modes

| Mode | What it does | Phases |
|------|-------------|--------|
| **EDA** | Exploratory data analysis only | 1–2 |
| **Estimation** | Estimation + publication output (requires locked design) | 1, 3–4 |
| **Full** | Complete pipeline | 1–5 |

Default: **Full**. Detect mode from user request or ask if ambiguous.

# Devil's Advocate Skill

> Challenge research assumptions and identify weaknesses in your arguments.

## Purpose

Based on Scott Cunningham's Part 3: "Creating Devil's Advocate Agents for Tough Problems" - addressing the "LLM thing of over-confidence in diagnosing a problem."

**For formal code audits with replication scripts and referee reports, use the Referee 2 agent instead (`.claude/agents/referee2-reviewer.md`).** This skill is for quick adversarial feedback on arguments, not systematic audits.

## When to Use

- Before submitting a paper
- When stuck on a research problem

# Docs Review

> Cross-cutting documentation review that checks **consistency, accuracy, and completeness** across the entire documentation ecosystem. It verifies that docs agree with each other and with reality; installed per-repository audit or sync workflows can deepen the check but are not required.

## When to Use

- After adding, removing, or renaming skills, hooks, agents, or rules
- After major infrastructure changes (consolidation, new repos, renamed components)
- Before publishing or sharing the public repo
- Periodic health check (monthly)
- When the user says "review docs", "check my docs", "are my docs consistent"

## When NOT to Use

# DOCX creation, editing, and analysis

## Overview

A .docx file is a ZIP archive containing XML files.

## Quick Reference

| Task | Approach |
|------|----------|
| Read/analyze content | `pandoc` or unpack for raw XML |
| Create new document | Use `docx-js` — see [`references/docx-js-patterns.md`](references/docx-js-patterns.md) |
| Edit existing document | Unpack → edit XML → repack — see Editing below |

# Experiment Design

> Interview-driven design workflow producing design documents, power analysis scripts, and pre-analysis plans.

## Modes

| Mode | What it produces | Entry point |
|------|-----------------|-------------|
| **Power** | Power analysis script + sample size table | "How many participants do I need?" |
| **Design** | Full design document (hypotheses, conditions, measures, randomization) | "Design my experiment" |
| **PAP** | Pre-analysis plan (AEA/OSF/EGAP format) | "Write a PAP" |
| **Survey** | Structured survey specification from natural language or QSF | "Build a survey" / "Parse my Qualtrics" |

Default: **Design**. If user provides a `.qsf` file, auto-select Survey mode.

# Grill Me — Interactive Oral-Exam Drill

> You answer, out loud, one grounded question at a time. This skill plays a skeptical examiner and interrogates you — escalating on weak or evasive answers — then hands you a study sheet of what you fumbled, with model answers. Two flavours: **defend** your own research, or **study** a class you're learning.

## Two Modes (auto-detected; override with `--defend` / `--study`)

| | **Defend** | **Study** |
|---|---|---|
| Target | *Your own* paper / model / proof / research idea | A class, subject, textbook chapter, lecture notes you're *learning* |
| Goal | Rehearse defending your choices under pressure | Test + deepen recall and understanding of the material |
| "Right answer"? | No single right answer — you defend a *choice*; the examiner probes whether it holds | Yes — there's an objectively correct answer; wrong answers get corrected |
| Default persona | Skeptical-but-fair examiner (viva/referee) | Examiner-Socratic (an examiner who also teaches when you miss) |
| Prep for | Viva · job talk · seminar Q&A · referee/rebuttal armour | Exams · comprehension checks · learning a new field |

# Project Handoff

Use one client-neutral handshake for every route. Before acting, read `../shared/cross-client-handoff.md` completely and follow its schema and state machine.

## Choose the route

- If the user names Claude or Codex, use that client as `to`.
- If the user asks for the next or a fresh session without naming a client, set `to` to the current client. This is the default for Claude-to-Claude and Codex-to-Codex continuation.
- Use `to: either` only when the task is deliberately client-agnostic.
- Set `from` to the current client, or `human` when invoked outside a client session.

All routes write `<project-root>/.context/ai-handoff.md`. Do not create a separate client-specific handoff file.

## Prepare a handoff

# Ideas: Capture & Integrate

> An inbox for improvement ideas — the gap between `[LEARN]` tags (immediate corrections) and `skill-extract` (full skill creation). Captures raw improvement ideas and periodically integrates the best ones into the system.

## Two Modes

| Mode | Trigger | What it does |
|------|---------|-------------|
| **Capture** | `ideas capture [text]` | Append a structured idea entry to `log/ideas.md` |
| **Integrate** | `ideas integrate` | Review unprocessed ideas and turn them into actions |

---

## Mode 1: Capture

# Init Project — Research Project Scaffolder

> Interactive project setup: answer questions, get a ready-to-use research project directory.

## Protocol

### Phase 1: Interview

Ask the user these questions using `AskUserQuestion` (adapt based on what's already known):

1. **Project name** — short name for the directory (e.g., `nudge-experiment`)
2. **Paper title** — working title for the paper
3. **Research question** — one sentence
4. **Target journal/venue** — where you plan to submit

# Init Project Course

> Bootstrap a university course or module folder into a clean, navigable structure. Designed for taught modules with lectures, workshops, assessments, and optionally recordings.

## When to Use

- University modules with lectures + workshops + assessments
- Course folders that have accumulated files over a term
- When the user says "organise this module", "init course", "set up this module folder"
- Any taught course with recurring weekly components

## When NOT to Use — Escalate

- To `init-project-light` if it's a one-off document collection (no lectures/workshops structure)

# Init Project Light

> Lightweight project bootstrapper for small projects that do not need a full research-project scaffold.

## When to Use

- Small document collections (proposals, applications, meeting notes)
- One-off or short-lived projects
- Projects without a code pipeline or Overleaf link
- When the user says "set up something light", "quick init", "organise this folder"
- Any project that does not warrant the installation's full research-project initializer

## When NOT to Use — Escalate to a full research-project initializer

# Initialize project orchestration

Create the project source once under `.ai/orchestration/`. Treat Claude Code
and Codex files as generated adapters, never as parallel authoring surfaces.

## Resulting structure

```text
.ai/orchestration/                 # canonical, client-neutral source
├── manifest.yaml
├── agents/<role>.md
└── commands/<workflow>.md

.claude/agents/project-<role>.md   # generated Claude agent

# Insights Deck Skill

> Archive a Claude Code insights HTML export and generate a Beamer presentation summarising the findings. All outputs go to `log/insights/` with date stamps.

## When to Use

- After exporting the built-in Claude Code insights report
- 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.

# 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 the available structured-question mechanism.** Ask questions directly in your text responses, one or two at a time. Wait for the user to respond before continuing.

# Knowledge Lint

> Substantive consistency checks on the compiled knowledge wiki. Produces `correspondence/internal-reviews/KNOWLEDGE-LINT-REPORT.md`.

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `knowledge-lint`
- **Write reports to:** `reviews/_project/knowledge-lint/YYYY-MM-DD-HHMM.md` inside the project. Path is relative to the research project root, not the Task-Management repo.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** if today's file exists, append a same-day descriptor (`{date}-revision.md`, `{date}-r2.md`, `{date}-pre-submission.md`) — never overwrite.
- **Index update:** if `reviews/INDEX.md` exists, write a one-line entry under "Latest per source" pointing at the new file. Otherwise `review-recap` will rebuild the index next time it runs.
- **Infrastructure repos** (Task-Management, atlas-workspace, etc.): this section does not apply — the path-scoped rule won't load there.

# LaTeX Document Compilation

> Default compilation skill for all LaTeX documents. Compiles with autonomous error detection and resolution (up to 5 iterations), runs a citation audit on clean builds, and produces a quality score.

## When to Use

- **Default method** for all LaTeX compilation
- Any `.tex` file that should compile to PDF
- When compilation fails and you want automatic diagnosis and repair
- When you want a post-compilation citation audit

## When NOT to Use

- Markdown documents — use plain markdown, not LaTeX

# LaTeX Diff

> Compare two versions of a LaTeX document and report what actually changed —
> text, equations, citations, labels/refs, section titles, macros, environments,
> file add/remove, and moves — each graded by severity. Wraps the `latexdiff-agent`
> CLI (`packages/latex-diff`). Member of the `latex-*` source/build family.

## When to Use

- "What changed between these two versions of the paper?"
- Building an R&R "summary of changes" or a preprint vN→vN+1 changelog
- Focusing a re-review on the changes that matter (semantic-impact only)
- Sanity-checking a co-author's edits before merging

# LaTeX Health Check: Self-Healing Build Agent

> Compile all LaTeX projects, auto-fix known errors iteratively, and verify cross-project consistency (symlinks, shared bibliographies, Overleaf separation).

## When to Use

- Periodically (weekly) to catch build rot before it becomes debugging sessions
- After major infrastructure changes (template updates, symlink reorganisation)
- Before submission season to verify all papers compile cleanly
- When the user says "check my LaTeX", "build health", "compile everything"

## Modes

| Mode | Trigger | What it does |

# LaTeX Polish — Source Lint + Vision-On-Rendered-PDF

> Heavier-weight visual-quality review than `latex`. Combines the Phase 4 source-pathology lint with vision-model inspection of selected rendered PDF pages. Designed to catch the failure class that `latex` Phase 4 source-grep misses: blank pages, clipped tables, illegible shrunken figures, weird title-page line spacing that the regex couldn't fingerprint, bad float placement, overlap.

## When to Use

- Pre-submission visual check on a paper, proposal, thesis, or deck
- After major restructuring (new sections, table re-layouts, figure swaps) when you want eyes on the rendered output
- When `latex` reports a clean build but something still "looks weird"
- When preparing for a panel / supervisor read where presentation matters

## When NOT to Use

| Need | Use instead |

# LaTeX Research Posters

## Overview

Research posters are a critical medium for scientific communication at conferences, symposia, and academic events. This skill provides comprehensive guidance for creating professional, visually appealing research posters using LaTeX packages.

## When to Use This Skill

- Creating research posters for conferences, symposia, or poster sessions
- Designing academic posters for university events or thesis defenses
- Converting scientific papers into poster format
- Creating template posters for research groups or departments

## Compilation Convention

# LaTeX Scaffold

Convert an approved Markdown draft into a minimal, compilable LaTeX project. This is a **deterministic format conversion** — prose quality should already be addressed in the source draft.

## When to Use

- Converting a literature review, survey, or report from Markdown to LaTeX for PDF output
- Turning meeting notes or drafts into a formatted document
- Bootstrapping a LaTeX project from an existing outline
- Any time you need md→tex without rewriting content

## Inputs

- A Markdown file (`.md`) — the draft to convert

# Template Compliance

> Compare a research project's LaTeX preamble against the working-paper template bundled with the installed `latex` skill. Classify every difference, produce a scored report, and optionally apply changes interactively.

## When to Use

- After the template has been updated and you want to check older papers
- Before submission — verify the preamble is clean and up to date
- When a paper has mysterious compilation issues (often a stale preamble)
- During periodic maintenance or `system-audit`
- When starting work on a paper that hasn't been touched in a while

## When NOT to Use

# Lean Check: Machine-Prove a Self-Authored Lemma

Formalize a lemma/theorem in Lean 4 + mathlib and let the kernel check it. A `lake build` that succeeds **with no `sorry` and no extra axioms** is a machine-verified proof — the strongest guarantee available.

## When to Use

- A **critical lemma** whose correctness you want beyond doubt (the load-bearing step of a theorem).
- `lean-check`, "formalize this in Lean", "machine-check this lemma", "prove this in Lean 4".
- After `numerical-check` fails to falsify a claim and it's important enough to *prove*.

## When NOT to Use

| Situation | Use instead |
|---|---|

> **Author:** Moran Koren, Ben-Gurion University of the Negev (korenmor@bgu.ac.il). Part of the [Theorist Toolbox](https://github.com/morankor/theorist-toolbox).


# Math proof

Write rigorous mathematical proofs suitable for peer-reviewed academic papers. Every step should be explicit enough that a reader can verify it without filling in gaps. The proof must be a complete proof, not a proof outline — each step should be carefully explained and documented.

## Trigger phrases

- `math-proof`
- "prove this"
- "show analytically"
- "derive this result"
- "justify mathematically"

# MCP Server Development Guide

## Overview

Create MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.

---

# Process

## 🚀 High-Level Workflow

Creating a high-quality MCP server involves four main phases:

# Method Audit

> Reverse-engineer the data collection and empirical methods across a corpus of papers. Produce a critical comparison table that surfaces methodological blind spots.

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `method-audit`
- **Write reports to:** `reviews/_project/method-audit/<YYYY-MM-DD-HHMM>.md` inside the project. Path is relative to the research project root, not the Task-Management repo.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** timestamps include hour+minute (HHMM) to disambiguate same-day runs; never overwrite an earlier run's report.
- **Index update:** if `reviews/INDEX.md` exists, write a one-line entry under "Latest per source" pointing at the new file. Otherwise `review-recap` will rebuild the index next time it runs.
- **Infrastructure repos** (Task-Management, atlas-workspace, etc.): this section does not apply — the path-scoped rule won't load there.

# Multi-Perspective Exploration

Spawn 3-5 parallel agents, each with a distinct disciplinary lens and epistemic prior, to independently investigate a research question. Then synthesise their findings into a structured comparison that surfaces agreements, tensions, and blind spots.

The core insight: a single-perspective analysis inherits the biases of that perspective. Deliberately introducing cognitive diversity — grounded in real disciplinary traditions — produces more robust research designs.

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `multi-perspective`
- **Write reports to:** `reviews/<scope>/multi-perspective/YYYY-MM-DD-HHMM.md` inside the project, where `<scope>` is the paper slug (e.g., `paper-jtp`, `paper-philtech`) for paper-level reviews or `_project` for project-level reviews. Path is relative to the research project root, not the Task-Management repo.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** the timestamp includes minutes (`YYYY-MM-DD-HHMM`), so same-day runs are naturally separated. If multiple reports are generated in the same minute, append a descriptor (`{timestamp}-r2.md`, `{timestamp}-revision.md`) — never overwrite.

# Numerical Check: Falsify a Self-Authored Math Claim by Sweep

Empirically stress-test a mathematical claim you wrote but have not proven. The goal is **falsification**: throw many random instances at the claim and try to break it. A single genuine counterexample kills the claim; a large clean sweep is *evidence*, never proof.

## When to Use

- You wrote a **Proposition / Theorem / Conjecture** (monotonicity, threshold, comparative-static, inequality, closed-form, limit) and want to know if it's actually true before claiming it.
- `numerical-check`, "stress-test my conjecture", "find a counterexample to X", "is Q(ρ) really monotone", "does the threshold hold for all …".
- The write-time empirical arm of the `mark-unverified` rule (self-authored math must be checked before assertion).

## When NOT to Use

| Situation | Use instead |
|---|---|

# PDF Processing Guide

## Overview

This guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see REFERENCE.md. If you need to fill out a PDF form, read FORMS.md and follow its instructions.

## Quick Start

```python
from pypdf import PdfReader, PdfWriter

# Read a PDF
reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

# Pipeline Manifest

Build and maintain a `pipeline.md` that maps every script in a research project to its inputs, outputs, and the paper figures/tables it feeds. Optionally add structured headers to scripts that lack them.

## When to Use

- When starting a multi-step empirical project (establish the pipeline early)
- Before sharing code with coauthors (makes the data flow legible)
- Before submission (ensures the replication package is traceable)
- After inheriting or reviving old code (pair with `code-archaeology`)
- When you can't remember which script produces Figure 3

## When NOT to Use

# Browser Automation with playwright-cli

Use this skill for ad-hoc browser navigation, inspection, and interaction using
CLI snapshots. When a local application needs managed server startup, custom
Python assertions, or a repeatable Python test script, use `$webapp-testing`.

## Quick start

```bash
# open new browser
playwright-cli open
# navigate to a page
playwright-cli goto https://playwright.dev
# interact with the page using refs from the snapshot

# Lessons Learned: Structured Retrospective

Analyse incidents using a structured framework, identify root causes, and encode preventive measures directly into skills, guards, or documentation. The goal is systematic improvement, not blame.

## When to Use

- After incidents, mistakes, rollbacks, or near-misses
- When the user says "what went wrong", "lessons learned", "post-mortem", "retrospective", or "how do we prevent this"
- After a stuck session where significant time was lost
- After a wrong-approach event (plan existed but execution diverged)

## Process

### Phase 1: Incident Definition

# Pre-Commit Audit — File Size, Anonymity, Secrets

> Three-pass safety scan before commit. Blocks pain-points: oversized commits (1.3GB parquet incident), CCS-style anonymity breaches, leaked credentials. Each pass is a hard gate; user OKs proceed.

## Hard Rules

### Existential — block proceed

1. **Size pass blocks anything >10MB unless gitignored OR user explicitly approves.** Threshold matches `block-large-files.sh` hook for consistency.
2. **Anonymity pass runs only on paper-relevant paths**: `paper-*/`, `*.tex`, `*.bib`, `*.md` inside paper directories. Scope is data-driven — we don't false-flag README authorship.
3. **Secrets pass uses an entropy heuristic + known-prefix list.** No regex-only matching that misses high-entropy keys. Block on confirmed secret; warn on suspicious-but-uncertain.
4. **All four passes run on the same file set** (default: staged for commit). Don't mix staged-only size check with all-files anonymity check.
5. **The Unicode pass is the one pass that is always in scope**, including infra-only commits. It is identity-blind — it reads codepoints, never names — so it cannot false-flag authorship the way the anonymity pass can.

# Pre-Submission Report

> Aggregates all quality checks into one dated report. Run before submitting to a journal/conference or sharing with collaborators.

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `pre-submission-report`
- **Write reports to:** `reviews/<paper-slug>/pre-submission-report/<YYYY-MM-DD-HHMM>.md` inside the project, where `<paper-slug>` is the paper directory name being reviewed (e.g., `paper-jtp` if reviewing `paper-jtp/main.tex`). Path is relative to the research project root, not the Task-Management repo.
- **Citation-integrity companion:** when citation integrity runs, write `<YYYY-MM-DD-HHMM>.citation-integrity.json` beside the report. It is a typed companion, not a second report or INDEX row.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** if the minute-based timestamp file exists, append a same-run descriptor (`{timestamp}-r2.md`, `{timestamp}-revision.md`) — never overwrite.
- **Index policy:** the aggregate pre-submission report is an output-only artefact and receives no `Check=pre-submission-report` row. Each reporting gate/check receives its own row with `Trigger=pre-submission-report`.

# Project Deck Skill

> Create beautiful presentation decks to communicate project status to your future self and collaborators.

## Purpose

Based on Scott Cunningham's Part 7: "Making Beautiful Decks For My Future Self" - using decks not for public speaking but to efficiently communicate work status across time and to coauthors.

## The Philosophy

"I use decks to help me keep track of the work I was doing so that I can communicate it to my coauthors and myself later in the week when we meet to go over our projects."

Claude has absorbed the "rhetoric of decks" - the tacit knowledge about what makes presentations effective:
- One idea per slide

# Project Safety Skill

**CRITICAL RULE: Never delete data or code files. Never.** Use legacy/ folder for originals. Copy, don't move.

> Establish safety rules and structures before Claude makes changes to research projects.

## Purpose

Based on Scott Cunningham's workflow: prevent accidental data loss by establishing rules and using legacy folders before Claude reorganizes or modifies project files.

## When to Use

- Starting a new research project folder
- Before asking Claude to reorganize files

> **Author:** Moran Koren, Ben-Gurion University of the Negev (korenmor@bgu.ac.il). Part of the [Theorist Toolbox](https://github.com/morankor/theorist-toolbox).

# Proof readability

> **Relationship to `proofread`:** `proofread` is a *report-only*, whole-paper prose checker (11 categories, never edits source). `proof-readability` *edits in place*, is proof-specific, runs only after a correctness gate, and holds a content-preservation invariant `proofread` does not. Audit a whole paper's prose → `proofread`; edit the exposition of a verified proof → `proof-readability`.

Edit verified proofs so a reader can follow them without reconstructing steps, chasing broken references, or decoding notation. This skill runs *after* a proof has been written (e.g., by `math-proof`) and *after* its correctness has been verified (by `domain-reviewer`, `lean-check`, or the user). It is an exposition pass, not a proving pass.

## Position in the pipeline

```
math-proof  →  verification (domain-reviewer / lean-check / user)  →  proof-readability
   (correctness)              (acceptance)                  (exposition only)
```

# Academic Proofreading

**Report-only skill.** Never edit source files — produce `reviews/<scope>/proofread/<YYYY-MM-DD-HHMM>.md` only (where `<scope>` is the paper slug, e.g. `paper-jtp`).

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `proofread`
- **Write reports to:** `reviews/<scope>/proofread/YYYY-MM-DD.md` inside the project, where `<scope>` is the paper slug (e.g., `paper-jtp`). Path is relative to the research project root, not the Task-Management repo.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** if today's file exists, append a same-day descriptor (`{date}-revision.md`, `{date}-r2.md`, `{date}-pre-submission.md`) — never overwrite.
- **Index update:** if `reviews/INDEX.md` exists, write a one-line entry under "Latest per source" pointing at the new file. Otherwise `review-recap` will rebuild the index next time it runs.
- **Infrastructure repos** (Task-Management, atlas-workspace, etc.): this section does not apply — the path-scoped rule won't load there.

# Python Environment Management

**CRITICAL RULE: Never use `pip` directly. Always use `uv`.** This applies to all Python package management.

## Golden Rule

**ALWAYS use `uv` for Python package and environment management. Never use `pip` directly.**

## Commands

| Task | Command |
|------|---------|
| Create venv | `uv venv` |
| Install package | `uv pip install <package>` |

# Quarto Deck

> Build browser-native slide decks with Quarto Reveal.js. Same rhetoric framework
> as `beamer-deck`, HTML output that can be shared as a URL, run live code, and
> still print to PDF.

## Purpose

Create one presentation as a `.qmd` file: assertion titles, a three-act arc, a
theme with reusable layout classes, speaker notes, figures generated from code,
and a deck that has been linted, reviewed and looked at slide by slide.

**Use this for:** teaching (workshops and classes), informal research talks,
web-shared decks, decks with live R/Python cells.

# reorg — local-model file reorganiser

Conversational front-end for the `local-reorg` CLI (`scripts/local-reorg/`). The CLI runs a
**local Ollama model on the Mac Mini** that reads each file's content and proposes where it
should go, or finds duplicates. Nothing is ever moved without your approval, and every run
is reversible.

## When to use

- "Reorganise / tidy / sort this folder" where you want the model to **read** files, not
  just pattern-match filenames.
- "Find duplicates" / "dedup this folder" (exact + near-duplicate via embeddings).
- General clutter (Downloads, Desktop, a messy project subfolder).

# Replication Audit

> Examine which findings in a literature have been replicated, failed to replicate, or never been tested. Flag papers that build on non-replicated foundations.

Don't build your dissertation on a foundation made of sand.

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `replication-audit`
- **Write reports to:** `reviews/<scope>/replication-audit/<YYYY-MM-DD-HHMM>.md` inside the project, where `<scope>` is the paper slug (e.g., `paper-jtp`) for paper-level reviews or `_project` for project-level reviews. Path is relative to the research project root, not the Task-Management repo.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** if the run timestamp already exists, append a same-run descriptor (`{timestamp}-revision.md`, `{timestamp}-r2.md`) — never overwrite the same `<YYYY-MM-DD-HHMM>` path.

# Replication Package — Assemble, Anonymize, and Audit

> Build publication-ready replication packages, optionally anonymize for double-blind review, or audit an existing package for reproducibility. The original project is never modified.

## Modes

| Mode | What it does | Use case |
|------|-------------|----------|
| **Assemble** | Clean copy + AI trace removal + AEA-style README | Sharing, Zenodo deposit, journal supplementary |
| **Blind** | Everything in Assemble + identity anonymization | Double-blind conference/journal submission |
| **Audit** | Read-only 11-check reproducibility validation | Pre-deposit quality gate, self-check |

**Default mode:** Assemble. Infer Blind if the user says "anonymize", "double-blind", or "blind review". Infer Audit if the user says "audit", "check reproducibility", or "validate package".

# Retarget Journal Skill

> Switch a paper manuscript from one journal to another. Handles folder renaming, bibliography swaps, citation key updates, formatting changes, and compilation verification.

## When to Use

- Switching a paper's target venue (e.g., Journal A to Journal B, Journal C to Journal D)
- After a rejection when resubmitting to a different journal
- When strategic decisions change the target venue mid-drafting

## Before Starting

Ask the user for:

# Review Cluster — Mid-Draft Adversarial Feedback

> Parallel fan-out of a 4-agent read-only core on an active-drafting paper, optionally adding clarity-reviewer as a fifth agent, with auto-synthesise downstream. Lighter than `pre-submission-report --parallel`; designed for tight iteration, not final-gate verification. Outputs `reviews/<scope>/review-cluster/YYYY-MM-DD-cluster-report.md` (scope = paper slug from the paper path).

## Output Path

Per `rules/review-artefact-routing.md` (auto-loads in research projects (path-scoped to `paper-*/` and `paper/`)):

- **Source slug:** `review-cluster`
- **Write reports to:** `reviews/<scope>/review-cluster/YYYY-MM-DD.md` (scope = paper slug) inside the project. Path is relative to the research project root, not the Task-Management repo.
- **Never** at project root (`./CRITIC-REPORT.md`-style filenames are forbidden — pre-rule layout).
- **Idempotency:** if today's file exists, append a same-day descriptor (`{date}-revision.md`, `{date}-r2.md`, `{date}-pre-submission.md`) — never overwrite.
- **Index policy:** the consolidated cluster report is an output-only artefact and receives no `Check=review-cluster` row. Each active reviewer receives its own row with `Trigger=review-cluster`.
- **Infrastructure repos** (Task-Management, atlas-workspace, etc.): this section does not apply — the path-scoped rule won't load there.

# Review Response

Systematic workflow for responding to reviewer comments on academic papers. Covers the full cycle from parsing comments through to a polished rebuttal document.

## When to Use

- "Help me write a rebuttal"
- "Respond to reviewer comments"
- "Handle this R&R"
- "Develop a review response strategy"
- Paper has received referee reports and needs a structured response

## Workflow

# Context Status: Session Health Check

On-demand diagnostic showing context usage, preservation state, and open work items. Fast and lightweight — no vault queries.

## What to Check

### 1. Context Usage Estimate (host-aware)

Use the active client's native context meter when it is exposed. A client adapter may provide a tool-call counter, but it is optional and must never be treated as shared memory. If no meter is available, report `SKIPPED (client does not expose context telemetry)`; do not guess a percentage from conversation length.

Calculate:
- Tool calls so far
- Estimated percentage (calls / 150)
- Which thresholds have fired (from the `fired` array)

# Session Log Skill

> Automatically create timestamped progress logs for research sessions.

## Purpose

Based on Scott Cunningham's session workflow: “Progress logs are my autosave of the workflow.” When sessions end or crash, the next AI client 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

# Skill Creator

A skill for creating new skills and iteratively improving them.

At a high level, the process of creating a skill goes like this:

- Decide what you want the skill to do and roughly how it should do it
- Write a draft of the skill
- Create a few test prompts and run claude-with-access-to-the-skill on them
- Help the user evaluate the results both qualitatively and quantitatively
  - While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
  - Use the `eval-viewer/generate_review.py` script to show the user the results for them to look at, and also let them look at the quantitative metrics
- Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks)
- Repeat until you're satisfied

# Learn: Session Knowledge Extraction

Extract reusable workflows, workarounds, and multi-step procedures discovered during a session into persistent skills. Complementary to the `learn-tags` rule — while `[LEARN]` tags record one-liner corrections in MEMORY.md, `skill-extract` creates full skill definitions in `skills/`.

## When to Use

- You discovered a non-obvious multi-step procedure
- You built a workaround for a recurring problem
- You developed a workflow that future sessions would benefit from
- the user says "save this as a skill", "learn this", or "remember how to do this"

## Phase 1: Evaluate

Before creating anything, answer these 4 self-assessment questions:

# Creation Guard: Pre-Flight Duplicate Check

Prevent duplicate functionality by analysing existing skills, agents, and rules before creating new ones. Intercepts creation intent, searches for overlap, and recommends one of 5 actions.

## When to Use

Invoke **before** creating ANY new:
- Skill (`skills/*/SKILL.md`)
- Agent (`.claude/agents/*.md`)
- Rule (`rules/*.md`)

Trigger phrases:
- "Create a skill for..."
- "I want a new skill that..."

# Split-PDF: Download, Split, and Deep-Read Academic Papers

**CRITICAL RULE: Never read a full PDF. Never.** Only read the 4-page split files, and only 3 splits at a time (~12 pages). Reading a full PDF will either crash the session with an unrecoverable "prompt too long" error — destroying all context — or produce shallow, hallucinated output. There are no exceptions.

## When This Skill Is Invoked

The user wants you to read, review, or summarize an academic paper. The input is either:
- A file path to a local PDF (e.g., `./articles/smith_2024.pdf`)
- A search query or paper title (e.g., `"Gentzkow Shapiro Sinkinson 2014 competition newspapers"`)

**Important:** You cannot search for a paper you don't know exists. The user MUST provide either a file path or a specific search query. If the user invokes this skill without specifying what paper to read, ask them. Do not guess.

**Prefer Paperpile when possible.** If the paper is in Paperpile, call `paperpile get-pdf-text(citekey=KEY)` directly — you get the full structured text without any splitting. Only fall through to this skill's page-split workflow when the PDF is NOT in Paperpile (preprints, referee materials, ad-hoc reading, third-party shared PDFs).