quantrank-app

name: quantrank-app description: Build, modify, or extend QuantRank — a static-site US equity ranking application that combines fundamental, technical, factor, sentiment, and ML analysis into a 0-100 composite StockRank with ensemble fair price. Architecture is GITHUB-ACTIONS-FIRST (no backend server, no database) — Python script computes scores weekly and outputs JSON files; Next.js static site reads JSON and renders the UI; everything deploys free via Vercel. Roadmap is OPTION B (research-backed) with Option A as fallback. Use when the user wants to create QuantRank from scratch, add new analysis pillars or metrics, improve scoring methodology, integrate new free data sources, build the GitHub Actions compute pipeline, design the JSON output schema, build the Next.js static frontend, set up scheduled refresh workflows, deploy to Vercel, or troubleshoot any part of this static ranking system.

QuantRank — Build & Maintenance Skill

A skill for building and extending QuantRank, a static-site US equity stock ranking application that ranks stocks 1..N using 60+ classical analysis techniques plus advanced ML/NLP/regime-detection methods, augmented by research-backed peer-reviewed libraries (Option B roadmap).

Project knowledge files (loaded into the project):

• stock_ranking_knowledge.md — authoritative reference for ALL classical formulas, data sources, normalization rules. Always consult before implementing any analysis technique — never invent formulas.
• WORKFLOW.md — phase-by-phase build plan (9 phases, 0-8). Always check current phase before working.
• RESEARCH_FINDINGS.md — research-backed stretch additions for Phase 4-8 (Option B roadmap).

Contents

• Core Project Goal
• Architecture: Static-Site Pattern
• Required Tech Stack
• Roadmap Strategy
• Repository Structure
• JSON Output Schema — includes schema-version table
• Core Behavior Rules — Rules 1-18, the canonical rulebook
• When the user asks for…
• Anti-Patterns to Refuse
• Communication Style
• End State Definition

Rules at a glance

Core Project Goal

Build a static web app (no backend server, no database) that:

1. Pulls free-tier financial data for US stocks (S&P 500 → S&P 1500 in stages)
2. Computes 60+ classical metrics + advanced sentiment/ML/regime features
3. Phase 4+: Augments with peer-reviewed library factors (OSAP, JKP, Qlib Alpha158, IPCA)
4. Normalizes them sector-relative into 8 pillar scores (0-100 each)
5. Combines via meta-learner into a final composite StockRank (0-100)
6. Computes ensemble Fair Price (DCF + Graham + Residual Income + multiples)
7. Surfaces top-5 SHAP explanations per stock
8. Outputs everything as JSON files committed to the repo
9. Refreshes weekly via GitHub Actions cron
10. Renders via Next.js static site deployed on Vercel
11. Public GitHub repo — fully reproducible, free GitHub Actions

⚠️ ARCHITECTURE: STATIC-SITE PATTERN (Option D)

This is the most important rule. Read carefully.

What this app IS:

• A GitHub Actions cron job that runs Python weekly to compute rankings
• A Next.js static site that reads pre-computed JSON files
• A public GitHub repo with auto-committed JSON outputs
• Deployed to Vercel free tier with auto-deploy on push
• Phase 5+: Hybrid compute — heavy ML training on Kaggle/Modal, light scoring on GitHub Actions

What this app is NOT:

• ❌ NOT a FastAPI/Flask/Express backend
• ❌ NOT using PostgreSQL/SQLite/MongoDB at runtime
• ❌ NOT making live API calls from the frontend
• ❌ NOT computing scores on user request
• ❌ NOT a real-time/intraday system

Compute Flow (Phase 0-3):

[GitHub Actions cron, Mon-Fri 22:00 UTC — PR 4f, was weekly Sunday]
    ↓
Python script → fetch data → compute features → output JSON
    ↓
Auto-commit JSON files to public/data/ in repo
    ↓
Push triggers Vercel auto-deploy
    ↓
[User opens site] → Next.js loads pre-computed JSON → renders UI

Compute Flow (Phase 5+ with heavy ML):

[GitHub Actions weekly cron]
    ↓
Light pipeline (ingestion + scoring) → JSON
    ↓
[Kaggle Notebooks monthly]
    ↓
Heavy training (LightGBM, autoencoder, FinBERT batch) → models
    ↓
[Modal $30/mo credits, quarterly]
    ↓
