flonat-research 0.1.0

package/skills/validate-bib/references/deep-verify.md

@@ -0,0 +1,71 @@
+# Deep Verification Mode
+
+> Triggered by: `--deep-verify` flag, or when the .bib has 40+ entries, or when the user says "deep verify" / "verify all references".
+
+This mode spawns parallel sub-agents that each verify a batch of entries and write structured results to disk -- bypassing context window limits entirely.
+
+## Architecture
+
+```
+You (orchestrator)
++-- Read .bib file, extract all entries
++-- Create verification_results/ directory in project root
++-- Batch entries into groups of 5
++-- Spawn parallel agents (max 5 concurrent), each:
+|   +-- For each entry in batch:
+|   |   +-- Verify DOI resolves (via biblio MCP scholarly_verify_dois)
+|   |   +-- Check title matches DOI metadata
+|   |   +-- Check author consistency
+|   |   +-- Check year correctness
+|   |   +-- Check for published version if preprint
+|   +-- Write results to verification_results/batch_N.json
++-- Wait for all agents to complete
++-- Read all batch JSON files
++-- Merge into verification_results/full_report.json
++-- Generate markdown summary highlighting entries needing attention
+```
+
+## Batch JSON Format
+
+Each agent writes a file `verification_results/batch_N.json`:
+
+```json
+[
+  {
+    "cite_key": "Author2020-ab",
+    "doi_valid": true,
+    "title_match": true,
+    "author_match": true,
+    "year_correct": true,
+    "preprint_status": "published_version_exists",
+    "published_doi": "10.1234/...",
+    "issues": [],
+    "suggested_fixes": {}
+  }
+]
+```
+
+## Agent Prompt Template
+
+Each sub-agent receives:
+- The batch of .bib entries (raw text)
+- The batch number
+- The output path: `verification_results/batch_N.json`
+- Instructions to use biblio MCP tools for verification
+- Instruction to write results to disk only -- never return large payloads
+
+## Assembly & Report
+
+After all agents complete:
+1. Read all `verification_results/batch_*.json` files
+2. Merge into `verification_results/full_report.json`
+3. Generate `verification_results/summary.md` with:
+   - Total entries verified
+   - Entries with issues (grouped by issue type)
+   - Suggested fixes
+   - Entries needing manual attention
+4. Print the summary to the user
+
+## Cleanup
+
+After the report is delivered, offer to delete `verification_results/` or keep it for reference.

package/skills/validate-bib/references/openalex-verification.md

@@ -0,0 +1,45 @@
+# Metadata Verification
+
+> Reference file for `/validate-bib`. Use when missing entries or suspicious metadata are found.
+
+## Preferred: Biblio MCP Tools
+
+**Always prefer MCP tools over the Python client** — they're faster, require no boilerplate, and query multiple sources.
+
+| Tool | Use for |
+|------|---------|
+| `scholarly_verify_dois` | Batch-verify DOIs across OpenAlex + Scopus + WoS (up to 50 per call) |
+| `scholarly_search` | Find a paper by title across all sources — useful when a cited key is missing |
+| `openalex_lookup_doi` | Look up full metadata for a single DOI |
+| `scholarly_similar_works` | Find related papers when a title search doesn't match exactly |
+
+## Fallback: Python Client
+
+**Python:** Always use `uv run python`. Never bare `python`, `python3`, `pip`, or `pip3`.
+
+Use the Python client only for workflows not exposed via MCP (citation networks, institution analysis):
+
+```bash
+uv run python -c "
+import sys
+sys.path.insert(0, '.scripts/openalex')
+from openalex_client import OpenAlexClient
+
+client = OpenAlexClient(email='user@example.edu')
+
+# Look up a specific DOI
+result = client.get_entity('works', 'doi:10.1016/j.ejor.2024.01.001')
+
+# Search by title to find the correct entry
+results = client.search_works(search='decision making under uncertainty', per_page=5)
+"
+```
+
+## When to use:
+
+- A cited key is missing and you want to confirm whether the paper exists
+- Year or author formatting looks suspicious and you want to cross-check
+- The user asks to enrich `.bib` entries with verified metadata
+- Batch DOI verification (use `scholarly_verify_dois` first)
+
+Do NOT use this by default — only when the report flags issues worth verifying.

