# Starter contract: unstructured → structured extraction (backlog #18)

Pre-filled from `templates/requirement.md`. Adjust the bracketed parts to your chosen input; everything else is ready.

> **On the board:** this is **OODLE-201** on the mock Jira board. Best Wave-1 opening: connect the `oodle-jira` MCP and say *"grab OODLE-201 and grill me"*. Then compare what you froze against this contract.

## WHO

- User: an Oodle analyst/engineer who today parses fields out of unstructured text by hand (Russell's workflow).
- Situation: a folder of sanitised, approved text blocks (letters, notes, descriptions) with consistent-ish content but no structure.
- Task they are trying to complete: get named fields into a CSV they can use downstream.

## WHAT

- Required behaviour (not implementation): given a folder of text files, produce one CSV row per file with the agreed field columns; unknown/missing values are marked `MISSING`, never guessed.
- Input: `[folder of ≥10 sanitised text files: prepare before the session]`.
- Output: `extracted.csv` + a one-line-per-file log of what was found vs. missing.

## WHY

- Intent: prove that extraction + a checkable artefact beats hand-parsing.
- Business outcome: hours of manual parsing become minutes, with an audit trail.
- Evidence/source: Russell's interview. He has done exactly this by hand.

## NOT

- Explicit exclusions: no real customer data, sanitised/synthetic inputs only; no writes anywhere but the working folder.
- Protected areas: nothing outside the working folder.
- Agent must never: invent a value for a field it cannot find in the source text.

## DONE

- Acceptance signals that pass or fail: a checker script confirms (1) row count == file count, (2) every non-`MISSING` value appears verbatim (or as an agreed normalisation) in its source file, (3) held-back test file extracts correctly.
- Authoritative verifier: the checker script, your first deterministic eval. Write it (with Claude) before the extractor.

### Scenarios

```gherkin
Scenario: happy path
  Given a text file containing all agreed fields
  When the extraction runs
  Then the CSV row contains each field's value verbatim from the source

Scenario: edge case
  Given a text file missing one agreed field
  When the extraction runs
  Then that cell reads MISSING and the log names the file and field

Scenario: explicit exclusion
  Given a field value that cannot be found in the source text
  When the extraction runs
  Then the agent records MISSING rather than inventing a plausible value
```