Whisper transcription + Llama-3 MD&A inference → embeddings
    ↓
All artifacts → repo public/data/ → Vercel deploy

Why this architecture:

• Free forever: Vercel hobby + GitHub Actions on public repo + Kaggle/Modal free tiers = $0
• Mobile-friendly dev: Claude Code app + GitHub mobile + Vercel mobile = full workflow
• Fast for users: pre-computed JSON served via CDN, no DB queries
• Simple: no auth, no rate limiting, no API design needed

Required Tech Stack

DO NOT deviate without explicit approval. Canonical stack list lives in CLAUDE.md §Stack — Python 3.11+ · Next.js 14.2 · GitHub Actions · Vercel · SEC EDGAR + yfinance. Below covers only the phase-specific additions + license caveats that the long-form rulebook needs.

Phase 4+ stretch additions (Option B)

Optional-dep additions by phase (gated behind [project.optional-dependencies]):

Supabase note: connector is registered (mcp__supabase__* in Claude Code) but the Python client is deferred — add supabase to pyproject.toml only inside the implementation PR that first wires a real table call. See CLAUDE.md §Connectors.

mlfinlab is BANNED — all-rights-reserved (Hudson & Thames commercial license). Reimplement Triple-Barrier + Meta-Labeling + Purged CV from López de Prado 2018 directly under MIT. Algorithms are not patented.

Roadmap Strategy: Option B with Option A Fallback

Active Plan: Option B (Research-Backed)

• Phases 0-3 unchanged from original WORKFLOW.md → ship v1.0
• Phase 4 NEW: Factor Consolidation (OSAP + JKP + Qlib + IPCA)
• Phase 5 ENHANCED: ML + Triple-Barrier + Meta-Labeling + Conformal Prediction
• Phase 6 ENHANCED: Sentiment v2 (Whisper + 8-K events + Lazy Prices)
• Phase 7 ENHANCED: Regime v2 (Student-t HMM + TDA + NCO)
• Phase 8: Universe expansion to S&P 1500

Fallback Plan: Option A (Original WORKFLOW.md)

Triggers reverting to Option A per-phase if:

• Library integration > 1 week of blockers
• License conflict (e.g., mlfinlab AGPL incompatibility)
• Heavy compute setup fails (Kaggle/Modal access issues)
• Validation shows no alpha lift from research addition

Each phase has explicit fallback triggers in WORKFLOW.md.

Performance Expectations

Honest hedge: 3-7% is research-suggested upper bound; 2-4% is realistic floor. Wide confidence interval [0%, +5%] on any single 3-year window. Some research papers cited may have decay, replication issues, or in-sample bias — see RESEARCH_FINDINGS.md caveats.

Repository Structure

CLAUDE.md §Layout has the live top-level path table. AGENTS.md §Project structure has the granular tree with file-purpose annotations. This file's role: lock the module-level breakdown that future phases must align with.

JSON Output Schema (Critical Contract)

The compute/ and frontend/ are decoupled by these JSON contracts. Never break them.

Schema versions:

Phase 4+ schemas are tracked in WORKFLOW.md "Defense Roadmap" until shipped. The table above documents shipped schemas only — the roadmap doc is the single source of truth for unshipped work and avoids drift between two places.

public/data/metadata.json

{
  "version": "1.0.0",
  "last_update_utc": "2026-05-11T22:00:00Z",
  "next_update_utc": "2026-05-18T22:00:00Z",
  "universe": "SP500",
  "universe_size": 503,
  "compute_run_id": "abc123def",
  "git_commit": "...",
  "phase": 3,
  "roadmap": "Option B"
}

public/data/rankings.json (summary)

[
  {
    "rank": 1,
    "ticker": "AAPL",
    "name": "Apple Inc.",
    "sector": "Information Technology",
    "composite_score": 87.4,
    "current_price": 220.15,
    "fair_price": 245.30,
    "max_fair_price": 285.00,
    "margin_of_safety_pct": 10.3,
    "pillar_scores": {
      "quality": 92, "value": 65, "growth": 78, "momentum": 84,
      "health": 95, "sentiment": 70, "ml": 80, "risk": 88,
      "technical": 75, "profitability": 90
    },
    "confidence_interval_95": [78.2, 92.1]
  }
]

public/data/stocks/{TICKER}.json (full detail)

(Same structure as before with additions for Phase 4+ research features. See WORKFLOW.md for full detail.)

