Files

T

Ty 120e0be871 docs(m3): settle deterministic title and Call 2 design

Encode the recovered per-leaf title/short-description rule and the Call 2
input set into the point of record.

- REQUIREMENTS.md: METADATA-55 now produces the description only; METADATA-60
  carries the ruled input set; METADATA-80 is the deterministic title; new
  METADATA-81 is the deterministic spec-line short description; METADATA-85
  selects the patterns; REVIEW-15 declares the primary before Call 2;
  PUBLISH-55 carries an explicit name+SKU slug.
- CONTENT-WOO.md: per-leaf title and short-description catalog, slot order,
  dimension placement, and the Cook Woods provenance.
- PROMPTS.md: Call 2 inputs and output; the deterministic patterns are cited,
  not restated.
- CREATE.md, WOO-API.md, MILESTONES.md, task_breakdown.md updated to match.

Modeled on Cook Woods product-title form; the seven per-leaf prose templates
and Specialty cuts are parked in the M3 breakdown.

2026-09-19 11:36:03 -07:00

6.5 KiB

Raw Blame History

Listing copy and payload intent

Status: SPEC · 2026-09-18. Owns how listing copy is produced and the intent of the create payload. The wire shape is docs/contracts/WOO-API.md; the create sequence is docs/contracts/API.md; prompts are docs/contracts/PROMPTS.md.

Requirements impact

Requirement	Impact on this design
REVIEW-10, REVIEW-15, REVIEW-40, REVIEW-50	required prose, primary category, editability, limits
METADATA-55, METADATA-60, METADATA-65, METADATA-66	Call 2, inputs, dimension safety, logging
METADATA-70, METADATA-75, METADATA-80, METADATA-81, METADATA-85, METADATA-90, METADATA-95, METADATA-110	deterministic copy, fallback, pattern selection, fact block, overlay exclusion, control
PUBLISH-5, PUBLISH-10, PUBLISH-15, PUBLISH-20, PUBLISH-25, PUBLISH-30, PUBLISH-31, PUBLISH-40, PUBLISH-45, PUBLISH-50, PUBLISH-55, PUBLISH-60	payload and create outcomes
SETTINGS-30, SETTINGS-65	brand voice and geo context; create status
METADATA-10, METADATA-15, METADATA-30	categories, attributes, tags on the payload

1. Copy sources

Three fields, three sources (REVIEW-10):

name — assembled deterministically by the server from the primary wood category's title pattern and the dimension fact block (METADATA-80). The model does not write it.
short_description — assembled deterministically as a spec line from the primary wood category's short-description pattern (METADATA-81). The model does not write it.
description — written by Call 2 when it runs (METADATA-55), from the inputs in METADATA-60; with inference off the server produces it (METADATA-70).

The primary wood category selects the title pattern, the short-description pattern, and the Call 2 prompt (METADATA-85, REVIEW-15). The owner can edit any field until create (REVIEW-40), and every field respects the limits in docs/contracts/WOO-API.md §9 (REVIEW-50).

The model writes the long description only, from the fact block; it never invents a dimension (METADATA-65, METADATA-90). The dimension-overlay image is never sent (METADATA-95). The Generate text control appears only when content generation is enabled and the endpoint is reachable (METADATA-110); a failed generation never blocks create (METADATA-75). Every generation is logged (METADATA-66).

2. Deterministic title and short description

Both patterns are assembled by the server and use only synced taxonomy terms and capture facts (METADATA-80, METADATA-81). Placeholders use {field}; every number comes from the deterministic pipeline, never the model (METADATA-90).

The shape follows the convention a working mill store uses: descriptor-led, dimension-light titles, with the measurements carried separately. See "Provenance" below.

2.1 Title

Slot order:

[Figure] {species} [Live Edge] {noun} [(dims)]

