pop-fem-audit/CLAUDE.md

Project Workflow Rules

Keep this file minimal. It is injected into every Claude Code subagent; NEVER put research domain knowledge, theory, coding criteria, or expected results here. Domain material lives in docs/ and is read only when explicitly needed.

Roles

• The main Claude Code session is for discussion, planning, and writing only. All analysis is executed by deterministic scripts.
• Claude Code subagents are used only for engineering support (writing scripts, style checks, reviews) — never as research instruments.

Analysis pipeline (paper-bound work)

• LLM analysis runs via Python scripts calling the Anthropic Messages API: model claude-sonnet-4-6, temperature=0, thinking disabled, Batch API where possible.
• Prompt definition files live in prompts/<task>_v<N>.md and are passed verbatim as the system prompt.
• Every LLM step runs the same definition file twice, then a separate arbitration step reconciles the two outputs ("2 runs + 1 arbitration"). If arbitration output is unexpected, revise the definition file and repeat the whole cycle; never patch results by hand.
• Every execution is archived self-contained under runs/<phase>/<date>-<prompt-version>/: prompt snapshot, raw outputs of both runs, arbitration output, and meta.json (model ID, parameters, timestamps, batch IDs).
• Scripts read the API key from the ANTHROPIC_API_KEY environment variable (.env, gitignored). Never hardcode keys.

Data rules

• data/yearend_hot100_2016_2025.csv is the only hand-placed raw file; everything else in data/ is script-derived.
• Full lyrics are copyrighted: they stay in data/lyrics/ (gitignored) and must never be committed or reproduced in full anywhere in the repo.

Documents

• results/ holds final arbitrated tables (what the paper cites); runs/ holds raw audit records. The paper cites results/ only.
• Any change to a definition file, the codebook, or the plan is recorded in docs/decision_log.md with date and reason.