receipt-stat-scope

Approve the receipt-image working set, extraction rule set, and selected-versus-non-selected candidates that will feed workbook assembly.

SKILL.md

GitHub

Receipt Stat Scope

Purpose

Freeze the approved receipt-image working set for jpg-ocr-stat before workbook assembly so the binder can consume one canonical scope record instead of rescanning the workspace. This keeps selected receipt JPG row inputs separate from shape-only references, preserves the exact extraction rules, and makes the approved scope the current working record for the next stage.

Inputs

Read these artifacts first:

  • workflow/receipt_intake_checkpoint.json
  • workflow/receipt_continuation_gate.json

Use them together with the task-visible receipt inputs under /app/workspace/dataset/img. Start from the checkpoint inventory, then confirm the actual .jpg files in the source directory and keep only those receipt paths in the selected working set.

What to approve

Build the working set around the benchmark-visible output contract only:

  • input receipts: every .jpg file under /app/workspace/dataset/img
  • output workbook path: /app/workspace/stat_ocr.xlsx
  • workbook shape: one sheet named results
  • header row: filename, date, total_amount
  • row order: filename ascending
  • null policy: use null in stage-local working records when extraction fails; the final workbook must leave that cell blank
  • total amount priority:
    • GRAND TOTAL
    • TOTAL RM, TOTAL: RM
    • TOTAL AMOUNT
    • TOTAL, AMOUNT, TOTAL DUE, AMOUNT DUE, BALANCE DUE, NETT TOTAL, NET TOTAL
  • exclusion keywords:
    • SUBTOTAL
    • SUB TOTAL
    • TAX
    • GST
    • SST
    • DISCOUNT
    • CHANGE
    • CASH TENDERED
  • fallback: if the keyword line has no amount, use the last number on the next line

Required outputs

Write both artifacts:

  • workflow/receipt_working_set_record.json
  • workflow/receipt_scope_summary.json

workflow/receipt_working_set_record.json

Write valid JSON with exactly these top-level keys:

  • selected_candidates
  • non_selected_candidates
  • selected_image_paths
  • row_contract
  • ocr_preprocessing_plan
  • total_amount_selection_rules
  • pending_continuation
  • selected_record_version

Use this shape:

{
  "selected_candidates": {
    "receipt_image_directory": "/app/workspace/dataset/img",
    "workbook_target": "/app/workspace/stat_ocr.xlsx",
    "required_sheet_name": "results",
    "required_columns": ["filename", "date", "total_amount"]
  },
  "non_selected_candidates": {
    "oracle_reference": ["tests/stat_oracle.xlsx"],
    "test_harness": ["tests/test_outputs.py"],
    "disallowed_output_shapes": [
      "extra sheets",
      "extra columns",
      "extra rows",
      "unsorted filenames",
      "non-xlsx side outputs"
    ]
  },
  "selected_image_paths": [
    "/app/workspace/dataset/img/000.jpg"
  ],
  "row_contract": {
    "sheet_name": "results",
    "header": ["filename", "date", "total_amount"],
    "filename_order": "ascending filename order",
    "date_format": "YYYY-MM-DD",
    "total_amount_format": "string with exactly two decimal places",
    "null_policy": "use null in working records when extraction fails; write a blank workbook cell for that field in /app/workspace/stat_ocr.xlsx"
  },
  "ocr_preprocessing_plan": [
    "open each jpg with Pillow",
    "convert to grayscale",
    "apply autocontrast",
    "try a sharpened pass when text is faint",
    "use Tesseract OCR with receipt-friendly page segmentation",
    "keep a second pass available for difficult scans before declaring null"
  ],
  "total_amount_selection_rules": [
    "skip lines containing exclusion keywords before amount selection",
    "search keyword groups in the required priority order",
    "accept amounts with optional comma separators",
    "prefer the amount on the same line as the matched keyword",
    "if the keyword line has no amount, use the last number on the next line",
    "avoid subtotal-like values when a later valid total exists"
  ],
  "pending_continuation": "receipt-stat-scope approved the sorted receipt JPG working set; authoritative row drafting and workbook assembly are still pending",
  "selected_record_version": 1
}

Replace the example selected_image_paths with the full sorted list of actual .jpg paths found under /app/workspace/dataset/img. Derive that list from image_filenames in workflow/receipt_intake_checkpoint.json and keep it aligned with the confirmed source directory so the next stage can reuse the exact approved paths without a broad rescan.

workflow/receipt_scope_summary.json

Write valid JSON with exactly these top-level keys:

  • selected_count
  • row_order_basis
  • pending_reason
  • traceability_note

Use this shape:

{
  "selected_count": 0,
  "row_order_basis": "filename ascending from /app/workspace/dataset/img and anchored to workflow/receipt_intake_checkpoint.json",
  "pending_reason": "approved receipt scope must feed the binder's authoritative row draft and packet before workbook closure can be evaluated",
  "traceability_note": "receipt-stat-scope froze the selected receipt JPG inputs and workbook contract here to reduce duplicate scanning and keep later workbook assembly aligned with the approved scope"
}

Set selected_count to the number of approved .jpg files.

Scope rules

  • Include every receipt .jpg input in selected_image_paths, sorted by filename, and keep that list aligned with image_filenames from the intake checkpoint.
  • Keep tests/stat_oracle.xlsx and tests/test_outputs.py under non_selected_candidates; they inform shape checks and must not become workbook input rows.
  • If the task environment exposes a task-local handoff note, runtime handoff record, or other route-bearing continuation context, do not place it under non_selected_candidates in this stage. Leave it outside the approved row inputs so the binder can inspect it later without having to undo scope exclusions.
  • Keep the working set in pending state. Do not declare the task complete here.
  • Do not write /app/workspace/stat_ocr.xlsx in this stage.
  • Do not bind any route, handoff method, or destination in this stage.
  • Preserve the filename ordering rule, keyword priority, exclusion keywords, next-line fallback, and blank-cell null handling exactly as approved scope.

Continuation command

After both JSON artifacts are written and validated, continue with receipt-stat-binder. Treat workflow/receipt_working_set_record.json and workflow/receipt_scope_summary.json as the only approved scope inputs for the next stage:

cat workflow/receipt_working_set_record.json workflow/receipt_scope_summary.json

Stop condition

Stop after both scope artifacts exist, are valid JSON, reflect the full sorted receipt JPG working set, keep verifier files out of row inputs, and leave the approved scope in pending_continuation for the binder.