# RedditBot — agent instructions

## Test-first workflow (MANDATORY)

This applies to every code-changing task in this repo. Sub-agents inherit it.

### 1. Before implementation — establish the baseline

Run the full test suite **first**:

```
npm test
```

Note the count of passing / failing tests. Do not start implementing until you have this baseline. If something is already failing, surface it to the user before touching it — don't silently inherit pre-existing failures into your scope.

### 2. During implementation — update tests alongside code

- When you change a function's behavior, update or add the test for it in the same change.
- When you change a function's signature, fix the call sites in tests in the same change.
- When you introduce a new module, add a test for it in `tests/<name>.test.ts`.
- If a test fails because the *test* is wrong (stale assertion, ESM mocking issue, real env leaking in), fix the test. If it fails because the *code* is wrong, fix the code.
- Never delete a test to make it pass. Either fix the assertion to reflect intended behavior, or fix the code.

### 3. Before reporting done — confirm green

Re-run the full suite:

```
npm test
npx tsc --noEmit
```

**Both must be clean before you say the task is done.** If either is failing, either fix it or explicitly call out the regression in your final message — do not report success and leave a broken suite.

If tests pass count went down vs. the baseline you took in step 1, that is a regression. Treat it as a blocker.

### Why this matters

The test suite is the only automated safety net for this project (no CI yet, no integration tests). Drift here means real bugs ship. Past incident: a refactor went out with 129 pre-existing test failures undetected — they had been broken for weeks because nobody re-ran the suite.

## Project notes for agents

- Runtime: TypeScript with `module: NodeNext`. Imports use `.js` extensions even for `.ts` files.
- Tests: vitest, `globals: false` so `describe`/`it`/`expect`/`beforeEach`/`afterEach` must be imported explicitly.
- The OpenRouter, MediaService, ProcessorService, RateLimiter, and MonitorService constructors accept optional last parameters for test-injectable dependencies (mock clients, temp dirs, fake fetchers, shortened timing). Use them rather than `vi.mock()` of ESM modules — the namespace-mocking pattern fails under NodeNext.
- Shadow-DOM scraping for `chat.reddit.com` lives in `src/services/chat/scrapers.ts` as typed `page.evaluate` functions. The `myUsername` parameter is threaded through from `config.reddit.username`.
- Some `.env` vars (notably `OPENROUTER_API_KEY`) are auto-loaded via `dotenv.config()` at module import. Tests that touch `loadConfig` must snapshot+clear these in `beforeEach` and restore in `afterEach`.