flonat-research 0.1.0

package/skills/shared/project-documentation-format.md

@@ -0,0 +1,281 @@
+# Project Documentation — Format Conventions
+
+> Conventions for ASCII diagrams, env vars, tone, LaTeX, Beamer, public variants, and validation.
+> Split from [`project-documentation.md`](project-documentation.md) for leanness.
+
+---
+
+## ASCII Diagrams
+
+### Direction Conventions
+
+| Flow type | Direction | Example |
+|-----------|-----------|---------|
+| Data/request flow | Left-to-right | `User ──→ API ──→ DB` |
+| Stage progression | Top-to-bottom | Stage 1 → Stage 2 → Stage 3 |
+| Architecture layers | Top-to-bottom | Frontend → Backend → Database |
+| Workflow chains | Left-to-right with branches | `A ──→ B ──→ C` with `└──→ D` |
+
+### Symbol Legend
+
+```
+──→     directional flow
+│       vertical connection
+├──     branch (continuing)
+└──     branch (terminal)
+┌─┐     box corners (for containers)
+▼ ▲     vertical arrows
+```
+
+### Labelling
+
+- Label every box with its service/component name
+- Label arrows only when the relationship isn't obvious (e.g., "OAuth", "REST API")
+- Add parenthetical notes for data stores: `SQLite (results + cache)`
+- Keep diagrams under 15 lines — split into multiple diagrams if needed
+
+---
+
+## Environment Variable Documentation
+
+Use this table format everywhere env vars are documented:
+
+```markdown
+| Variable | Purpose | Required | Default |
+|----------|---------|----------|---------|
+| `OPENROUTER_API_KEY` | LLM access via OpenRouter | Yes | — |
+| `OPENALEX_API_KEY` | OpenAlex bibliometric data | Yes | — |
+| `SCOPUS_API_KEY` | Scopus search (optional) | No | — |
+```
+
+**Rules:**
+- Required column: "Yes" or "No" — never blank
+- Default column: the actual default value, or "—" if none
+- Group by service (API keys together, app config together)
+- In READMEs, show env vars inside bash code blocks with comments. In reference docs, use the table.
+- `.env.example` must include every variable with a comment
+
+---
+
+## Tone by Audience
+
+| Audience | Tone | Patterns |
+|----------|------|----------|
+| End users (user manual) | Approachable, instructional | "You can...", "Enter your...", "Results include..." |
+| Developers (README) | Crisp, feature-focused | Active verbs: "Get", "Fetch", "Run", "Configure" |
+| Maintainers (architecture) | Technical, precise | Third person: "The orchestrator wires...", "Requests flow through..." |
+| Adopters (public repo) | Welcoming, honest | "Built for...", explicit audience statement |
+
+---
+
+## LaTeX Documentation
+
+When a document exists in both markdown and LaTeX (e.g., user manual in `.md` and `.tex`), the markdown is the source of truth for content. The LaTeX version adds typographic polish.
+
+### Standard Preamble (Article Style)
+
+```latex
+\documentclass[11pt,a4paper]{article}
+
+\usepackage{geometry}       % Margins (2.5cm all sides)
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage{lmodern}        % Modern serif font (not Computer Modern)
+\usepackage{microtype}      % Typographic refinement
+\usepackage{parskip}        % Paragraph spacing, no indents
+\usepackage{hyperref}       % Clickable links
+\usepackage{xcolor}         % Custom colours
+\usepackage{booktabs}       % Professional tables (\toprule, \midrule, \bottomrule)
+\usepackage{longtable}      % Multi-page tables
+\usepackage{enumitem}       % List customisation
+\usepackage{listings}       % Code blocks
+\usepackage[skins,breakable]{tcolorbox}  % Callout boxes
+\usepackage{tikz}           % Diagrams
+```
+
+### Custom Commands
+
+Define these reusable commands in the preamble for consistency:
+
+```latex
+\newcommand{\code}[1]{\texttt{\small #1}}           % Inline code
+\newcommand{\filepath}[1]{\texttt{\small #1}}        % File paths
+\newcommand{\skill}[1]{\texttt{/#1}}                 % Skill references
+\newcommand{\hook}[1]{\texttt{#1}}                   % Hook references
+\newcommand{\keyterm}[1]{\textbf{#1}}                % Key terminology
+```
+
+### Colour Palette for Callout Boxes
+
+```latex
+\definecolor{accentgreen}{HTML}{059669}   % Tip boxes
+\definecolor{accentamber}{HTML}{D97706}   % Warning boxes
+\definecolor{accentred}{HTML}{DC2626}     % Error/critical boxes
+\definecolor{codebg}{HTML}{F3F4F6}        % Code background
+\definecolor{codeframe}{HTML}{D1D5DB}     % Code border
+
+\newtcolorbox{tipbox}[1][]{
+    colback=accentgreen!5, colframe=accentgreen!60,
+    fonttitle=\bfseries, title={#1}, sharp corners, boxrule=0.5pt}
+\newtcolorbox{warnbox}[1][]{
+    colback=accentamber!5, colframe=accentamber!60,
+    fonttitle=\bfseries, title={#1}, sharp corners, boxrule=0.5pt}
+```
+
+### Table Formatting
+
+- Use `booktabs` rules: `\toprule`, `\midrule`, `\bottomrule` — never vertical lines
+- Column spec: `@{}lp{7cm}@{}` (remove outer padding, left column, paragraph column)
+- Multi-page tables: `\begin{longtable}` with `\endhead` for repeating headers
+- Always `\centering` within table environments
+
+### md/tex Parity
+
+When both formats exist, structural parity is required: every `##` heading in the markdown should have a corresponding `\section{}` in LaTeX. Content can differ slightly (LaTeX adds figures, better formatting), but the section structure must match. Validate with `validate_docs.py` check 2.
+
+---
+
+## Beamer Presentation Docs
+
+Projects may include Beamer decks in `docs/` (e.g., `docs/scout-overview/`, `docs/setup-overview/`). These are outward-facing documentation, not just slides.
+
+### Standard Setup
+
+```latex
+\documentclass[aspectratio=169,11pt]{beamer}
+\setbeamertemplate{navigation symbols}{}     % No nav clutter
+\setbeamertemplate{footline}[frame number]   % Frame numbers only
+```
+
+- **Aspect ratio:** Always 16:9 (`aspectratio=169`)
+- **Navigation symbols:** Disabled
+- **Footline:** Frame number only (or custom three-part: author | title | X/Y)
+
+### Colour Palette
+
+Define a cohesive palette of 5-8 colours in the preamble. Established palette:
+
+| Colour | Hex | Use |
+|--------|-----|-----|
+| `Midnight` | `1A1A2E` | Dark backgrounds, body text |
+| `DeepBlue` | `16213E` | Frame title backgrounds |
+| `RoyalBlue` | `0F3460` | Structure, bullet markers |
+| `Coral` | `E94560` | Alerts, emphasis |
+| `CloudWhite` | `FAFBFC` | Main background |
+| `SoftGray` | `BDC3C7` | Subtitles, subdued text |
+| `LightBlue` | `D6EAF8` | TikZ box fills |
+| `SlateGray` | `5D6D7E` | Arrows, secondary elements |
+
+### Frame Title Conventions
+
+- Use **substantive claims**, not labels: "62 skills cover the full research lifecycle" not "Skills Overview"
+- Optional subtitle for framing questions: "Every new AI session starts from zero"
+- Keep titles to one line
+
+### TikZ Diagram Styling
+
+```latex
+\begin{tikzpicture}[
+    node distance=0.6cm and 0.8cm,
+    box/.style={draw=SlateGray, rounded corners=3pt,
+                minimum width=2.0cm, minimum height=0.75cm,
+                align=center, fill=#1, text=Midnight},
+    box/.default={LightBlue},
+    arr/.style={-{Stealth[length=2mm]}, thick, color=SlateGray},
+]
+```
+
+- Rounded corners (3pt), minimum dimensions, centred text
+- Colour-code by component type (e.g., `Coral!20` for interfaces, `CloudWhite` for core, `SoftGray!30` for external)
+- Stealth arrowheads, thick strokes
+
+### Code Blocks in Beamer
+
+Use small monospace fonts — slides need compact code:
+
+```latex
+\begin{lstlisting}[language={}, basicstyle=\ttfamily\fontsize{6.5}{8}\selectfont]
+```
+
+### Bullet Styles
+
+- Level 1: `\tiny$\blacksquare$` in primary colour (filled square)
+- Level 2: `\scriptsize$\blacktriangleright$` in secondary colour (right triangle)
+- Enumerate: `\insertenumlabel.` in primary colour
+
+---
+
+## Public/Anonymized Variants
+
+When a document has both private and public versions (e.g., `setup-overview.tex` and `setup-overview-public.tex`), follow these conventions.
+
+### What to Anonymize
+
+| Private | Public replacement |
+|---------|-------------------|
+| Author name | Generic descriptor ("PhD researcher") or GitHub handle |
+| Institution names | Remove entirely |
+| Exact component counts | Remove or genericize ("30+", "Skills" without number) |
+| Specific project names | "Multiple active research projects" |
+| vault references | "Task manager" (generic) |
+| Date in `\date{}` | GitHub URL or "Open-source" descriptor |
+
+### Sync Markers
+
+For auto-generated or synced content in public markdown files, use HTML comment markers:
+
+```markdown
+<!-- MARKER-NAME:START -->
+<!-- auto-generated by script-name.py — do not edit manually -->
+[content here]
+<!-- MARKER-NAME:END -->
+```
+
+- Marker names: UPPERCASE-HYPHENATED (`COMPONENT-TABLE`, `SKILLS-SUMMARY`, `FILE-TREE`)
+- Attribution line after START: `auto-generated by ...` or `synced from private ...`
+- Warning: `do not edit manually`
+
+### Private LaTeX Headers
+
+```latex
+% ============================================================
+% Document Title — Description
+% Author · Month Year
+% ============================================================
+```
+
+### Public LaTeX Headers
+
+```latex
+% ============================================================
+% Document Title — Public Version (Format)
+% Generated during sync — DO NOT EDIT MANUALLY
+% Edit source-file.tex and re-run sync-script.sh
+% ============================================================
+```
+
+---
+
+## Automated Validation
+
+Projects with documentation in multiple formats or locations should include a validation script that catches drift automatically.
+
+### The `validate_docs.py` Pattern
+
+- **Stdlib-only** — no venv needed, runs anywhere Python is installed
+- **Location:** `scripts/validate_docs.py` in the project root
+- **Severity levels:** FAIL (blocks CI) and WARN (informational, `--strict` promotes to FAIL)
+- **Flags:** `--strict` (treat warnings as failures), `--check N` (run only check N)
+- **Paths:** All resolved relative to script location — no hardcoded absolute paths
+- **CI integration:** Run before tests in the CI pipeline
+
+### Common Checks
+
+| Check | Severity | What it catches |
+|-------|----------|----------------|
+| Help slug integrity | FAIL | WORKFLOW_TIPS slugs that don't match user-manual headings |
+| md/tex section parity | WARN | Structural divergence between markdown and LaTeX versions |
+| File path references | FAIL | Backtick-quoted paths in docs that don't exist on disk |
+| Class/method references | FAIL | Code references in architecture docs that don't match source |
+| Count accuracy | WARN | Claimed counts vs actual (data sources, templates, etc.) |
+| Env var completeness | WARN | Settings fields missing from documentation |

