## TL;DR

The dedup report's columns shifted after a schema change. Pin the report columns explicitly and validate the header row.

## Error

```text
dedup report csv columns mismatched
```

## Steps

1. Compare the report header against the expected columns Expected: you see the shift.
2. Pin the column list explicitly in the report code Expected: it is stable.
3. Regenerate the report Expected: columns align.
4. Validate headers on every run Expected: it cannot regress.

## When to use

- Report columns mismatched
- The schema changed

## When not to use

- The schema is stable (then check the report code)
- Columns are dynamic by design (then map by name, not position)

## Tool compatibility

- CSV reports
- Schema changes

## Variant phrasings

### csv columns mismatched

Pin the column list explicitly.

### dedup report columns shifted

Same: validate the header row.

## Why it happens

Positional CSV parsing breaks the moment a column is added. Agents parse by index because it is easy.

## Edge cases

- Parse by header name, not position
- Version your report formats

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_5a4BAC2lfVEkfIYb8Nex2w