docs: add the MiniMax handoff brief for DN inbox tasks 6-11
Constrains the implementer away from the two failure modes that have already bitten this work: writing to production PocketBase, and guessing when the plan does not match the code. Also states plainly that a wrong product match costs money and a block does not, since Task 6 is where that trade-off lives. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
DEls
parent
b4b61083b0
commit
ba6ce2bf2e
1 changed files with 144 additions and 0 deletions
144
docs/handoffs/2026-09-17-minimax-dn-tasks-6-11.md
Normal file
144
docs/handoffs/2026-09-17-minimax-dn-tasks-6-11.md
Normal file
|
|
@ -0,0 +1,144 @@
|
|||
# Handoff brief — MiniMax: delivery note inbox Tasks 6–11
|
||||
|
||||
Paste this whole file as your instructions. Everything you need is either here or in the plan it names.
|
||||
|
||||
---
|
||||
|
||||
## Your job
|
||||
|
||||
Implement **Tasks 6, 7, 8, 9, 10 and 11 — and only those** from:
|
||||
|
||||
```
|
||||
docs/superpowers/plans/2026-09-17-dn-inbox-corrections.md
|
||||
```
|
||||
|
||||
Read that plan first. It contains **complete, final code for every step.** It was written after auditing 34 real documents and the live database. Its code blocks are meant to be typed in as given.
|
||||
|
||||
Do **not** do Task 1 (manual n8n UI work), Task 12 (a human does the ledger audit), or Tasks 2–5 (already done).
|
||||
|
||||
## Starting state
|
||||
|
||||
- Branch: `fix/dn-inbox-corrections` — **stay on it, do not create another.**
|
||||
- Starting commit: `b4b6108`
|
||||
- Baseline: **882 tests passing, `npm run typecheck` clean.** If either is broken before you start, stop and say so.
|
||||
- Tasks 2–5 are already merged into this branch. `src/lib/dn-pipeline/` currently contains: `types.ts`, `segment.ts`, `checks.ts`, `extract.ts`, `split.ts`, `promote.ts`, `run.ts` and their tests. `match-po-item.ts` and `aliases.ts` do **not** exist yet — you create them in Tasks 6 and 7.
|
||||
|
||||
---
|
||||
|
||||
## HARD CONSTRAINT 1 — never write to PocketBase
|
||||
|
||||
The PocketBase instance is **production, holding real supplier payment data.**
|
||||
|
||||
Tasks 7, 10 and 11 tell you to create `scripts/pb-*.py` migration scripts.
|
||||
|
||||
> **CREATE THE SCRIPT FILES. DO NOT RUN THEM.**
|
||||
|
||||
Skip every step that runs one (Task 7 Step 2, Task 10's "run it twice", Task 11 Step 1b). Note in your report that you skipped them. A human runs all migrations after reviewing them.
|
||||
|
||||
Also forbidden:
|
||||
- any `curl` with `POST`, `PATCH`, `PUT` or `DELETE` against the PocketBase URL
|
||||
- running any existing `scripts/pb-*.py` or `scripts/migrate-*.py`
|
||||
- `npm run dev` and any attempt to exercise the UI against live data
|
||||
|
||||
Read-only `curl -s` GET against PocketBase is allowed if you must inspect a schema. You should not need to.
|
||||
|
||||
**Consequence:** Tasks 7, 10 and 11 add database fields your code then reads. Those fields will not exist while you work, so you cannot run the app end to end. That is expected. Your acceptance gate is the unit tests, not a live run.
|
||||
|
||||
## HARD CONSTRAINT 2 — never improvise
|
||||
|
||||
If a code block in the plan looks wrong to you, **implement it exactly as written and flag it in your report.** Several decisions are deliberate and counter-intuitive:
|
||||
|
||||
- A check returning `passed: null` is **not** a failure. Only `false` blocks a note.
|
||||
- A purchase order line with no unit must **not** block a delivery.
|
||||
- `resolvePoItem` returning `ambiguous` is a **correct, desirable** outcome. Do not "fix" it into a match.
|
||||
- The `allNotesPromoted` gate in `run.ts` is intentionally redundant. Leave it.
|
||||
|
||||
If a plan step quotes code that does not match the real file:
|
||||
|
||||
> **STOP. Do not guess. Leave that step undone and report the exact difference.**
|
||||
|
||||
Guessing is how data gets silently corrupted here. A reported mismatch costs a human two minutes; a wrong guess costs a wrong supplier payment.
|
||||
|
||||
## HARD CONSTRAINT 3 — Task 6 is the one that can cost money
|
||||
|
||||
Task 6 builds the matcher that decides which purchase order line a delivery line refers to — and therefore which **rate** gets applied to real money.
|
||||
|
||||
Two earlier attempts at this produced **wrong matches**:
|
||||
|
||||
| Slip line | Wrongly matched to | Correct answer |
|
||||
| --- | --- | --- |
|
||||
| `U PIPES-600 X 2.5(100D)` | `S&S Pipes-1050 X 2.5(100D)RR` | `IJ PIPES-600 X 2.5(100D)` |
|
||||
| `160x6M KABELFLEX PIPE & COUPLING` | `160mm uPVC Cl 16 Pipe` | `160mm Sleeves Black` |
|
||||
|
||||
A wrong match is **worse than no match**. A block is visible and costs someone two minutes; a wrong match silently pays the wrong amount.
|
||||
|
||||
Task 6's test file contains 15 ground-truth cases plus a test named `never returns a wrong match for any known input`. **Every one must pass.**
|
||||
|
||||
If a case fails, fix the implementation — **never** loosen `WORD_FLOOR` (0.30) or `MARGIN` (0.15) to make it pass. Those numbers were tuned against 23 real descriptions. If you believe one must change, stop and report it instead.
|
||||
|
||||
---
|
||||
|
||||
## Order of work
|
||||
|
||||
Strictly sequential. Task 8 depends on 6 and 7. Do not reorder.
|
||||
|
||||
| Task | What | Gate |
|
||||
| --- | --- | --- |
|
||||
| 6 | `match-po-item.ts` — three-outcome matcher | its 15 test cases pass |
|
||||
| 7 | `aliases.ts` + alias collection script | `aliases.test.ts` passes |
|
||||
| 8 | Wire matcher + aliases through checks, promote, run | full suite passes, `grep -rn "matchPoItem" src/` returns nothing |
|
||||
| 9 | Resolve-item route + board UI | typecheck clean |
|
||||
| 10 | Document type classification | full suite passes |
|
||||
| 11 | `open_pages` — stray page stops blocking | full suite passes |
|
||||
|
||||
## What to run
|
||||
|
||||
Do run these. Run them often.
|
||||
|
||||
```bash
|
||||
npx vitest run src/lib/dn-pipeline/<file>.test.ts # one file
|
||||
npm run test:run # full suite
|
||||
npm run typecheck # must be clean before every commit
|
||||
```
|
||||
|
||||
`npm run typecheck` **must pass before every commit.** If it fails, fix the cause — do not commit and do not comment out the failing code.
|
||||
|
||||
## Commits
|
||||
|
||||
Commit per task, using the exact message from that task's commit step. End each commit message with:
|
||||
|
||||
```
|
||||
Co-Authored-By: MiniMax <noreply@minimax.io>
|
||||
```
|
||||
|
||||
Do not squash, do not amend, do not rebase, do not push.
|
||||
|
||||
## Known trap, already hit once
|
||||
|
||||
Tasks 10 adds **required** fields to `PageRead` and `NoteSegment`. Every hand-built test fixture in `promote.test.ts`, `run.test.ts` and `segment.test.ts` will then fail typecheck until the new fields are added to them.
|
||||
|
||||
When that happens: add the new fields to those fixtures with values consistent with their siblings. **Change no test logic and no assertions** — fixture completeness only. This is expected and is not a sign you broke something.
|
||||
|
||||
---
|
||||
|
||||
## Report back
|
||||
|
||||
Be specific and honest. A skipped step reported is fine; a skipped step hidden is not.
|
||||
|
||||
1. **Per task:** done or not, and the commit SHA.
|
||||
2. **Tests:** final `npm run test:run` count, and the names of every test you added.
|
||||
3. **Typecheck:** clean or not.
|
||||
4. **Skipped steps** and why (the PocketBase ones are expected — list them anyway).
|
||||
5. **Mismatches:** any place the plan's quoted code differed from the real file, with the exact difference. Quote both versions.
|
||||
6. **Migration scripts created but not run** — list the file paths.
|
||||
7. **Anything in the plan you think is wrong.** Do not act on it. Just say so.
|
||||
8. **Task 6 specifically:** confirm the `never returns a wrong match for any known input` test passes, and state whether you changed `WORD_FLOOR` or `MARGIN` (you should not have).
|
||||
|
||||
## What happens next
|
||||
|
||||
A human then:
|
||||
- reviews every diff against the live database
|
||||
- reads and dry-runs your migration scripts, then applies them
|
||||
- runs Task 12: re-processes all 34 batches and audits every delivery line item for wrong product links
|
||||
|
||||
So: correctness and honest reporting matter far more than speed or completeness. If you finish four of the six tasks properly, that is a better outcome than six done loosely.
|
||||
Loading…
Reference in a new issue