package/skills/shared/project-documentation.md

@@ -0,0 +1,100 @@
+# Project Documentation Conventions
+
+> Shared conventions for outward-facing documentation: project READMEs, user manuals, architecture docs, deploy guides, and in-app help. Ensures consistency across Scout, council packages, and future projects.
+>
+> Companion to `system-documentation.md` (which covers internal Task Management docs like CLAUDE.md, SKILL.md, and component catalogues).
+
+---
+
+## Governed Documents
+
+Every document governed by these conventions carries a tag on its first line:
+
+- **Markdown:** `<!-- Governed by: skills/shared/project-documentation.md -->`
+- **LaTeX:** `% Governed by: skills/shared/project-documentation.md`
+
+### Registry
+
+| Project | File | Type |
+|---------|------|------|
+| Scout | `README.md` | README |
+| Scout | `docs/user-manual.md` | User manual |
+| Scout | `docs/architecture.md` | Architecture |
+| Scout | `deploy/README.md` | Deploy guide |
+| Scout | `docs/user-manual.tex` | LaTeX manual |
+| Scout | `docs/scout-overview/scout-overview.tex` | Beamer deck |
+| Task Management | `docs/user-manual/user-manual.tex` | LaTeX manual |
+| Task Management | `docs/setup-overview/setup-overview.tex` | Beamer deck |
+| Task Management | `docs/setup-overview/setup-overview-public.tex` | Beamer deck (public) |
+| Task Management | `public/public-repo/README.md` | README (public) |
+| Task Management | `public/public-repo/docs/getting-started.md` | Getting started |
+| Task Management | `public/public-repo/docs/council-mode.md` | Feature guide |
+| Task Management | `public/public-repo/docs/biblio-setup.md` | Setup guide |
+| Task Management | `public/public-repo/docs/setup.md (legacy)` | Setup guide |
+
+### Tagging Protocol
+
+When **creating** new outward-facing documentation (README, user manual, architecture doc, deploy guide, Beamer deck, or LaTeX manual):
+
+1. Add the appropriate tag as the very first line of the file
+2. Add the file to the registry table above
+
+When **auditing** a project's documentation (via `/sync-repo scout`, `/update-project-doc`, or manually):
+
+1. Grep for `Governed by: skills/shared/project-documentation.md` across all `.md` and `.tex` files
+2. Flag any outward-facing docs that lack the tag — these are candidates for tagging
+3. Do not tag internal docs (CLAUDE.md, SKILL.md, `.context/` files, `log/` files, `docs/skills.md`, etc.) — those are governed by `system-documentation.md`
+
+---
+
+## The Documentation Suite
+
+Every software project should have a README. Larger projects add docs as they grow. This table defines what each file covers and when to create it.
+
+| Document | Create when | Audience | Covers |
+|----------|------------|----------|--------|
+| `README.md` | Always | Everyone | What it does, quick start, project structure |
+| `docs/user-manual.md` | Web UI or CLI with 3+ workflows | End users | Every feature, step-by-step, with examples |
+| `docs/architecture.md` | 5+ source files or non-obvious design | Maintainers | Service layers, data flow, design patterns |
+| `deploy/README.md` | Remote deployment exists | DevOps / self | Infrastructure, secrets, CI/CD |
+| In-app help (`/help` + tips) | Web UI exists | End users | Same content as user manual, rendered in-app |
+
+**Principle:** Each document serves a distinct audience. If two docs say the same thing, one should be a pointer to the other.
+
+---
+
+## Content Conventions
+
+Detailed conventions for each document type: [`project-documentation-content.md`](project-documentation-content.md)
+
+Covers: README required sections, user manual structure, per-workflow pattern, architecture doc structure, deploy guide structure, in-app help system, library/package READMEs, CLI example conventions.
+
+## Format Conventions
+
+Detailed conventions for formatting and presentation: [`project-documentation-format.md`](project-documentation-format.md)
+
+Covers: ASCII diagrams, env var tables, tone by audience, LaTeX preamble and commands, Beamer decks (colour palette, TikZ, bullet styles), public/anonymized variants (sync markers, anonymization rules), automated validation (`validate_docs.py` pattern).
+
+---
+
+## Checklist for New Project Documentation
+
+Before shipping any project documentation:
+
+1. **README exists** with all required sections
+2. **Live URL** linked prominently if hosted
+3. **ASCII diagram** shows end-to-end flow
+4. **Tech stack table** lists every major dependency
+5. **Setup is copy-pasteable** — tested from a clean state
+6. **CLI examples use real arguments** — no `$` prefix, no placeholders
+7. **Env vars documented** in consistent table format
+8. **File tree annotated** — comments explain non-obvious entries
+9. **Pointer table** links to detailed docs (user manual, architecture, deploy)
+10. **User manual** follows per-workflow pattern (URL → purpose → how to use → what you get)
+11. **Limitations section** with honest caveats (numbered, bold constraint + explanation)
+12. **In-app help** loads user manual at runtime (no content duplication)
+13. **LaTeX versions** use standard preamble, custom commands, booktabs tables
+14. **md/tex parity** — section structure matches between formats
+15. **Beamer decks** use 16:9, consistent colour palette, substantive frame titles
+16. **Public variants** anonymized (no names, no exact counts, sync markers for auto-generated content)
+17. **Validation script** checks for drift between docs and code

