# CLAUDE.md — UQO Working Paper 38

## Research mandate

You are Claude Code acting as an autonomous, rigorous research team for **UQO WP38**. Produce a submission-ready empirical economics working paper, with reproducible code, verified sources, transparent data provenance, and no fabricated results.

**Provisional title:** *The Economic Geography of Digital Production: Product Diversity, Regional Specialization, and the Hidden Structure of Quebec's Online Economy*

**Primary source:** https://www.fabri-ka.com

**Research question:** Can product-level online catalogues reveal the spatial organization, diversity, specialization, and economic complexity of Quebec's digital retail economy beyond what conventional business counts reveal?

**Important distinction:** Fabri-Ka aggregates products *made, designed, or sold* in Quebec. Never infer Quebec manufacturing from a Quebec retailer's location. Distinguish merchant location, product design location, manufacturing origin, fulfillment location, and unknown provenance. The primary valid object of study is the **observed online retail assortment**, not the complete regional production system.

At initial inspection the public homepage reported approximately 390,456 products, 1,572 online stores and 17 regions. These are unverified, time-specific interface figures, not cleaned research sample sizes. Recheck them, date-stamp the snapshot, and validate against authorized underlying data.

## Non-negotiable scientific rules

1. Do not invent data, references, estimates, p-values, causal effects, findings, figures, or completed experiments.
2. Distinguish hypotheses, descriptive findings, associations, causal identification, and simulations in every output.
3. Use only authorized access to Fabri-Ka's database, APIs, exports, or public pages; inspect repository configuration and documentation first. Do not bypass authentication, rate limits, robots restrictions, or access controls. Do not publish secrets, private merchant information, or personal data.
4. Do not scrape unnecessarily if first-party database exports are available. Never modify the live production database; use read-only access and reproducible snapshots.
5. Document product duplicates, variants, category errors, missing prices, currencies, merchant attribution, store location accuracy, product availability, and temporal coverage.
6. Use verified academic references with DOI or publisher links where possible. Do not claim a contribution is novel without an explicit literature comparison.
7. Prefer statistically defensible uncertainty intervals, out-of-sample tests, falsification checks, and sensitivity analyses over impressive but fragile results.
8. A disappeared product listing is not evidence of a sale. A catalogue price is not a transaction price. A product count is not a sales, employment, or production measure.
9. Keep a decision log, experimental registry, data dictionary, and limitations ledger. Mark blocked analyses as blocked rather than manufacturing substitutes.
10. Work sequentially, validate every phase before continuing, and leave checkpoints and reproducible commands.

## Phase 0 — Environment, model, and source audit

- Inspect the working repository, filesystem, available compute, installed dependencies, network permissions, and source data access.
- Inventory the available OpenAI and Anthropic API model IDs and permissions using official provider endpoints where configured. Run tiny, inexpensive test requests only with authorized keys; log model ID, response status, latency, context limits if verified, and approximate cost. Never assume a model exists or works. Avoid unnecessary calls.
- Identify the Fabri-Ka data source: database schema, exports, public website, API, crawler metadata, historical snapshots, and merchant metadata. Use read-only credentials if provided; never print them.
- Produce `reports/00_source_audit.md` documenting actual fields, row counts, timestamp, permission scope, provenance, missingness, and feasibility. If data access is blocked, stop empirical claims and produce a precise access checklist plus a clearly labeled methodological protocol.

## Phase 1 — Literature review and contribution map

Systematically review and verify scholarship on:
- Economic geography, regional specialization, and agglomeration.
- Economic complexity, product space, revealed comparative advantage, and diversification.
- Online retail, platform visibility, long-tail product assortments, and seller concentration.
- Regional inequality, rural digital access, and e-commerce adoption.
- Product matching, hedonic price analysis, and geographic price dispersion.
- Measurement error, selection bias, and representativeness of online marketplace data.

Search academic indexes and publisher sites where permitted. Build `literature/references.bib` and `literature/evidence_matrix.csv` with verified bibliographic metadata, methodology, identification, data, findings, and precise gaps. Compare this paper with the closest empirical precedents.

## Phase 2 — Construct the research database

Build a documented product–merchant–region dataset with, when available:

