flonat-research 0.1.0

package/skills/latex-autofix/references/known-errors.md

@@ -0,0 +1,183 @@
+# Known Error Patterns & Auto-Fixes
+
+> Reference file for `/latex-autofix`. Each pattern maps a log signature to a fix.
+
+## 1. Missing package
+
+**Log pattern:**
+```
+! LaTeX Error: File `<package>.sty' not found.
+```
+or
+```
+! Undefined control sequence.  ...  \<command>
+```
+where the undefined command belongs to a well-known package.
+
+**Fix:** Add `\usepackage{<package>}` to the preamble (before `\begin{document}`). Place it after existing `\usepackage` lines. Common mappings:
+
+| Command | Package |
+|---------|---------|
+| `\includegraphics` | `graphicx` |
+| `\url`, `\href` | `hyperref` |
+| `\toprule`, `\midrule`, `\bottomrule` | `booktabs` |
+| `\multirow` | `multirow` |
+| `\lstlisting` | `listings` |
+| `\tikz`, `\begin{tikzpicture}` | `tikz` |
+| `\xspace` | `xspace` |
+| `\adjustbox` | `adjustbox` |
+| `\subcaption`, `\subfigure` | `subcaption` |
+| `\sisetup`, `\SI` | `siunitx` |
+| `\algorithm` | `algorithm2e` or `algorithmicx` |
+
+If the package is unclear, report it as unresolved rather than guessing.
+
+## 2. Font / symbol conflicts
+
+**Log pattern:**
+```
+Command \<name> already defined.
+```
+Common case: `\Bbbk` conflict between `amssymb` and `newtxmath`.
+
+**Fix:** Add a `\let` override **before** the conflicting package:
+
+```latex
+% Fix font conflict: \Bbbk defined by both amssymb and newtxmath
+\let\Bbbk\relax
+```
+
+For the specific `amssymb` / `newtxmath` conflict, insert `\let\Bbbk\relax` between the two `\usepackage` lines. More generally:
+
+- Read the error to identify which command is multiply defined
+- Add `\let\<command>\relax` before the second package that defines it
+- If multiple commands conflict, add a `\let` for each
+
+## 3. Undefined citation
+
+**Log pattern:**
+```
+LaTeX Warning: Citation `<key>' on page <n> undefined
+```
+or (with biblatex/biber):
+```
+Package biblatex Warning: ... Entry '<key>' ... not found
+```
+
+**Fix:**
+1. Read the `.bib` file(s) identified in Phase 1.
+2. Search for the citation key. Check for:
+   - **Typo:** fuzzy-match against all keys in the `.bib` (e.g., `smith2020` vs `Smith2020`, `santanna2020` vs `santanna2020doubly`).
+   - **Missing entry:** the key genuinely doesn't exist in the `.bib`.
+3. If a close match is found, fix the `\cite{<key>}` in the `.tex` file.
+4. If no match exists, report as unresolved — do **not** fabricate bibliography entries.
+
+## 4. Missing image / file path
+
+**Log pattern:**
+```
+! LaTeX Error: File `<path>' not found.
+```
+or
+```
+! Package pdftex.def Error: File `<path>' not found
+```
+
+**Fix:**
+1. Extract the filename from the error.
+2. Search the project directory recursively for a file with that name (using Glob).
+3. If found, update the `\includegraphics` (or `\input`, `\include`) path in the `.tex` file.
+4. If not found, report as unresolved.
+
+## 5. Stale auxiliary / cache files
+
+**Log pattern:** Errors that reference corrupted `.aux`, `.bbl`, `.bcf`, `.toc`, or `.idx` files, or error messages like:
+```
+I found no \bibstyle command
+```
+```
+I found no \citation commands
+```
+```
+\openout ... already open
+```
+or when the same error persists after a seemingly correct fix.
+
+**Fix:**
+1. Run `latexmk -C -outdir=out` in the project directory to clean all generated files.
+2. Delete `out/` contents if `latexmk -C` doesn't clear them.
+3. Restart the compile loop from Step 2a (this counts as one iteration).
+
+## 6. Beamer package conflicts (enumitem)
+
+**Log pattern:**
+```
+Option clash for package enumitem
+```
+or
+```
+Command \item already defined
+```
+when using `enumitem` with beamer.
+
+**Fix:** Beamer redefines `\item` internally, so enumitem often clashes. First check if enumitem is actually needed — if only used for basic lists, remove it (beamer handles lists natively). If enumitem features are required (custom labels, spacing), replace:
+
+```latex
+% Before (conflicts with beamer):
+\usepackage{enumitem}
+
+% After:
+\usepackage[shortlabels]{enumitem}
+\setlist[itemize]{label=\textbullet}
+```
+
+If the conflict is with a non-beamer class, the `shortlabels` option alone usually resolves it.
+
+## 7. xcolor option conflicts
+
+**Log pattern:**
+```
+Option clash for package xcolor
+```
+or
+```
+Undefined control sequence. \rowcolor
+```
+(when `table` option is missing from xcolor).
+
+**Fix:** xcolor must be loaded with all needed options **before** any package that loads it implicitly (e.g., `tikz`, `tcolorbox`, `beamer`). Two approaches:
+
+```latex
+% Approach 1: Load xcolor early with all options
+\usepackage[table,dvipsnames,svgnames]{xcolor}
+% ... then load tikz, tcolorbox, etc.
+
+% Approach 2: If another package loads xcolor first, use PassOptionsToPackage
+\PassOptionsToPackage{table,dvipsnames,svgnames}{xcolor}
+\documentclass{...}
+```
+
+Common missing options: `table` (for `\rowcolor`, `\cellcolor`), `dvipsnames` (for named colours like `ForestGreen`), `svgnames` (for web colours).
+
+## 8. TikZ reserved key conflicts
+
+**Log pattern:**
+```
+I do not know the key '/tikz/<name>'
+```
+or
+```
+Package pgfkeys Error: I do not know the key '/tikz/<name>'
+```
+
+**Fix:** TikZ reserves many common English words as keys. If a custom key name conflicts, rename it:
+
+```latex
+% Before (conflicts — 'step' is a reserved TikZ key):
+\tikzset{step/.style={...}}
+
+% After:
+\tikzset{mystep/.style={...}}
+```
+
+Common reserved names that cause conflicts: `step`, `at`, `node`, `draw`, `fill`, `path`, `scale`, `shift`, `rotate`, `color`, `text`, `inner sep`, `outer sep`. Rename custom keys to avoid these (e.g., `stepsize`, `mynode`, `drawstyle`).

