# 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.