Refine product review prompt flow

pm/tasks.org

@@ -371,29 +371,52 @@
 Clearly show current state separate from proposed future state.
 ** acceptance criteria
 1. Display position in review queue, e.g., (1/22)
-2. Add short help text header to the review item explaining that the action resolves the current observed product group
-3. color-code outputs based on info, prompt/menu, warning
+2. Display compact header with observed_product under review, queue position, and canonical decision, e.g.: "Resolve [n] observed product group [name]  and associated items to canonical_name [name]? (\n [n] matched items)"
+3. color-code outputs based on info, input/prompt, warning/error
    1. color action menu/requests for input differently from display text; do not color individual options separately
+   2. "no canonical_name suggestions found" is informational, not a warning/error.
 4. update action menu `[x]exclude` to `e[x]clude`
 5. on each review item, display a list of all matched items to be linked, sorted by descending date:
    1. YYYY-mm-dd, price, raw item name, normalized item name, upc, retailer
    2. image URL, if exists
+   3. Sample:
 6. on each review item, suggest (but do not auto-apply) up to 3 likely existing canonicals using determinstic rules, e.g:
    1. exact normalized name match
    2. prefix/contains match on canonical name
    3. exact UPC
-- reinforce project terminology such as raw_name, observed_name, canonical_name
-  
+7. Sample Entry:
+#+begin_comment
+Review 7/22: Resolve observed_product MIXED PEPPER to canonical_name [__]?
+2 matched items:
+ [1] 2026-03-12 | 7.49 | MIXED PEPPER 6-PACK | MIXED PEPPER | [upc] | costco | [img_url]
+ [2] [YYYY-mm-dd] | [price] | [raw_name] | [observed_name] | [upc] | [retailer] | [img_url]
+2 canonical suggestions found:
+ [1] BELL PEPPERS, PRODUCE
+ [2] PEPPER, SPICES
+- reinforce project terminology such as raw_name, observed_name, canonical_name   
+#+end_comment
+8. When link is selected, users should be able to select the number of the item in the list, e.g.:
+#+begin_comment
+Select the canonical_name to associate [n] items with:
+  [1] GRB GRADU PCH PUF1. | gcan_01b0d623aa02
+  [2] BTB CHICKEN         | gcan_0201f0feb749
+  [3] LIME                | gcan_02074d9e7359
+#+end_comment
+9. Add confirmation to link selection with instructions, "[n] [observed_name] and future observed_name matches will be associated with [canonical_name], is this ok?
+     actions: [Y]es  [n]o  [b]ack  [s]kip  [q]uit
 ** evidence
-- commit:
-- tests: `./venv/bin/python -m unittest discover -s tests`; `./venv/bin/python review_products.py --help`; verified review prompt now shows queue position, matched item history, image URLs when present, and deterministic canonical suggestions
+- commit: `7b8141c`, `de74218`
+- tests: `./venv/bin/python -m unittest discover -s tests`; `./venv/bin/python -m unittest tests.test_review_workflow tests.test_purchases`; `./venv/bin/python review_products.py --help`; verified compact review header, numbered matched-item display, informational no-suggestion state, numbered canonical selection, and confirmation flow
 - date: 2026-03-17
 
 ** notes
-- The big win here was clarifying terminology in the prompt itself: the reviewer is resolving one observed product group to a canonical_name, not linking raw rows to each other.
-- Showing the full matched-item list by descending date made the review context much more legible than the old compact summary fields.
-- Deterministic suggestions help, but they are intentionally conservative and shallow; this improves reviewer speed without pretending to solve product matching automatically.
+- The key improvement was shifting the prompt from system metadata to reviewer intent: one observed_product, its matched retailer rows, and one canonical_name decision.
+- Numbered canonical selection plus confirmation worked better than free-text id entry and should reduce accidental links.
+- Deterministic suggestions remain intentionally conservative; they speed up common cases, but unresolved items still depend on human review by design.
 
+
+- resolve observed product group (group id)
+  to canonical name: 
 * [ ] t1.10: add optional llm-assisted suggestion workflow for unresolved products (2-4 commits)
 
 ** acceptance criteria