package/skills/latex-autofix/references/quality-rubric.md

@@ -0,0 +1,50 @@
+# Quality Rubric: LaTeX Auto-Fix
+
+> Scoring rubric for `/latex-autofix`. Uses the shared framework in [`../../shared/quality-scoring.md`](../../shared/quality-scoring.md).
+
+## Deduction Table
+
+### Blocker (-100)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| Compilation fails after 5 fix iterations | -100 | No PDF produced |
+| PDF produced but with fatal rendering errors (blank pages, missing content) | -100 | Output is unusable |
+
+### Critical (-15 to -25)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| Unresolved `\cite{}` — `??` or `[?]` in output | -15 | Per unique broken citation key |
+| Unresolved `\ref{}` — `??` in output | -15 | Per unique broken reference |
+| Auto-fix changed user intent (e.g., wrong citation key substituted) | -25 | Per instance — silent corruption |
+
+### Major (-5 to -14)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| Overfull hbox > 10pt remaining | -5 | Per instance |
+| Missing `.latexmkrc` or incorrect `$out_dir` config | -10 | Build hygiene failure |
+| Stale auxiliary files causing warnings | -5 | Should have been caught by cache clean |
+| Package added but not strictly necessary | -5 | Per unnecessary package |
+| Cited keys in `.tex` not found in `.bib` (audit) | -8 | Per missing key |
+| Unused keys in `.bib` (audit, >20% unused) | -5 | Once for the pattern |
+
+### Minor (-1 to -4)
+
+| Issue | Deduction | Notes |
+|-------|-----------|-------|
+| Overfull hbox 1-10pt | -2 | Per instance |
+| Underfull hbox/vbox warnings | -1 | Per instance |
+| Font substitution warnings | -2 | Per unique substitution |
+| Multiple compilation iterations needed (>2) | -1 | Per extra iteration beyond 2 |
+
+## Category Mapping
+
+| Rubric category | Phase |
+|----------------|-------|
+| Pre-flight config | Phase 1 |
+| Compilation errors | Phase 2 |
+| Auto-fix quality | Phase 2 (fix accuracy) |
+| Remaining warnings | Phase 3 |
+| Citation audit | Phase 4 |