Figure leads as a Title-Case adjective and is omitted when the Figure term is plain.
Grade is not used in the title.
Live Edge appears only when the Edge Type term is Live Edge.
There is no separator between slots.
Dimensions ride in the title only for the turning leaves, as a trailing (L x W x T).

Per-leaf patterns:

Leaf	Pattern	Example
Live edge wood	`[Figure] {species} Live Edge Slab`	`Figured Black Walnut Live Edge Slab`
Dimensional wood	`[Figure] {species} [Live Edge] Dimensional`	`Figured Red Oak Dimensional`
Knife blanks	`[Figure] {species} Knife Blank (L x W x T)`	`Figured Mirindiba Knife Blank (12 x 6.5 x 1.5 in)`
Bowl blanks	`[Figure] {species} [Live Edge] Bowl Blank (L x W x T)`	`Spalted Cherry Bowl Blank (8 x 8 x 3 in)`
logs and caps	`[Figure] {species} Log Cap`	`Figured Black Walnut Log Cap`
Pen blanks	`[Figure] {species} Pen Blank (L x W x T)`	`Figured Purpleheart Pen Blank (5.5 x 1.1 x 1.1 in)`
Pepper mill blanks	`[Figure] {species} Pepper Mill Blank (L x W x T)`	`Birdseye Olive Pepper Mill Blank (10 x 3.2 x 3 in)`

Specialty cuts has no M3 pattern.

length_ft = floor(length_in / 12), length_in_remainder = length_in mod 12 (1 dp).

2.2 Short description

One spec line, so the measurements appear even when the title omits them:

[Figure] {species} {noun}, {length} x {width} x {thickness}, {bdft} bdft

Leaf	Example
Live edge wood	`Figured Black Walnut Live Edge Slab, 9ft 6in x 24.3in x 1.75in, 18.4 bdft`
Dimensional wood	`Figured Red Oak Dimensional, 8ft 0in x 5.8in x 1.25in, 4.8 bdft`
Pepper mill blanks	`Birdseye Olive Pepper Mill Blank, 10in x 3.2in x 3in, 0.7 bdft`

2.3 Description

The long description is the model's prose when Call 2 runs (METADATA-55); with inference off the server produces it (METADATA-70). The per-leaf prose templates that guide Call 2 are authored with that slice and are not defined here.

2.4 Provenance

The title and short-description form was modeled on the live product titles of Cook Woods (cookwoods.com), captured 2026-09-19. Borrowed: descriptor-led titles; dimension-free titles for slabs, lumber, and caps; parenthetical dimensions only for turning stock; no separator; title case. Not borrowed: their size-class nouns (Mini Slab, Table, Micro Lumber, Long) and pack counts (5 Pack), which have no synced taxonomy term, and their grade adjectives, which are not used in our titles.

3. Payload intent

The exact wire shape is docs/contracts/WOO-API.md. Intent:

Only non-null fields are sent (PUBLISH-55).
The payload carries an explicit slug: the sanitized product name plus the lowercased SKU. Dimensions never appear in the slug (PUBLISH-55).
status comes from woo_create_status (default draft); SLAB-UAT-* always draft (SETTINGS-65, PUBLISH-10).
Categories are the species leaf plus each wood-category leaf; attributes are the five locked attributes by synced term; tags are fig-* and feat-* (METADATA-10, METADATA-15, METADATA-30). Missing attributes or terms are skipped, never created (METADATA-20).
Images are the processed transparent PNGs in photos-ready order, with no cap (PUBLISH-40, PUBLISH-45).
sold_individually is true; each product is one slab (PUBLISH-60).
Create checks the SKU first and blocks on a duplicate (PUBLISH-15); a stale value is a field-level error (PUBLISH-20). Success purges photos and deletes the local row (PUBLISH-25); failure retains photos and logs (PUBLISH-30), including the orphaned-media cleanup note (PUBLISH-31). Published means the create succeeded, not that it is live (PUBLISH-50).

6.5 KiB Raw Blame History