Core Behavior Rules

Rule 1: Always reference the knowledge documents

Before implementing any analysis technique:

• Phase 0-3: Read stock_ranking_knowledge.md
• Phase 4+: Read RESEARCH_FINDINGS.md for stretch additions
• Use formulas AS WRITTEN. Never reinvent without justification.

Rule 2: Phase discipline

Work in phases per WORKFLOW.md. Do not skip ahead. Each phase produces a working deliverable. Phase 4 starts only after v1.0 ships.

Rule 3: GitHub-Actions-first development

The user develops on mobile (no local Python/Node), so all testing/running happens in GitHub Actions / Kaggle / Modal. CI must catch errors before merge. Use workflow_dispatch for ad-hoc runs. Logs are primary debugging tool.

Rule 4: Free-tier first + license verification

Every API/library must respect free-tier limits AND have compatible license:

• Verify OSS license before integration (especially mlfinlab AGPL)
• Cache aggressively to compute/cache/ (gitignored)
• Implement tenacity retry with exponential backoff
• Phase 4+: Verify current data availability before integration (sources change)

Rule 5: Point-in-time data discipline

Look-ahead bias kills backtests. Every fundamental MUST use filing_date, not period_end. 13F is lagged 45 days. Form 4 uses transactionDate. SEC EDGAR exposes both — always use the filing date. Phase 4+ OSAP/JKP signals are pre-built with proper PIT discipline; verify any reconstructions match.

Rule 6: Sector-relative for fundamentals

Quality, Value, Growth, Profitability — always rank within GICS sector, never globally. Use absolute ranking only for Risk and Momentum. Always exclude financials/utilities from Magic Formula and asset-turnover metrics.

Rule 7: Missing data → sector median

• <50% of pillar's metrics available → set pillar to neutral (50) and flag.
• Single metric NaN → impute as sector median (NEVER global median).
• Never propagate NaN; record imputed fields in data_quality.imputed_metrics.

Rule 8: Test golden values

For every fundamental metric, write a unit test against a known-correct value for at least 1 ticker. Phase 4+: Validate library outputs against published paper results within 5% tolerance.

Rule 9: JSON schema is sacred

The frontend/ consumes JSON with strict expectations. Never break the schema mid-development. Bump version per phase per Schema versions table above.

Rule 10: No paid data, no real-money, no live trading

This app is for research and educational ranking only. README and frontend MUST display this disclaimer. Never integrate live trading APIs.

Rule 11: Trademark caution

Never use "Jitta" anywhere. The project name is QuantRank.

Rule 12: Atomic JSON writes

Always write to a .tmp file then os.rename() to final path. Never write partial JSON.

Rule 13: Fallback discipline (Option B specific)

Per-phase fallback triggers documented in WORKFLOW.md. If hit:

• Log decision in PHASE_STATUS.md
• Revert that phase to Option A
• Continue with subsequent phases on Option B
• Do not silently abandon research additions; document why

Rule 14: Decay monitoring (Option B specific)

For research-backed factors (Phase 4+):

• Track rolling 24-month IC per signal
• Alert when slope < 0 with t < -2
• McLean-Pontiff suggests 35% post-publication decay; budget for it
• Re-validate quarterly against published paper t-stats

Rule 15: Performance ceiling honesty

Never claim alpha > 5% net without:

• 10+ years walk-forward validation
• Embargoed/purged CV
• Deflated Sharpe < 0.5
• PBO < 50%
• Out-of-sample period including 2020 + 2022 regime stress

Rule 16: Defense layer is annotate-and-veto-Top-N (NEW 2026-05-09)

Risk overlays and fraud-detection signals never modify the composite score. They operate in three modes only:

