Skip to content

CLAUDE.md

Latest commit

 

History

History
120 lines (100 loc) · 7.32 KB

CLAUDE.md

File metadata and controls

120 lines (100 loc) · 7.32 KB
Raw

EROTICA — repo guidance

Python package erotica/ (clustering, isochrone, dynamics, kinematics, photometry, structure, analysis) plus the full source of the NGC 6383 A&A paper (aa52082-24) under data/test/NGC6383/. Remote: notluquis/erotica, working branch dev. (Renamed COSMIC→EROTICA 2026-07-21 — package, import, PyPI dist, GitHub repo, and the working dir /Users/notluquis/COSMIC → /Users/notluquis/erotica.)

Pipeline/status/roadmap for all papers live in the hub repo (attached via --add-dir): ~/phd/PIPELINE.md (state), ~/phd/ROADMAP.md (plan), ~/phd/erotica-package.md (package backlog), ~/phd/papers/PXX.md (dossiers). Keep those current; do not spawn TODO files here.

Before writing scientific code here, read these two

  • ~/phd/methodology.md PART K — the execution craft. The failure modes that have actually produced wrong numbers in this repo, each with its case: generators that produce something other than their label, experiments degenerate with their own control, tests that cannot fail, and the verification order (generator → estimator → interpretation). Every generator needs a parameter-free special case with a known closed form, and that case must be a test. Re-apply each bug you fix and confirm the suite goes red — a test you have not seen fail is a hypothesis.
  • ~/phd/model-landscape.md — per-module map of the published model alternatives, marked SURVEYED / PARTIAL / UNSURVEYED. Read the row for the module you are touching. An UNSURVEYED row is a recorded liability, not a neutral state; when you make a modelling choice, update the row and name what you rejected.

Nested guidance — these load automatically when you work in the directory

file covers
erotica/analysis/CLAUDE.md prior/likelihood conventions, the traps that already bit (King's b, R_t, the γ bias), how to add a profile
tests/CLAUDE.md what an oracle is, the four ways tests here failed to bite, mutation before claiming a test works
tools/validation/CLAUDE.md one-off experiments become paper numbers — docstring, controls, JSON sidecar, live queries
docs/design-notes/CLAUDE.md append-only about mistakes; citation, verified-vs-inferred, the falsifier

Design decisions are logged append-only in docs/design-notes/decisions.md — record the number that was wrong and why, not only the fix. A struck-through row in a results table is worth more than the row that replaced it.

Landmines

  • ~30 files hardcode /Users/notluquis/erotica/... (paper figure regen). They were rewritten during the 2026-07-21 dir move; if this dir moves again, rewrite them in the same pass or they all break.

  • Paper source of truth: data/test/NGC6383/comments_paper/submission_package/clean_source/aanda.tex. An older working copy sits at data/test/NGC6383/Tex_File/aanda.tex — don't edit that one by mistake. (The legacy Tex_File/NGC6383_manuscript.tex was retired in the analysis-layer migration; state tagged ngc6383-aanda-resubmission.)

  • data/test/NGC6383/ is ~3.1 GB and committed to the repo (paper repro artifacts, hardcoded paths). Reproducibility tag: ngc6383-aanda-resubmission.

  • pre-commit is broken here: the nbstripout hook chokes on the large working-tree stash and can revert unstaged changes into a .cache/pre-commit/ patch. Commit with git commit --no-verify until the hook is fixed (release-blocker: fix the pre-commit config — see ~/phd/erotica-package.md).

  • Read the Docs slug migration is pending. Done — the slug is erotica. This entry claimed the slug was "still cosmic-clusters as of 2026-08-02 (verified against the RTD API)" and that the README's erotica.readthedocs.io links "404 until it lands". Both halves are now false. Measured directly 2026-08-04:

    URL status
    erotica.readthedocs.io/en/latest/ 200 — serving the live docs
    cosmic-clusters.readthedocs.io/en/latest/ 404 — the old slug is gone

    So the README links are correct and load; do not add warnings back. Keep the old slug out of new links entirely — it resolves to nothing.

  • PyPI: erotica is published. Verified 2026-08-04 via pypi.org/pypi/erotica/json → HTTP 200, version 0.1.0, artefacts erotica-0.1.0.tar.gz and erotica-0.1.0-py3-none-any.whl. The old dist name cosmic-cluster-analysis returns 404 and was never published. pip install erotica works, so any doc still saying "install from source (current)" is stale. ⚠ Check pypi.org/pypi/<name>/json, never pypi.org/project/<name>/ — the latter returns HTTP 200 with a Cloudflare challenge page whether or not the project exists, which is how you conclude a name is free when it is taken, or taken when it is free.

  • CDS accepts ASCII and FITS only — no HDF5, no parquet. A&A mandates data deposit, usually at CDS, so any table destined for the NGC 6383 paper must be produced in an accepted format. Verified 2026-08-02. This constrains the deposit pipeline, not just the final export.

  • A&A does have a software track: "Numerical methods and codes" (Sect. 15). It imposes no README or code-availability requirement, unlike JOSS. Write to JOSS's bar and A&A is satisfied automatically; the reverse is not true — in particular JOSS requires an AI-usage disclosure naming tools, versions, scope and human review, and calls non-disclosure "an ethical breach", whereas A&A's 18 June 2026 statement permits undisclosed AI use for language, coding and search under human oversight.

Data traps (respect in any catalog work)

  • comments_paper/_legacy/rerun_2026-05/members_DIFFERENT_RUN_DO_NOT_USE.csv = a different run (177 not 254 members, corrupted float source_ids). Never use.
  • At 60/70′ the generic HDBSCAN max_members branch is NOT the NGC branch — use the dual-label exports.
  • Notebook 25′ figures are stale producers; comments_paper/members.csv-style short sweeps ≠ the paper reference run.

CodeGraph — cableado 2026-08-17, con una trampa medida

codegraph init indexa este repo en 445 ms (314 ficheros, 5110 nodos, 10963 aristas) y salta los 3.1 GB de data/. Está registrado como servidor MCP en .mcp.json y sus permisos en .claude/settings.json.

Lo que sirve: codegraph impact <simbolo> y codegraph callers <simbolo> resuelven bien — impact search_pseudoprobability devuelve 49 símbolos con los tests reales de tests/test_clustering.py, que es exactamente la pregunta de la lección 34 del CLAUDE.md global ("correr sólo el test que tocaste no es correr los tests").

⚠ codegraph affected NO sirve en este repo, y falla en las dos direcciones. Su clasificador de "test file" es por ruta, y el paper vive en data/**test**/NGC6383/. Medido sobre erotica/analysis/provenance.py:
tests reales que reporta 0 — omite tests/test_provenance.py, que existe y menciona provenance 32 veces
falsos positivos 14 — scripts de regeneración de figuras, COSMIC_aux.py, gate.py

El grafo sí conoce el fichero (codegraph callers write_metadata lo encuentra en tests/test_provenance.py:292), así que el defecto está en el clasificador, no en el índice. Usa callers/impact y no affected hasta que el paper salga de data/test/ (paso 5 de ARCHITECTURE.md en el hub).