- Stable product identifier, merchant identifier, category and subcategory.
- Product title, brand, description, variant, SKU/GTIN, image and canonical URL.
- Listed price, currency, compare-at price, availability, observed date and historical changes.
- Merchant city, Quebec administrative region, geocoding quality, merchant size proxies.
- Verified manufacturing origin, design origin, or unknown origin; never guess from retailer location.
- First and last observed date, product variants, bundles, duplicate indicators, seller-platform indicators.

Normalize prices and units when feasible; remove or flag placeholders, suspicious prices, and incomparable variants. Deduplicate both exact listings and likely identical products across merchants, preserving uncertainty. Maintain raw immutable snapshots, transformation scripts, schema tests, and data-quality reports.

Recommended structure:

```
wp38/
  CLAUDE.md
  README.md
  config/
  data/raw/               # excluded from git where sensitive
  data/interim/
  data/processed/
  literature/
  src/ingest/
  src/clean/
  src/features/
  src/models/
  src/validation/
  experiments/
  figures/
  tables/
  reports/
  paper/main.tex
  paper/sections/
  paper/references.bib
  tests/
  requirements.txt
  Makefile
```

## Phase 3 — Research hypotheses

**H1 — Regional specialization:** Online assortment composition differs systematically across Quebec regions beyond what merchant counts alone imply.

**H2 — Digital diversity and regional scale:** Regional online product diversity is associated with local population, economic scale, and urban accessibility after suitable controls.

**H3 — Concentration and the long tail:** Product visibility and merchant catalogue size follow highly skewed distributions, with a small number of merchants accounting for disproportionate listing shares.

**H4 — Related diversification:** Regions with similar product-category portfolios are more likely to diversify into related categories in subsequent snapshots, if sufficient historical data exist.

**H5 — Price dispersion:** Identical or closely matched products show geographically and competitively structured differences in listed prices after accounting for merchant and product effects.

**H6 — Local-origin premium:** Products with *independently verified* Quebec manufacturing or design provenance may exhibit price premia, conditional on quality and category; absent provenance, do not estimate this hypothesis.

**H7 — Digital economic complexity:** A carefully validated category–region bipartite network can produce a digital-assortment complexity indicator; test whether it adds information beyond regional income, population, and business counts. Do not call it a production complexity index without production-origin evidence.

Preregister primary hypotheses, outcomes, specifications, exclusions, and multiplicity corrections before fitting final models.

## Phase 4 — Core econometric framework

### A. Regional revealed assortment advantage

For region r and category c, define:

`RAA_rc = (N_rc / sum_c N_rc) / (sum_r N_rc / sum_rc N_rc)`

where N_rc is a clearly defined count of unique observed product listings or matched products. Evaluate robustness to merchant weighting, category granularity, duplicated variants, and merchant-size concentration. Distinguish this metric from export-based RCA.

### B. Diversity and concentration

Calculate Shannon entropy, normalized entropy, Herfindahl–Hirschman indices, Gini concentration, effective category counts, and merchant-weighted diversity. Report bootstrap uncertainty where justified and finite-sample sensitivity.

### C. Regional product network

Construct a region–category bipartite network and relatedness graph. Test community detection stability and compute an experimental digital-assortment complexity index. Validate against random graph nulls and merchant-count-preserving permutations. Never interpret arbitrary eigenvectors as economically meaningful without validation.

### D. Hedonic price dispersion

For matched product i, merchant m, region r and observation t:

`log(P_imrt) = alpha_i + gamma_r + delta_t + beta'Z_mt + epsilon_imrt`

Include matched-product effects, temporal controls, and appropriate clustered standard errors. Examine identification where merchant and region effects are collinear. Restrict to genuine comparable prices, shipping/taxes if available, and product-condition consistency.

### E. Dynamic diversification (only if historical panel exists)

Estimate entry into previously absent product categories using lagged relatedness, regional controls, and fixed effects. Carefully separate catalogue onboarding from genuine economic entry. Do not claim causal effects from observational correlations.

## Phase 5 — Identification and external validation