1. VETO — exclude flagged stock from entered_top5 badge (composite rank unchanged). 7 active at Phase 4.5a (2026-05-16): Altman Z″ distress (altman_distress), Sloan accruals top decile within sector (sloan_accruals_top_decile, sector-relative since PR #89), Net Stock Issuance top decile (Pontiff-Woodgate 2008, net_issuance_top_decile), data_quality_input_corruption (promoted PR #33), non_reliance_filing (re-enabled PR #79, 8-K Item 4.02, Schroeder 2024 SSRN — 365d lookback), beneish_manipulation_veto (Beneish 1999, M > −1.78 PPV-crossover, PR #90), dechow_manipulation_veto (Dechow et al. 2011, F > 3.0 4× baseline, PR #91).
2. GUARD — return null + flag (e.g., null fair_price for stale filings). 5 numerical guards at v1.0.
3. ANNOTATE — warning only, no score change. 8+ flags at v1.0 + recommendation (PR 4d) + loss_chance_pct (PR 4e) — both pure derivations from existing fields, no new ingest.

Why never scoring inputs: empirical evidence (Beneish-Vorst 2021; McLean-Pontiff 2016) shows fraud-detection FP rates ≥30% in broad market and anomaly returns decay 58% cumulative. Penalizing the score introduces more error than it removes.

Defense freeze post-v2.0: Do NOT add new defenses unless an existing defense's IC has decayed > 50% for 6+ months AND the new addition has academic evidence of incremental IC > 0.01. Marginal AAER capture < 5% beyond 4 fraud signals (Beneish-Vorst 2021). Rotate, don't stack.

Full defense schedule and bibliography in docs/RESEARCH_FINDINGS.md §"Defense Playbook".

Rule 17: Frontend design system + threshold-symbolic tests (NEW 2026-05-15)

Two pattern locks landed during PRs 4d / 4e and apply to every Phase 4+ UI / scoring contribution:

1. Outlined-light chip family, with paired dark: variants — every new pill / badge / chip (sector, score-tier, MoS bucket, recommendation, loss-chance) uses the Pattern B outlined-light style codified in .claude/skills/frontend-design-system/SKILL.md Rule 2. Solid-bg chips are an anti-pattern. Ship a paired dark: variant on every colored surface — since Phase 3b the site runs class-strategy dark mode (darkMode: 'class' + a next-themes toggle), so dark: activates on the .dark class (an explicit user choice), NOT bare system prefers-color-scheme; a light-only surface is now the bug (near-invisible on the dark band). (The pre-Phase-3b "no dark:" rule — PR #70's invisible-label regression on a force-light + darkMode: 'media' page — is retired; see frontend-design-system SKILL.md Rule 4 for the pairing table + full history.) Trigger the design-system skill before any new UI.

2. Tests reference thresholds symbolically, not by literal value — pure-function scorers like derive_recommendation and derive_loss_chance expose their thresholds as module-level constants (BULLISH_COMPOSITE_MIN, BULLISH_MOS_MIN_PCT, etc.). Tests must import the constants and assert against constant ± 1.0 style boundaries — never against hard-coded numbers. This insulates the test suite from threshold tuning: when the constant moves, tests stay green if the function still respects the constant. PR 4d's calibration revision (composite 70 → 60, MoS 20 → -10 after the S&P 500 distribution simulation surfaced 0% Strong Buy and 54% Sell) broke 5 hard-coded tests and was the forcing function for this rule.

Rule 18: Observability-before-wiring (NEW 2026-05-20)

Every integration PR that consumes a NEW external data source ships the diagnostic Metadata surface BEFORE the production logic uses the data. The diagnostic exposes WHICH inputs were dropped and WHY at each filter / gate / NaN-strip point; production wiring lands ≥ 1 cron later, after the accounting equation len(input_universe) == sum(len(diagnostic_buckets)) is verified on real data. The Phase 4h → 4h.2 retrofit (PRs #112 → #118 → #124) is the forcing precedent: a 30-minute additional Phase 4h scope would have saved the ~10-hour 2-PR debugging cycle. Detail + mandatory checklist in WORKFLOW.md §Observability-Before-Wiring Pattern.

When the user asks for...

"Build the project from scratch"

1. Read WORKFLOW.md Phase 0.
2. Confirm: project name = QuantRank, repo = public, Vercel deploy.
3. Execute Phase 0 tasks. Update PHASE_STATUS.md at end.

"Add a new metric (Phase 0-3)"

1. Search stock_ranking_knowledge.md for the technique.
2. Identify pillar (per Section 21 / Quick Reference A).
3. Add function to compute/features/<pillar>.py with golden-value test.
4. Update pillar aggregation in compute/scoring/pillars.py.
5. Add field to raw_metrics in compute/output/schemas.py.
6. Update TypeScript types in frontend/lib/types.ts.
7. Run CI to verify.

"Add a research-backed feature (Phase 4+)"

1. Read RESEARCH_FINDINGS.md for the technique.
2. Verify license compatibility (especially AGPL libraries).
3. Verify current data source availability (re-check URLs).
4. Add module to appropriate compute/ directory.
5. Validate output against published paper results (5% tolerance).
6. If validation fails → trigger fallback to Option A for that phase.
7. Document in PHASE_STATUS.md.

"Add a new data source"

1. Check Section 5 of knowledge doc — already covered?
2. Phase 4+: Check RESEARCH_FINDINGS.md data sources.
3. New file in compute/ingest/<source>.py matching existing pattern.
4. Add API key (if needed) to GitHub Actions secrets.
5. Document rate limits and license in module docstring.

"Improve accuracy"

1. Manage expectations per Section 28 (realistic = 2-4% Option A, 3-7% Option B).
2. Check current phase. Don't add Phase 6 features in Phase 4.
3. Don't add LSTM before LightGBM works.
4. Phase 4+: Prioritize OSAP/JKP factor library over DIY signals.
5. Always validate via IC, IR, PBO before claiming improvement.

"The site is broken / shows old data"

1. Check PHASE_STATUS.md for current phase.
2. Check latest GitHub Actions run — failed?
3. Check public/data/metadata.json — what's last_update_utc?
4. Check Vercel deployment logs.
5. Recovery: trigger manual-trigger.yml workflow.

"Deploy to production"

1. One-time setup (Phase 0):
   • Push repo to GitHub (public).
   • Connect repo to Vercel (auto-detects Next.js).
   • Set Vercel build settings: root = frontend/, output = out/.
2. Trigger first compute: GitHub Actions → compute-rankings.yml → Run workflow.
3. Verify: After ~10 min, JSON appears, Vercel rebuilds, site goes live.

"Set up Phase 5+ heavy compute"

1. Connect Kaggle account (free) → generate API token.
2. Add KAGGLE_USERNAME, KAGGLE_KEY to GitHub secrets.
3. Connect Modal account (free $30/mo credits).
4. Add MODAL_TOKEN_ID, MODAL_TOKEN_SECRET to GitHub secrets.
5. Set up workflow to trigger Kaggle from GH Action via kaggle kernels push.
6. Outputs: Kaggle Dataset → re-pull into repo via API.

Anti-Patterns to Refuse

Communication Style

The user develops on mobile and may not be a quant expert.

• Formulas (Phase 0-3): link to section in stock_ranking_knowledge.md.
• Research additions (Phase 4+): link to section in RESEARCH_FINDINGS.md + paper citation.
• Realistic expectations: cite Section 28 + RESEARCH_FINDINGS caveats.
• Mobile constraints: prefer GitHub Actions/Kaggle/Modal runs over local debugging.
• Iteration: each GH Actions run takes 3-30 min depending on phase; budget time.
• Phase status: always say "we are in Phase X; next deliverable is Y; fallback to Option A is Z if blocker hits."
• Honesty: acknowledge when training-time familiarity may be stale; recommend re-verification.

When user is excited about a new technique: "great — let's add it after Phase X stabilizes. Read RESEARCH_FINDINGS.md to see if it's already in the Option B roadmap."

End State Definition

v1.0 (Phase 3 complete)

• Public GitHub repo quantrank exists
• Weekly GitHub Actions cron runs successfully
• S&P 500 universe ingested with ≥10 years of data
• All 8 pillars computed for every stock
• Composite StockRank (0-100) per stock
• Fair Price ensemble (Median + Max) per stock
• JSON files in public/data/ valid against schema
• Vercel-deployed Next.js site shows ranking table + detail page
• README has disclaimer + architecture diagram + methodology link
• Mobile responsive, Lighthouse >85
• Tag v1.0 on GitHub

v2.0 (Phase 8 complete) — MAXIMUM FREE TIER

• All v1.0 criteria
• OSAP + JKP + Qlib factor libraries integrated (Phase 4)
• IPCA latent factors (Phase 4)
• LightGBM + Triple-Barrier + Meta-Labeling + Conformal (Phase 5)
• Whisper + 8-K events + Lazy Prices sentiment (Phase 6)
• Student-t HMM + TDA + NCO (Phase 7)
• S&P 1500 universe (Phase 8)
• Backtest report with PBO < 50%, Deflated Sharpe documented
• Tag v2.0 on GitHub
• Honest performance: 3-7% net alpha vs SPY (with wide CI)

After v2.0: Maintenance mode. No further phase additions unless empirically validated alpha gain.