# AGENTS.md — Root Directives

This repo has two operational areas with their own `AGENTS.md`:

- `analysis/AGENTS.md` — how to write and run experiments
- `docs/AGENTS.md` — how to document findings, plans, and checkpoints

## The Core Contract

Every experiment has two sides, always paired:

```
analysis/{NNN}-{name}/            ← code, scripts, outputs
docs/runs/{YYYY-MM}/{NN}-{name}/  ← plans, findings, checkpoints
```

Never create one without the other.

## Agent Workflow

1. **Ask first.** Before starting any experiment, clarify with the human: which org(s)? what date range? what's the specific question?
2. **Read the latest checkpoint and the plan doc.** Before starting, ask the human: "Should I read any prior findings before running this analysis?" and give them options — e.g., specific finding filenames you can see in the folder, or "none, start fresh". Do not read prior findings unless the human explicitly selects them.
3. **Plan before code.** Write a plan doc in `docs/runs/.../plan/` and get approval.
4. **Code the experiment.** Follow `analysis/AGENTS.md`.
5. **Document results.** Follow `docs/AGENTS.md`. Write findings immediately — don't accumulate undocumented results.
6. **Checkpoint at stopping points.** End of investigation thread, end of day, before switching context.

## Multiple Experiments Per Day

Normal and expected. Each script run that produces insight gets a finding doc. Checkpoints can batch across findings.

```
Morning:   Plan → code script → run → document finding
Afternoon: Add script to same experiment → run → document finding
           OR create new experiment if the question is genuinely different
Evening:   Write checkpoint summarizing the day
```

## Timestamps

**All dates and times in docs are UTC.** Format: `YYYY-MM-DD HH:MM UTC`. No local timezones, no ambiguous dates. Every finding and checkpoint has a `Created` timestamp; findings also have `Updated` when edited. See `docs/AGENTS.md` for the full metadata spec.

## Environment Rules

- **Always `uv run`** for Python. Never bare `python` or `pip`.
- **Local Postgres** for all data access. Start with `/start-local-db`. DSN lives in `.local.env`.
- **Sync prod data** before new experiments if needed: `/sync-prod-to-local`.
- **Conventional commits** enforced by hook. No Anthropic/Claude attribution in commit messages.