package/skills/validate-bib/references/preprint-check.md

@@ -0,0 +1,31 @@
+# Preprint Staleness Check
+
+> Reference file for `/validate-bib`. Protocol for checking whether preprints have been published.
+
+## Detection — identify preprint entries by any of:
+
+| Signal | Examples |
+|--------|----------|
+| URL/DOI contains preprint host | `arxiv.org`, `ssrn.com`, `nber.org`, `repec.org`, `econpapers`, `ideas.repec` |
+| Journal/howpublished field | "arXiv preprint", "SSRN", "NBER Working Paper", "Working Paper", "mimeo" |
+| Entry type | `@techreport`, `@unpublished`, `@misc` with working-paper-like metadata |
+| Note field | Contains "preprint", "working paper", "wp", "discussion paper" |
+
+## Lookup — find the published version:
+
+1. **Biblio MCP `scholarly_search` first** (preferred — queries OpenAlex + Scopus + WoS with dedup):
+   Call `scholarly_search` with the paper title as query. Check if any result has a journal/venue and is not itself a preprint. Cross-source search increases the chance of finding the published version.
+2. **DOI resolution fallback**: If the preprint has a DOI, check if it redirects to or links to a published version.
+3. **Web search last resort**: Search for the paper title + "published" or "journal" if MCP returns nothing.
+
+## Classification:
+
+| Finding | Severity | Message |
+|---------|----------|---------|
+| Published version exists | **Warning** | "Preprint `key` appears published in *Journal Name* (Year). Consider updating the .bib entry." |
+| Published version exists with different title/authors | **Warning** | "Preprint `key` may have been published as '*new title*' in *Journal*. Verify and update." |
+| No published version found | **Info** | "Preprint `key` — no published version found (checked YYYY-MM-DD)." |
+
+## Report section:
+
+Add a `## Warning: Stale Preprints` section to the report listing all preprints where a published version was found, with the suggested replacement metadata (journal, year, DOI).

package/skills/validate-bib/references/report-template.md

@@ -0,0 +1,62 @@
+# Bibliography Validation Report Template
+
+> Reference file for `/validate-bib`. Use this format for all validation reports.
+
+```markdown
+# Bibliography Validation Report
+
+**Project:** [path]
+**Date:** YYYY-MM-DD
+**Files scanned:** [list of .tex files]
+**Bibliography type:** External .bib / Embedded / Both
+**Bibliography:** [filename] ([N] entries) | Embedded ([N] \bibitem entries) | Both ([N] .bib + [N] \bibitem)
+**Citations found:** [N] unique keys across [N] citation commands
+
+## Summary
+
+| Check | Count |
+|-------|-------|
+| Missing entries (Critical) | 0 |
+| Possible typos (Warning) | 0 |
+| Unused entries (Warning) | 0 |
+| Missing required fields (Warning) | 0 |
+| DOI mismatches (Warning) | 0 |
+| Stale preprints (Warning) | 0 |
+| Year issues (Info) | 0 |
+
+## Critical: Missing Entries
+
+| Cited Key | File | Line | Suggested Match |
+|-----------|------|------|-----------------|
+| `smith2020` | main.tex | 42 | `smith2021` (edit dist: 1) |
+
+## Warning: Possible Typos
+
+[Keys with close fuzzy matches]
+
+## Warning: Unused Entries
+
+[Keys in bibliography not cited anywhere — listed for review]
+
+## Warning: Missing Required Fields
+
+*External .bib only — skipped for embedded bibliographies.*
+
+| Key | Type | Missing Fields |
+|-----|------|---------------|
+| `jones2019` | article | journal |
+
+## Warning: Stale Preprints
+
+| Key | Current Source | Published In | Year | DOI |
+|-----|---------------|--------------|------|-----|
+| `smith2020arxiv` | arXiv:2020.12345 | *J. of ML Research* | 2022 | 10.xxxx/yyyy |
+
+## Info: Year Issues
+
+[Entries with suspicious years]
+
+## Limitations
+
+*If embedded:* Embedded bibliographies (`\bibitem`) lack structured metadata (author, year, journal as separate fields). Only cross-reference checks were performed. Quality checks (required fields, year reasonableness, author formatting) require an external `.bib` file.
+```