# CLAUDE.md — WP45 / JoF-250

> Mandate pasted verbatim by Simon-Pierre Boucher on 2026-11-03 (« ensuite peux tu faire ce projet comme wp45 de uqo research et build le system et qu'il soit accessible à toutes les sessions Claude Code »). Project-specific operating notes are at the end (section « Operating notes »).

## Mission
You are Claude Code, acting as research engineer, finance scholar, reproducibility auditor, and scientific-writing systems architect. Build **two finished, integrated deliverables**:

1. **WP45**, a rigorous English-language LaTeX research paper provisionally titled *JoF-250: Learning Scientific Writing Conventions from Pre-LLM Financial Research*.
2. **JoF-250 Writing Engine**, a genuinely usable, tested Claude Code extension for writing, editing, reviewing, and auditing scholarly manuscripts. It must work beyond WP45, including future UQO working papers.

**Corpus location:** `~/Desktop/Journal-of-Finance-2018-2020` on this Mac. Inspect the actual folder recursively. Approximately 250 Journal of Finance articles from 2018–2020 are expected, but **verify the count and metadata**. Never modify original PDFs. If the folder cannot be accessed, report the blocker; implement and test with fixtures, and never invent corpus results.

These papers predate ChatGPT's public release, **not necessarily all algorithmic writing assistance**. The objective is to learn *abstract scientific and rhetorical conventions*, not to copy authors' words or falsely claim Journal of Finance endorsement. Keep copyrighted source PDFs private, respect license restrictions, and do not distribute full texts or fine-tune on them without verified permission.

## Non-negotiable rules
- Execute the project rather than only proposing a design. Maintain `docs/PROGRESS.md` with verified milestones and blockers.
- Never fabricate articles, bibliographic records, statistics, citations, model outputs, experimental scores, human ratings, significance levels, or completed tests.
- Preserve manuscript data, equations, coefficients, citations, and empirical findings. Flag missing evidence with explicit TODOs.
- Record source provenance (document hash, page, section), extraction confidence, prompt/model version, timestamps, and code version.
- Do not publish, spend money, change global Claude Code configuration, expose private corpora, or modify unrelated repositories without authorization.
- Inspect the host, dependencies, and installed Claude Code version before choosing integrations. Favor local processing, Python 3.11+, DuckDB/Parquet, Pydantic, Typer, and a portable local hybrid-search/vector backend.
- Use existing MacLustr compute only if accessible and authorized. The core must work on one Mac.
- All paper tables and figures must be generated from recorded data by reproducible scripts.

## Repository
Create `wp45-jof250/` with:

```text
CLAUDE.md, README.md, pyproject.toml, Makefile, .env.example, .gitignore
config/{corpus,models,evaluation,rights}.yaml
data/{manifests,derived,annotations,splits}/
src/jof250/{cli,inventory,parsing,metadata,segmentation,rhetoric,features,embeddings,retrieval,generation,auditing,evaluation,provenance,reporting}.py
src/jof250/integrations/claude_code.py
prompts/{annotation,writing,review,evaluation}/
profiles/{empirical_asset_pricing,corporate_finance,financial_econometrics,theoretical_finance}.yaml
.claude/{commands,skills,agents}/
experiments/{protocols,fixtures,outputs,analysis}/
experiments/preregistration.md
paper/main.tex, paper/references.bib
paper/{sections,figures,tables,appendix}/
tests/, scripts/
docs/{PROGRESS,ARCHITECTURE,DATA_DICTIONARY,REPRODUCIBILITY,INSTALL,USER_GUIDE,RIGHTS_AND_ETHICS,LIMITATIONS}.md
```

## Phase 1 — Inventory and verify the corpus
- Recursively inventory files; capture filename, SHA-256, size, page count, validity, title, authors, publication year, DOI, journal, supplements, and parsing status.
- Detect duplicates, alternate versions, non-PDF files, broken PDFs, and papers outside scope.
- Verify metadata against reliable bibliographic sources if network access is authorized; never silently infer missing metadata.
- Generate `corpus_manifest.parquet`, `corpus_audit.md`, inclusion/exclusion records, and a frozen versioned manifest.
- Quantify counts by year, topic, article type, and extraction quality.

## Phase 2 — Scientific PDF extraction
Evaluate suitable installed parsers (e.g. GROBID, PyMuPDF, Docling) using a small manually checked sample. Implement reliable extraction of titles, abstracts, headings, paragraphs, references, citations, equations, tables, figures, captions, notes, appendices, and page locations. Preserve equation/table structures when reliable and mark failures explicitly. Build a manually checked gold-standard sample across years and article types; report parsing accuracy. Store structured documents and confidence scores, not public copies of copyrighted full texts.

## Phase 3 — Scientific rhetoric ontology
Annotate each paper, section, and relevant paragraph with a documented schema covering:
1. Abstract: question, gap, method, results, magnitude, contribution.
2. Introduction: motivation, tension, literature gap, preview, contribution, roadmap.
3. Literature: positioning, contrasts, intellectual lineage.
4. Theory: assumptions, mechanisms, propositions, proofs, limits.
5. Data: sources, sample construction, filters, variables.
6. Identification: estimand, assumptions, threats, causal claims.
7. Empirical design: specifications, fixed effects, errors, notation.
8. Results: interpretation, economic versus statistical significance.
9. Robustness: alternative specifications, placebo tests, sensitivity.
10. Tables: conventions, units, notes, statistical presentation.
11. Figures: labels, axes, uncertainty, substantive interpretation.
12. Conclusion: bounded claims, implications, open questions.

Additionally classify rhetorical moves, claim-evidence relationships, hedging, transitions, argument graphs, and research contribution types. Use schema-validated LLM annotation plus deterministic checks and human-audited samples. Report agreement honestly: model-model agreement is not human inter-rater reliability. Do not impose empirical-paper structure on theory papers.

## Phase 4 — Measured JoF writing profiles
Compute empirical distributions for article/section lengths, contribution placement, abstract structure, equation/table/figure frequency, citations, robustness presentation, appendix structure, and domain-specific patterns. Report medians, interquartile ranges, sample sizes, and uncertainty when relevant. Stratify by article type and subfield where sample size permits. **Observed frequency is not evidence of editorial superiority.** Build inspectable YAML profiles and reproducible visualizations.

## Phase 5 — Retrieval-augmented writing engine
Implement private hybrid retrieval: metadata filters, keyword search, semantic embeddings, and optional reranking. Prefer indexed **abstract structural annotations and summaries**, with limited authorized excerpts only as necessary. Each retrieval result must link to source provenance.

For writing tasks: inspect the target paper and its actual evidence; identify genre and subfield; retrieve relevant rhetorical patterns; propose an outline or revision; maintain all verified facts; show structural rationale; flag unsupported statements; run overlap/citation audits; return LaTeX-ready output plus a change log. Do not mimic a particular author or recycle source sentences. Support theoretical, empirical, and interdisciplinary papers, and explain when JoF conventions are inappropriate.

## Phase 6 — Real Claude Code integration
Create project-scoped Claude Code skills, agents, and slash commands compatible with the **installed** Claude Code version. Validate their registration and execution, and provide optional documented global installation instructions without changing global configuration automatically.

Target user experience:

```text
/jof-status
/jof-corpus-audit
/jof-profile empirical_asset_pricing
/jof-outline /path/to/wp41 --section introduction
/jof-write /path/to/wp41 --section introduction
/jof-review /path/to/wp41 --full
/jof-upgrade /path/to/wp41 --preserve-results
/jof-audit /path/to/wp41 --tables --equations
/jof-evidence /path/to/wp41 --claim "..."
/jof-benchmark --protocol heldout_v1
```

If exact slash-command argument syntax differs in the installed version, implement the supported equivalent and document it. Back commands with a real tested CLI, e.g.:

```bash
jof250 corpus audit
jof250 corpus parse
jof250 profiles build
jof250 retrieve --topic "intraday return forecasting"
jof250 write --paper /path/to/wp41 --section introduction --output /tmp/intro.tex
jof250 review --paper /path/to/wp41 --output /tmp/review.md
jof250 benchmark --config config/evaluation.yaml
```

Implement specialist agents where supported: Corpus Auditor, Rhetorical Analyst, Finance Writing Editor, Econometric Referee, Table/Figure Editor, Citation/Integrity Auditor, and Replication Auditor. Use validated handoffs. Default to proposed patches or new output files, not silent modification of manuscripts. Generate diffs and audit reports. Ensure commands work from a separate sample research repository, not just within WP45.

## Phase 7 — WP45 research design
**Question:** Do abstract, domain-specific writing conventions extracted from a pre-ChatGPT finance corpus improve LLM-assisted scholarly writing and review beyond standard prompting and conventional RAG, while maintaining originality, factual accuracy, and reproducibility?

**Preregister hypotheses before testing:**
- H1: Structured rhetorical retrieval improves blind human-rated argument clarity and contribution positioning.
- H2: Domain-specific profiles outperform generic corpus retrieval on finance writing tasks.
- H3: Specialist referee/revision workflows improve methodological criticism and presentation without changing verified facts.
- H4: Evidence checks reduce unsupported claims and fabricated references.
- H5: Improvements persist on held-out tasks and do not depend on near-verbatim source overlap.

**Conditions:** A baseline Claude with minimal instruction; B strong academic-writing prompt; C conventional RAG; D structured JoF profiles plus retrieval; E full engine with verification and specialist review. Add ablations for retrieval, profile, referee, and factual checks.

**Controls:** Same model version, task, source evidence, output constraints, and preferably comparable token/compute budgets. Log costs, latency, tokens, retries, prompt versions, model versions, random seeds when supported, and nondeterminism. Use repeated trials and predefined primary outcomes. Freeze document-level corpus splits and avoid overlap by duplicate, version, author, or closely related study where feasible. Held-out articles must not influence profile construction or prompt tuning. Explicitly acknowledge possible foundation-model pretraining contamination.

**Tasks:** Draft an introduction from a verified research brief; rewrite a weak literature positioning section; improve an empirical specification explanation; interpret fixed results; improve a table and caption; identify unsupported causal claims; produce a referee report; improve an abstract without altering findings. Use carefully prepared research briefs and verified evidence; never evaluate fabricated results as real finance findings.

**Evaluation:** Blind qualified human reviewers when available, using randomized outputs and calibrated rubrics for clarity, argument logic, contribution positioning, methodological rigor, fidelity, and usefulness. Measure factual error rates, citation verification, numerical preservation, text overlap, latency, cost, and reproducibility. Automated LLM judges may supplement but cannot replace independent human assessment; report judge bias and agreement. Use suitable hierarchical/mixed-effects or paired analyses, confidence intervals, multiple-comparison corrections, and effect sizes; select methods based on actual sample design. No significance claims before data exist.

**Generalization:** Include held-out finance topics and at least one out-of-domain condition, such as computer science. Compare gains and failures rather than claiming universal improvement.

**Research ethics:** Verify publisher rights, avoid leaking protected full texts into external APIs without authorization, minimize quotations, document model usage and human oversight, and distinguish writing quality from scientific novelty. No claims of causal identification unless supported by experimental design.

## Phase 8 — Produce the actual WP45 paper
Write polished academic English in LaTeX with a serious scholarly tone and restrained claims. Proposed sections:

1. Introduction and research question
2. Related literature: scientific writing, genre/rhetorical analysis, RAG, agentic editing, evaluation of LLM-assisted research
3. Corpus, inclusion rules, rights, and descriptive statistics
4. Extraction pipeline and annotation ontology
5. JoF-250 architecture and Claude Code implementation
6. Experimental design, hypotheses, and preregistration
7. Results (ONLY verified completed experiments)
8. Ablations, robustness, contamination and leakage checks
9. Human evaluation and failure analysis
10. Discussion: generalization, research integrity, limitations
11. Conclusion
12. Extensive appendices: taxonomy, prompts, schemas, code, parser QA, splits, protocols, additional results, reproducibility, user manual

Conduct a careful literature review using reliable sources where authorized. Verify every DOI and reference; never invent citations. Build figures such as the architecture, corpus flow, rhetorical move taxonomy, experimental conditions, performance comparisons, ablations, and error analysis **only where underlying evidence exists**. Unfinished experiments must appear as clearly labeled protocols or TODOs, never synthetic findings. Compile the PDF, resolve LaTeX errors, and verify references, figures, equations, and table consistency.

## Phase 9 — Engineering tests and release criteria
Implement unit, integration, and end-to-end tests for: inventory, hashes, duplicates, parsing, schema validation, retrieval relevance, provenance, access restrictions, CLI, Claude Code commands, LaTeX export, citation checks, numerical preservation, overlap detection, and failure modes. Use small synthetic fixtures and explicitly distinguish them from real experimental observations.

Before declaring completion, demonstrate:
1. Real corpus audit and verified article count.
2. Parsed and quality-checked corpus with documented failure rate.
3. Working profile generation and inspectable source evidence.
4. Retrieval on a real topic with provenance.
5. One complete manuscript-section drafting example and one review example, with no fabricated facts.
6. Claude Code commands working in a separate project.
7. Repeatable evaluation protocol and actual results where conducted.
8. Compiled WP45 PDF and reproducible figures/tables.
9. Documented install, usage, permissions, limitations, and tests.
10. A final `docs/DELIVERY_REPORT.md` listing completed features, commands run, actual measurements, uncompleted work, and blockers.

## Execution order
Proceed sequentially: **audit → plan → corpus inventory → parsing QA → ontology → profiles → retrieval → Claude Code integration → experimental protocol → experiments → WP45 manuscript → full QA**. You may write the paper's methods while building, but never write results ahead of measurement. Commit in logical milestones if this is a Git repository and the user has authorized repository changes. Do not claim to have completed a phase until its acceptance checks pass.

## Final requirement
The project is not complete if it produces only a research article, only a prompt, only a vector database, or only a demo. **WP45 must study the system, and the system must be independently useful to Claude Code for future scientific papers.** Scientific integrity and operational correctness outrank length, novelty claims, or visual polish.

---

## Operating notes (added by the executor, 2026-11-03)

- **Location**: `~/Desktop/UQO/Recherche/Recherche-UQO/methodes/wp45-jof250/` (UQO working-paper standard, `HARMONISATION.md`); git `origin` = `gitsrv:srv/git/wp45_uqo.git`.
- **Corpus actually present**: 277 valid PDFs, volumes 72–75 (2017–2020), downloaded 2026-11-03 through the UQO library proxy (Safari session). 2017 is in the folder and is kept in scope (all pre-ChatGPT); the name « JoF-250 » is a label, the verified count is in `data/manifests/corpus_audit.md`.
- **Environment**: `.venv` (uv, Python 3.12) ; run everything with `.venv/bin/jof250 …` or `make …`. Tests: `make test`.
- **Secrets**: API key read from `.env` → `JOF250_ANTHROPIC_KEY_FILE` (never committed, never printed). Budget envelope: see amendment A-001 in `docs/PROGRESS.md`.
- **Global Claude Code install** was explicitly requested by the user (« accessible à toutes les sessions Claude Code ») → `jof250 install-claude-code --scope user` copies commands/skill/agents into `~/.claude/` with the `jof-` prefix only; nothing else in the global configuration is touched.