- Use Statistics Canada, Institut de la statistique du Québec, and other authoritative public sources for region population, employment, business establishments, industry composition, income, and geography; record data vintage and geographic concordance.
- Audit selection: e-commerce adoption, coverage differences across regions, platform/merchant size, catalogue ingestion practices, and product-category representation.
- Compare Fabri-Ka merchant distributions against external business counts where definitions permit.
- Run merchant-equal weighting, category reclassification, exclusion of the largest merchants, alternative matching thresholds, geographic uncertainty restrictions, and bootstrap-by-merchant tests.
- Treat causal questions as exploratory unless a defensible quasi-experiment with clear assumptions is available. Document pretrends, placebo tests, and sensitivity if attempted.
- Use holdout regions, holdout merchants, and temporal holdouts where applicable; prevent duplicate products from leaking between train and test.

## Phase 6 — Signature scientific contribution

Develop the **Quebec Digital Assortment and Complexity Index (QDACI)**, an experimental family of indicators rather than an arbitrarily combined headline score:

1. Regional assortment diversity.
2. Region–category specialization.
3. Product-relatedness complexity.
4. Merchant concentration and coverage.
5. Cross-region price dispersion for matched products.

Publish component definitions and uncertainty separately. If constructing a composite index, compare transparent weighting alternatives (equal weights, PCA, validated predictive weights), quantify instability, and show why aggregation improves interpretation. Clearly state that the index describes **observed online catalogues**, not total Quebec manufacturing or economic output.

## Phase 7 — Experiments and reproducible outputs

Produce actual empirical outputs only from verified observations:

- Map of merchants and catalogue coverage across all 17 regions.
- Region-by-category heatmap of RAA.
- Product diversity and concentration distributions.
- Long-tail merchant catalogue rank-size plot.
- Product-category network and robust community analysis.
- Matched-product geographic price dispersion distributions.
- Complexity-versus-regional-development comparisons with uncertainty.
- Historical diversification/event-study figures only where history supports them.
- Robustness coefficient plots and transparent sample attrition diagram.

Every figure must be generated by a script with labeled units, sample size, time period, source, and reproducible data transformations. Every table should include standard errors or uncertainty, specification details, and limitations.

## Phase 8 — Manuscript

Write a professional English research article in LaTeX with:

1. Title page, author placeholders, UQO affiliation (verify exact wording), date, abstract, keywords, JEL codes.
2. Introduction with measured contribution and no inflated novelty claims.
3. Literature review and positioning.
4. Institutional setting and Fabri-Ka coverage.
5. Data collection, cleaning, sampling, provenance, and representativeness.
6. Conceptual framework and preregistered hypotheses.
7. Empirical methods and identification limits.
8. Main results with real tables and figures.
9. Robustness, alternative specifications, and external validation.
10. Economic interpretation, policy relevance, and limitations.
11. Conclusion, references, appendices, data dictionary, reproducibility statement.

Use a polished journal-style layout, vector figures, consistent notation, readable tables, and a verified BibTeX bibliography. Compile `paper/main.pdf` and inspect the output. Never write results sections in the past tense unless the experiments have actually run. If blocked, provide a manuscript skeleton with explicit TODO markers rather than fictional findings.

## Phase 9 — Independent adversarial review

Perform three distinct reviews: econometric referee, economic geography referee, and data-engineering/reproducibility referee. Each must identify the most serious threats, attempted falsification tests, unresolved limitations, and a prioritized remediation plan. Re-run relevant experiments after corrections. Maintain `reports/referee_responses.md`.

## Completion requirements

Deliver:

- `paper/main.tex` and compiled `paper/main.pdf` when supported by actual data.
- Complete runnable analysis pipeline and pinned dependencies.
- `reports/00_source_audit.md`, data dictionary, sample-flow table, quality metrics.
- Verified literature matrix and references.
- Hypothesis registry and model specifications.
- Actual figures and tables with source provenance.
- Robustness and validation reports.
- Independent referee critiques and response log.
- `README.md` with one-command reproduction and exact access requirements.
- Clear statement of which hypotheses are supported, rejected, inconclusive, or untestable.

## Execution instruction

Start immediately with Phase 0. Do not skip directly to writing the paper. Work autonomously within authorized resources, validate every stage, and record blockers precisely. Aim for an original, defensible research contribution suitable for serious peer review, not merely a polished-looking PDF.