package/skills/shared/publication-output.md

@@ -0,0 +1,138 @@
+# Publication Output Conventions
+
+> Table format, figure format, and output routing standards for publication-ready outputs.
+> Referenced by `/data-analysis`, `/replication-package`.
+
+## Table Format: Booktabs Three-Line
+
+All LaTeX tables use the `booktabs` three-line style unless a venue explicitly requires something else.
+
+### Standard Structure
+
+```latex
+\begin{table}[htbp]
+\centering
+\caption{Descriptive title stating the finding}
+\label{tab:descriptive-label}
+\begin{tabular}{lcccc}
+\toprule
+                & (1)        & (2)        & (3)        & (4)        \\
+                & OLS        & FE         & IV         & IV-FE      \\
+\midrule
+Treatment       & 0.123***   & 0.098**    & 0.145**    & 0.112*     \\
+                & (0.034)    & (0.041)    & (0.058)    & (0.063)    \\
+Control A       & 0.456      & 0.423      & 0.478      & 0.445      \\
+                & (0.089)    & (0.092)    & (0.095)    & (0.098)    \\
+\midrule
+Observations    & 1,247      & 1,247      & 1,189      & 1,189      \\
+R$^2$           & 0.234      & 0.312      & 0.198      & 0.289      \\
+Controls        & Yes        & Yes        & Yes        & Yes        \\
+Fixed Effects   & No         & Yes        & No         & Yes        \\
+\bottomrule
+\end{tabular}
+\begin{tablenotes}[flushleft]
+\footnotesize
+\item \textit{Notes:} Standard errors in parentheses, clustered at the firm level.
+* $p<0.10$, ** $p<0.05$, *** $p<0.01$.
+\end{tablenotes}
+\end{table}
+```
+
+### Rules
+
+1. **Three lines only:** `\toprule`, `\midrule`, `\bottomrule`. No `\hline`, no vertical lines.
+2. **Standard errors in parentheses** below coefficients. Never brackets.
+3. **Star convention:** `* p<0.10, ** p<0.05, *** p<0.01` (state in table notes).
+4. **Column headers:** Model number in row 1, specification name in row 2.
+5. **Panel labels:** Use `\multicolumn` with `Panel A:`, `Panel B:` for multi-panel tables.
+6. **Footnotes:** Use `tablenotes` environment or `\smallskip\footnotesize` block below the table.
+7. **Alignment:** `l` for row labels, `c` for numeric columns. Use `S` (siunitx) for decimal alignment if available.
+8. **Number formatting:** Thousands separator (1,247 not 1247). 3 decimal places for coefficients, 2 for R².
+
+## Figure Format
+
+### Export Standards
+
+| Format | Use case |
+|--------|----------|
+| PDF | Default for all figures (vector, lossless) |
+| PNG | Raster plots, heatmaps (300+ DPI) |
+| SVG | Web/HTML output only |
+
+### Dimensions
+
+- **Single column:** 6 × 4 inches (width × height)
+- **Full width:** 10 × 6 inches
+- **Square (scatter/correlation):** 6 × 6 inches
+- **Panel figures:** Scale width proportionally; maintain consistent height across panels
+
+### Style
+
+- Greyscale-safe colour palettes (figures should be readable in B&W print)
+- Minimal gridlines (light grey, major ticks only)
+- Axis labels with units: "Revenue (USD millions)"
+- Legend inside plot area when space allows; outside otherwise
+- Title in the LaTeX `\caption{}`, not baked into the figure image
+
+### LaTeX Inclusion
+
+```latex
+\begin{figure}[htbp]
+\centering
+\includegraphics[width=\textwidth]{figures/fig1.pdf}
+\caption{Descriptive title stating what the figure shows}
+\label{fig:descriptive-label}
+\end{figure}
+```
+
+## Output Routing
+
+### Directory Structure
+
+```
+project/
+├── code/              ← scripts that generate output
+├── data/
+│   ├── raw/           ← READ-ONLY source data
+│   ├── processed/     ← cleaned/transformed data
+│   └── synthetic/     ← generated test data
+├── output/            ← intermediate results (not for paper)
+│   ├── tables/        ← .csv, .rds, .pkl intermediate tables
+│   └── figures/       ← exploratory/draft figures
+└── paper/             ← Overleaf-synced, LaTeX only
+    ├── tables/        ← .tex table files (generated by code)
+    └── figures/       ← .pdf/.png figure files (generated by code)
+```
+
+### Routing Rules
+
+1. **Scripts** live in `code/` or `src/`, never in `paper/`.
+2. **Publication tables** (`.tex`) go directly to `paper/tables/`. Generated by code, referenced via `\input{tables/table1.tex}`.
+3. **Publication figures** (`.pdf`/`.png`) go directly to `paper/figures/`. Generated by code, referenced via `\includegraphics{figures/fig1.pdf}`.
+4. **Intermediate outputs** (exploratory plots, draft tables, `.csv` summaries) go to `output/`. These are not committed to the paper directory.
+5. **Never hard-code results** in `.tex` files. All numbers come from `\input{}` or generated files.
+
+### Naming Conventions
+
+| File type | Pattern | Example |
+|-----------|---------|---------|
+| Main results table | `table{N}.tex` | `table1.tex` |
+| Named table | `tab-{name}.tex` | `tab-descriptives.tex` |
+| Appendix table | `tableA{N}.tex` | `tableA1.tex` |
+| Main figure | `fig{N}.pdf` | `fig1.pdf` |
+| Named figure | `fig-{name}.pdf` | `fig-event-study.pdf` |
+| Appendix figure | `figA{N}.pdf` | `figA1.pdf` |
+
+### Inline Statistics
+
+For inline numbers (sample sizes, test statistics, p-values), export a `.tex` file with `\newcommand` definitions:
+
+```latex
+% Generated by code/analysis.R — do not edit manually
+\newcommand{\Nobs}{1,247}
+\newcommand{\maineffect}{0.123}
+\newcommand{\mainse}{0.034}
+\newcommand{\mainpval}{0.001}
+```
+
+Include in the paper preamble with `\input{tables/inline-stats.tex}` and reference as `$N = \Nobs$`.