package/skills/latex-health-check/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: latex-health-check
+description: "Use when you need to compile all LaTeX projects and check cross-project consistency."
+allowed_tools:
+  - Read
+  - Edit
+  - Write
+  - Glob
+  - Grep
+  - Bash(latexmk*)
+  - Bash(pdflatex*)
+  - Bash(biber*)
+  - Bash(bibtex*)
+  - Bash(ls*)
+  - Bash(mkdir*)
+  - Bash(cp*)
+  - Bash(ln*)
+  - Bash(wc*)
+  - Bash(readlink*)
+argument-hint: "[project-path | 'all' | 'quick']"
+---
+
+# 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 |
+|------|---------|-------------|
+| **Single project** | Path argument | Compile + fix + verify one project |
+| **All projects** | `all` argument | Discover and compile every LaTeX project |
+| **Quick** | `quick` argument | Compile only, no fixes, report errors |
+
+## Phase 1: Discover LaTeX Projects
+
+Find all directories containing a `\documentclass` in a .tex file:
+
+Search locations (read from config, detect which exist):
+- Research root from `~/.config/task-mgmt/research-root` (fallback: `~/Projects/`)
+- `$TM/docs/`
+
+For each discovered project, record:
+- Project name (directory name)
+- Main .tex file path
+- Whether it has a `.latexmkrc`
+- Whether it has an `out/` directory
+- Whether it's inside a `paper/` subdirectory (Overleaf-linked)
+
+## Phase 2: Build Loop (per project)
+
+For each project:
+
+### 2a. Pre-flight
+- Check for `.latexmkrc` — create if missing (with `$out_dir = 'out'` and PDF copy-back)
+- Create `out/` directory if missing
+
+### 2b. Compile
+```bash
+cd <project-dir> && latexmk -interaction=nonstopmode <main.tex> 2>&1
+```
+
+**Engine selection:** Do NOT hardcode `-pdf`. The project's `.latexmkrc` (created in 2a) controls the engine — it auto-detects xelatex via `fontspec`, or defaults to pdflatex. Passing `-pdf` overrides this and breaks xelatex/lualatex projects. Let latexmk read `.latexmkrc`.
+
+### 2c. Parse log
+Extract from `out/*.log`:
+- Error count (lines starting with `!`)
+- Warning count (Overfull/Underfull hbox/vbox)
+- Undefined citation count
+- Missing package count
+
+### 2d. Auto-fix (up to 3 iterations)
+
+For each error, apply the known fix from the database:
+
+| Error pattern | Fix |
+|--------------|-----|
+| Missing package `X` | Add `\usepackage{X}` — but NEVER try `xltabular` or `ltablex` (use `longtable` instead) |
+| Undefined citation `key` | Check .bib file exists and is referenced; check for typos via edit distance |
+| Overfull hbox | Flag location and width — do NOT auto-fix (requires human judgment) |
+| tcolorbox `=` or `,` in title | Wrap title in braces: `title={...}` |
+| Font encoding warning | Add `\usepackage[T1]{fontenc}` if missing |
+| Missing `\begin{document}` | Check for corrupted preamble |
+| Broken symlink in `\input{}` or `\includegraphics{}` | Find the target and report |
+| Build artifacts in source dir | Flag — offer to move to `out/` |
+
+After each fix, recompile. Max 3 iterations per project.
+
+**Why 3 iterations (not 5)?** `/latex-autofix` runs up to 5 iterations on a single project with deep error analysis. This skill trades depth for breadth — 3 iterations is enough to catch the common fleet-wide issues (missing packages, broken symlinks, stale cache) without spending excessive time on any one project. If a project still has errors after 3 iterations, mark it as ERROR and recommend running `/latex-autofix` on it directly for deeper diagnosis.
+
+### 2e. Record result
+```json
+{
+  "project": "project-name",
+  "path": "/full/path",
+  "status": "OK | FIXED | ERROR",
+  "errors_initial": 3,
+  "errors_final": 0,
+  "fixes_applied": ["added fontenc", "fixed tcolorbox title"],
+  "warnings": 2,
+  "undefined_citations": 0
+}
+```
+
+## Phase 3: Cross-Project Checks
+
+After all projects are compiled:
+
+1. **Symlink integrity** — verify all symlinks in skills/, agents/, rules/, hooks/ resolve
+2. **Shared .bib consistency** — if multiple projects reference the same .bib file (e.g., via symlink), verify they're all pointing to the same version
+3. **Overleaf separation** — scan every `paper/` directory for forbidden file types (.py, .R, .csv, .ipynb, etc.)
+4. **Template consistency** — check if projects using the working paper template have diverged from the current template version
+
+## Phase 4: Report
+
+Generate a summary report:
+
+```
+LaTeX Health Check — YYYY-MM-DD
+
+Projects scanned:  N
+Compiled OK:       N (list)
+Fixed and OK:      N (list + fixes applied)
+Still broken:      N (list + remaining errors)
+Skipped:           N (list + reason)
+
+Cross-project issues:
+  Broken symlinks:        N
+  Overleaf violations:    N
+  Template drift:         N
+
+Warnings (not auto-fixed):
+  Overfull hboxes:        N across M projects
+  Underfull hboxes:       N across M projects
+```
+
+Print to stdout. If `--save` flag or 10+ projects scanned, also write to `log/latex-health/YYYY-MM-DD.md`.
+
+## What This Skill Does NOT Do
+
+- Does NOT fix overfull/underfull boxes (requires human judgment on rewording)
+- Does NOT modify paper content (only build configuration and missing packages)
+- Does NOT push to git (compilation fixes should be reviewed first)
+- Does NOT touch Overleaf-synced files without permission (per overleaf-separation rule)
+
+## Cross-References
+
+| Skill | Relationship |
+|-------|-------------|
+| `/latex-autofix` | Single-project deep fix (5 iterations). This skill runs a lighter version (3 iterations) at fleet scale. For ERROR projects, recommend running `/latex-autofix` directly. |
+| `/latex` | Manual compilation config and `.latexmkrc` reference — health-check creates `.latexmkrc` files using the conventions defined there. |
+| `/audit-project-research` | Checks project structure (directories, files). This skill checks build health. |
+| `/bib-validate` | Validates bibliography entries. This skill checks if citations compile. |
+| `/latex-template` | Checks preamble alignment with the working paper template. Complementary: run after health-check to ensure preamble consistency. |

