Note

    catalog-review-workflow

    Standard operating pattern for numbered review boards, collaborative catalog cleanup, and audit-ba...

    Document Metadata

    • title: Catalog Review Workflow
    • description: Standard operating pattern for numbered review boards, collaborative catalog cleanup, and audit-backed apply and verify passes
    • status: evolving
    • lastUpdated: "2026-04-10 07:37 ET (America/New_York)"
    • owner: Product/Engineering

    Catalog Review Workflow Use this workflow for catalog optimization where human vi

    Catalog Review Workflow

    Use this workflow for catalog optimization where human visual review should drive the final decision instead of pure automation.

    This repo uses the pattern for work like:

    • color cleanup
    • orientation cleanup
    • subject or theme assignment review
    • missing-attribute review
    • later featured-image and image-normalization review

    Standard Loop

    1. Open a numbered project doc for the catalog-review stream.
    2. Define the review target and the source or bucket rules.
    3. Generate numbered JPG review boards.
    4. Optionally generate a combined PDF bundle for markup convenience.
    5. Collect numbered feedback.
    6. Convert the feedback into a bounded apply pass.
    7. Verify the touched records.
    8. Record checkpoints plus audit artifacts in the project doc, ROADMAP.md, and CHANGELOG.md.
    9. Delete the temporary review packet when the session is complete, unless the user explicitly wants it kept.

    Standard Artifacts

    Every catalog-review run should produce:

    • numbered JPG pages
    • optional combined PDF bundle
    • manifest.json
    • manifest.csv
    • index.md

    Artifact locations in this repo:

    • durable review-board guidance and templates: docs/evidence/templates/catalog-review/
    • preserved review packets: the owning project's evidence directory, typically docs/evidence/active/<project>/review-packets/<run-name>/ or docs/evidence/archive/<project>/review-packets/<run-name>/
    • audit and verification artifacts: the owning project's evidence directory under docs/evidence/active/ or docs/evidence/archive/

    The manifest is the source of truth for later apply and verify work.

    Human Feedback Contract

    • numbered correction notes in chat or markdown are authoritative
    • annotated PDFs are useful supporting context, but not the source of truth
    • if the numbered notes and the PDF markup disagree, resolve the discrepancy explicitly before applying changes

    Project Doc Expectations

    Catalog-review project docs should stay lightweight and capture:

    • review target
    • source or bucket definition
    • generated board packet location
    • feedback packet reviewed
    • apply audit paths
    • verification audit paths
    • live counts or outcome summaries
    • next checkpoint targets

    Use the generic numbered project template under docs/PROJECTS/_templates/ for the project doc itself. Use docs/evidence/templates/catalog-review/ for review-session-specific scaffolding.

    Cleanup Rule

    Generated review packets are disposable by default even though they now live under the owning project's evidence directory.

    After the apply pass, verification pass, and project-doc checkpoint are complete, Codex should delete the run folder unless the user explicitly asks to keep or archive it.

    Repo-Specific Rules Stay Local

    Do not push repo-specific business rules into the generic workflow.

    Keep rules local to this repo for things like:

    • which collections define color buckets
    • how The New Neutrals relates to color:neutral
    • which subject collections exist
    • how orientation writes map to custom.artwork_orientation versus Shopify-managed shopify.orientation
    • how featured-image and image-role cleanup should be handled later under 1062

    Starter Prompt Examples

    • I want to do some catalog optimization work. Create a review board for all products that do not have a color set.
    • Open a new catalog-review project and generate boards for products missing orientation.
    • Prepare a catalog review packet for the Green collection and include a PDF bundle.
    • Apply the numbered catalog review corrections and verify the touched products.

    Provenance