package/skills/shared/quality-scoring.md

@@ -0,0 +1,70 @@
+# Quality Scoring Framework
+
+> Shared framework for numeric quality scoring across review skills. Each skill has its own rubric in `references/quality-rubric.md` — this file defines the common structure.
+
+## How It Works
+
+1. **Start at 100.** Every artefact begins with a perfect score.
+2. **Deduct per issue.** Each issue found subtracts points based on its severity tier (see rubric).
+3. **Floor at 0.** Score cannot go negative.
+4. **Apply verdict.** Map the final score to a verdict using the thresholds below.
+
+## Severity Tiers
+
+| Tier | Deduction range | Definition |
+|------|----------------|------------|
+| **Blocker** | -100 | Artefact is broken — cannot compile, render, or run. Single blocker = automatic 0. |
+| **Critical** | -15 to -25 | Will be noticed by reviewers/users. May cause rejection or misinterpretation. |
+| **Major** | -5 to -14 | Noticeable quality issue. Degrades professionalism or correctness. |
+| **Minor** | -1 to -4 | Polish issue. Individually harmless, accumulates. |
+
+Each skill's rubric maps specific issues to a tier and exact deduction. When an issue doesn't fit an existing rubric entry, classify it by tier definition and use the midpoint of the range.
+
+## Verdicts and Thresholds
+
+| Score | Verdict | Meaning |
+|-------|---------|---------|
+| **95-100** | Ship | Ready for submission, sharing, or publication. |
+| **90-94** | Ship with notes | Minor issues noted in report — acceptable to proceed. |
+| **80-89** | Revise | Meaningful issues that should be fixed before sharing. |
+| **60-79** | Revise (major) | Significant problems. Do not share in current state. |
+| **0-59** | Blocked | Fundamental issues. Artefact needs substantial rework. |
+
+## Deduction Rules
+
+- **One deduction per unique issue.** If the same typo appears 5 times, deduct once for the pattern + note the count.
+- **Repeated minor issues escalate.** 5+ instances of the same minor issue → treat as one major deduction instead of 5 minor ones.
+- **Blockers are absolute.** Any single blocker sets the score to 0 regardless of other findings.
+- **N/A categories don't penalise.** If a rubric category doesn't apply (e.g., no TikZ diagrams), skip it — don't award bonus points.
+
+## Score Block Template
+
+Include this block at the top of every review report, after the summary table:
+
+```markdown
+## Quality Score
+
+| Metric | Value |
+|--------|-------|
+| **Score** | XX / 100 |
+| **Verdict** | Ship / Ship with notes / Revise / Revise (major) / Blocked |
+
+### Deductions
+
+| # | Issue | Tier | Deduction | Category |
+|---|-------|------|-----------|----------|
+| 1 | [description] | Critical | -15 | [rubric category] |
+| 2 | [description] | Minor | -2 | [rubric category] |
+| ... | | | | |
+| | **Total deductions** | | **-XX** | |
+```
+
+## Applying the Framework
+
+When a skill says "Apply quality scoring":
+
+1. Read the skill's `references/quality-rubric.md` for issue-to-deduction mappings.
+2. As you review, log each issue with its rubric entry and deduction.
+3. Sum deductions, compute final score (100 - total), apply verdict.
+4. Insert the Score Block into the report at the designated location.
+5. In the Recommendations section, prioritise fixes by deduction size (biggest impact first).