package/skills/learn/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: learn
+description: "Extract reusable knowledge from the current session into a persistent skill.\nUse when you discover something non-obvious, create a workaround, or develop\na multi-step workflow that future sessions would benefit from."
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash(uv run python*)
+  - AskUserQuestion
+---
+
+# 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, `/learn` 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:
+
+1. **Non-obvious?** Would a future session figure this out without help, or would it waste time rediscovering it?
+2. **Future benefit?** Will this come up again across sessions or projects?
+3. **Repeatable?** Is this a procedure that can be followed step-by-step, or was it a one-off?
+4. **Multi-step?** Does it involve 2+ non-trivial steps that benefit from being documented together?
+
+**Decision rule:** If at least 3 of 4 answers are "yes", proceed to Phase 2. Otherwise, suggest recording as a `[LEARN]` tag in MEMORY.md instead (simpler, lower overhead).
+
+If borderline, ask the user:
+> "This seems useful but may not warrant a full skill. Should I create a skill or just add a [LEARN] tag to MEMORY.md?"
+
+## Phase 2: Creation Guard + Read Patterns
+
+Run the **creation-guard** analysis (see [`skills/creation-guard/SKILL.md`](../creation-guard/SKILL.md)):
+
+1. Identify the proposal (name, type, purpose, key functions, keywords)
+2. Search existing skills and agents for overlap (skill-index scan + keyword grep)
+3. Analyse overlap and generate a recommendation:
+
+| Recommendation | Criteria | Action |
+|----------------|----------|--------|
+| **PROCEED** | <20% overlap, genuinely new | Continue to Phase 3 |
+| **EXTEND** | 50%+ overlap with one existing | Modify existing skill instead — stop here |
+| **COMPOSE** | Multiple artifacts cover 80%+ | Create wrapper or document workflow — stop here |
+| **ITERATE** | 20-50% overlap, needs refinement | Ask the user to clarify differentiation, then re-evaluate |
+| **BLOCK** | Would create duplication | Do not create — stop here |
+
+4. Present the creation-guard analysis to the user and get explicit approval before proceeding
+5. **Read [`skills/shared/skill-design-patterns.md`](../shared/skill-design-patterns.md)** — choose the structural pattern that fits:
+   - **Workflow-based** — multi-step with phases and review gates
+   - **Task-based** — focused input/output with processing rules
+   - **Agent-delegation** — multiple subagents, each handling one concern
+   - **Reference-based** — augmenting with domain knowledge via `references/`
+
+## Phase 3: Design the Skill
+
+Before writing, make three decisions:
+
+**1. Choose the structural pattern** (from Phase 2). State it explicitly:
+> "This is a [workflow/task/agent-delegation/reference]-based skill."
+
+**2. Identify resources needed:**
+- Does the skill need `scripts/` for deterministic operations?
+- Does it need `references/` for detailed specs, rubrics, or large examples?
+- Does it need to delegate to subagents?
+
+**3. Draft the architecture** — for non-trivial skills, sketch the flow:
+```
+Input → [Step A] → REVIEW GATE → [Step B] → Output
+```
+
+## Phase 4: Build the Skill
+
+Write `skills/{name}/SKILL.md`:
+
+### Frontmatter
+
+```yaml
+---
+name: {kebab-case-name}
+description: "{What it does. Concrete task types. Use when...}"
+allowed_tools:
+  - {minimum set of tools needed}
+---
+```
+
+### Body Structure
+
+The body varies by pattern, but always includes these elements:
+
+```markdown
+# {Skill Name}: {Short Description}
+
+## When to Use
+[Activation conditions — natural language triggers and /command]
+
+## {Main Workflow / Processing Rules / Delegation Protocol}
+[The core of the skill — structured per the chosen pattern]
+
+## {Anti-Patterns / Never Do These}
+[What NOT to do — agents default to generic without constraints]
+
+## Output Format
+[What the output looks like]
+
+## Verification
+[How to confirm it worked]
+```
+
+**Optional sections** (add when relevant):
+- `## Defaults` — assumptions table to reduce friction
+- `## Examples` — concrete before/after or good/bad snippets
+- `## Notes` — edge cases, limitations
+
+### Solution Pattern (for debugging/workaround skills)
+
+When the skill captures a fix, workaround, or debugging procedure, use this body structure:
+
+```markdown
+# {Skill Name}: {Short Description}
+
+## Problem
+[Specific error message or symptom. Quote the exact text users would see.]
+
+## Context / Triggers
+[When this occurs — tool versions, file types, OS, configurations]
+
+## Solution
+[Step-by-step fix. Imperative form.]
+
+## Verification
+[How to confirm the fix worked]
+
+## Example
+[Concrete before/after or input/output]
+
+## Notes
+[Edge cases, alternative approaches, when this does NOT apply]
+```
+
+### Description Optimization
+
+The `description:` field in frontmatter is what triggers skill discovery. Write it to match how a user would describe their problem:
+
+- **Include specific error messages or symptoms** — "Fix `Package biblatex Error: File 'references.bib' not found`"
+- **Include context markers** — file types, tools, situations where this applies
+- **Include negative cases** — "Not for general proofreading (use /proofread instead)"
+- **Use natural trigger phrases** — the exact words a user would type
+
+### Extraction Checklist
+
+During skill creation, mentally verify each point before finalising:
+
+1. **Trigger coverage** — would a user find this skill from 3 different phrasings of the same problem?
+2. **Self-contained** — can the skill be followed without reading other files (except `references/`)?
+3. **Anti-patterns present** — at least 2 "don't do this" entries to prevent common mistakes?
+4. **Verification step** — does the skill tell you how to confirm it worked?
+5. **Scope bounded** — is it clear what this skill does NOT do?
+
+### Writing Rules
+
+- **Imperative form.** "Parse the input" not "You should parse the input."
+- **Be specific about what NOT to do.** Anti-pattern lists are highly effective.
+- **Include concrete examples.** Show expected input/output pairs.
+- **Keep SKILL.md under 300 lines.** Move detail to `references/`.
+- **Every instruction must be actionable.** No throat-clearing.
+- **Use tables for structured data.** Faster to parse than prose.
+
+### Naming Conventions
+
+- **Directory and name:** `kebab-case`, descriptive, 2-4 words
+- **Avoid generic names:** `fix-bug` is bad; `fix-overleaf-sync-conflict` is good
+- **Match the trigger:** If the natural trigger is "compile my slides", the name should relate to slide compilation
+
+### Allowed Tools
+
+Follow principle of least privilege:
+
+| Skill type | Tools |
+|-----------|-------|
+| Report-only | `Read`, `Glob`, `Grep` |
+| File-creating | + `Write`, `Edit` |
+| Shell-needing | + specific `Bash(command*)` patterns |
+| Interactive | + `AskUserQuestion` |
+| Delegating | + `Task` |
+
+## Phase 5: Validate
+
+Run the validation script on the new skill:
+
+```bash
+uv run python skills/learn/scripts/validate_skill.py skills/{name}
+```
+
+Fix all errors. Address warnings to improve quality. Use `--strict` to promote warnings to errors.
+
+The validator checks: frontmatter validity, name format and directory match, description quality, body length, broken links, referenced directories, and placeholder text.
+
+## Phase 6: Deploy and Confirm
+
+1. Copy the skill to the deployed location (rsync won't run until next session start):
+   ```bash
+   cp -r skills/{name} ~/.claude/skills/{name}
+   ```
+2. Check that `~/.claude/skills/{name}/SKILL.md` exists
+3. Tell the user: "Created `/{name}` — [one-line summary]. It's available immediately in all projects."
+4. If the skill is substantial, suggest updating `docs/skills.md` with the new entry
+
+## What This Skill Does NOT Do
+
+- **Does not replace `[LEARN]` tags** — one-liner corrections still go in MEMORY.md via the `learn-tags` rule
+- **Does not create agents** — agents need separate context and persistent memory
+- **Does not modify existing skills** — if an existing skill needs updating, do that directly