package/skills/shared/reference-resolution.md

@@ -0,0 +1,77 @@
+# Shared: Reference Resolution & Filing Sequence
+
+Canonical lookup and filing sequence for all bibliography skills (`/literature`, `/bib-validate`, `/bib-parse`, `/bib-coverage`). Reference this module instead of reimplementing lookup logic.
+
+## Resolution Order (Lookup)
+
+When resolving a reference (checking if it exists, finding metadata, verifying DOIs), search in this order:
+
+1. **Zotero** (active write target) — `mcp__refpile__search_library` by title/author. If found, reuse its `citationKey`.
+2. **Paperpile** (read-only cross-reference) — `mcp__paperpile__search_library` by title/author. If found, note for status reporting. Paperpile is read-only; items cannot be added via MCP.
+3. **Bibliography MCP** (scholarly sources) — `scholarly_search` across OpenAlex + Scopus + WoS for metadata enrichment.
+4. **Crossref API** (DOI fallback) — `curl -sL "https://api.crossref.org/works?query.bibliographic=[URL-encoded title+author]&rows=3"` for DOI resolution.
+5. **Web search** (last resort) — `WebSearch` for papers not found in any structured source.
+
+**Graceful degradation:** If any MCP is unavailable, skip it with a warning and continue with the remaining sources.
+
+## Status Categories
+
+Based on where a reference is found, assign one of these statuses:
+
+| Zotero | Paperpile | .bib | Status | Action |
+|--------|-----------|------|--------|--------|
+| Yes | Yes | Yes | `HEALTHY` | No action needed |
+| Yes | — | Yes | `HEALTHY` | No action needed |
+| No | Yes | Yes | `MIGRATE_TO_ZOTERO` | Auto-add to Zotero from Paperpile metadata |
+| No | No | Yes | `DRIFT` | In local .bib but not in any reference manager — auto-add to Zotero |
+| Yes | — | No | `EXPORT_GAP` | In Zotero but not in local .bib — export or cite |
+| No | Yes | No | `EXPORT_GAP` | In Paperpile but not in local .bib — export or cite |
+| No | No | No | `MISSING` | Not found anywhere — add via filing sequence below |
+
+## Filing Sequence (Adding Items)
+
+When a skill needs to add a reference to Zotero, follow this sequence:
+
+### 1. Add to Zotero
+
+Call `mcp__refpile__add_item` with full metadata (title, authors, year, journal/booktitle, DOI, itemType).
+
+### 2. File into topic collection
+
+Resolve the topic collection key from `zotero-collections.md` (in the project's research directory or the Task Management `.context/resources/` folder):
+
+- **Explicit argument:** If the user passed `--topic <slug>`, use that slug to look up the collection key.
+- **Project context:** Read the project's `CLAUDE.md` or topic frontmatter for the Atlas topic slug.
+- **Directory name:** If inside a research project directory, use the directory name as the topic slug.
+
+Call `mcp__refpile__add_to_collection(collection_key=<resolved_key>)` to file the item into the topic-specific collection.
+
+### 3. Also tag for review
+
+Call `mcp__refpile__add_to_collection` with the `_Needs Review` collection key. Items go into **both** the topic collection and `_Needs Review` — the topic collection for organisation, `_Needs Review` for the user to verify.
+
+### 4. Report Paperpile gaps
+
+List items that need manual import into Paperpile (read-only MCP — user must add via Paperpile app or browser extension).
+
+### 5. Fallback
+
+If the topic collection key cannot be resolved (no `--topic` argument, no project context, slug not found in `zotero-collections.md`), file into `_Needs Review` only and warn:
+
+> "Could not resolve topic collection — filed into `_Needs Review` only. Specify `--topic <slug>` or ensure the project has an Atlas topic."
+
+## Post-Run Maintenance
+
+After any skill run that adds items to Zotero:
+
+1. **Update `zotero-collections.md`** — increment item counts for affected collections.
+2. **Report migration candidates** — list items found in Paperpile but not in Zotero as `MIGRATE_TO_ZOTERO`. Offer to auto-add them.
+
+## Skills That Reference This Module
+
+| Skill | Uses Resolution | Uses Filing | Notes |
+|-------|----------------|-------------|-------|
+| `/literature` | Phase 1 (pre-search check) | Phase 6c (sync to managers) | Full workflow |
+| `/bib-validate` | Ref Manager Cross-Reference | Fix Mode (auto-add) | Reports + optional fixes |
+| `/bib-parse` | Phase 3.5 (library check) | Phase 6.5 (sync to Zotero) | PDF extraction workflow |
+| `/bib-coverage` | Collection comparison | — | Read-only comparison |