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

4.6 KiB

Raw Blame History

Prompts contract

Status: SPEC · 2026-09-18. Owns prompt storage, prompt inputs, and the two inference calls.

Requirements impact

Requirement	Impact on this design
METADATA-5, METADATA-10, METADATA-15, METADATA-30	taxonomy choices and cardinality
METADATA-35, METADATA-40, METADATA-45, METADATA-50	Call 1 inputs, constraints, pre-fill, precedence
METADATA-55, METADATA-60, METADATA-65, METADATA-70	Call 2 output, inputs, dimension safety, fallback
METADATA-75, METADATA-80, METADATA-81, METADATA-85, METADATA-90, METADATA-95	non-blocking, deterministic copy, pattern selection, fact block, overlay exclusion
METADATA-100, METADATA-105, METADATA-110, METADATA-115	feat mapping, prompt storage, button, failure
METADATA-66	generation logging
SETTINGS-30	brand voice and geo context
REVIEW-40, REVIEW-50	editability and field limits

1. Storage and revisions

Prompts live in the database, not in text files, with all revisions retained. Tables are in docs/contracts/DATA-MODEL.md §7. No prompt files ship with the application; the database is the only prompt source.
Each call reads the active revision fresh.
Editing a prompt creates a new revision; history is never overwritten.
Every generation is logged with its inputs, the request/response when a model was used, and the final stored content.

2. Call 1 — vision classification

When. Runs automatically after a calibrated draft uploads only when inference_enabled is true; also on demand or retry. With inference off it is skipped and the fields are filled by hand.

Inputs.

The clean processed photos at 1024 px long edge or less.
The synced taxonomy: species leaves, Edge Type, Figure, Grade, Thickness, Moisture terms, each with its Woo id. These are the only legal choices.
User metadata: SKU, length, thickness.

Constraints.

The model may only choose values from the supplied synced lists; it never invents categories or terms.
Free-text observations (character, inclusions, voids, checks) are mapped to existing synced feat-* tags only; Woo is authoritative for those tags.

Result fields. species_id + species_confidence; wood_category_ids; edge_type_term_id; figure_term_ids + figure_confidence; grade_term_id + grade_confidence; character, inclusions, voids, checks. Grade, edge, thickness, and moisture are singular.

Pre-fill. At or above the threshold (default 0.7) the field is pre-filled and remains editable; below it the field stays empty and is not shown as a low-confidence guess. Typed values always win. Call 1 is assist-only and never gates publish. A runtime failure is classified recoverable or unrecoverable for the owner.

3. Call 2 — content prose

When. User-triggered only, via the Generate text control; never automatic. The control appears only when content generation is enabled and the endpoint is reachable.

Inputs.

The clean processed photos.
The metadata confirmed or changed in review, including the primary and secondary wood categories and the parent-category path.
The literal dimension fact block, exact strings for species, figure term, length, thickness, average width, width min–max, and board feet; no length-by-width-by-thickness rectangle assumption.
Brand voice and geo context.

No provider thread id is used, and Call 1's raw prompt and result are not sent (METADATA-60).

Constraints.

The model writes prose only and never invents or alters a dimension; every number comes from the fact block (METADATA-65).
The dimension-overlay image is never sent (METADATA-95).

Output. The long description prose. The server assembles name and short_description (METADATA-55, METADATA-80, METADATA-81). The primary wood category selects the specialized prompt (METADATA-85). The owner can edit the result (REVIEW-40).

4. Fallback and templates

With inference off, the server assembles the name and short description and produces the description so create never lacks prose (METADATA-70).
The deterministic title and short-description patterns live in docs/contracts/CONTENT-WOO.md (METADATA-80, METADATA-81).
The primary wood category selects the specialized Call 2 prompt (METADATA-85).
All generated text stays within the field limits in docs/contracts/WOO-API.md §9 (REVIEW-50).

5. Prompt management

The active Call 1 and Call 2 revisions are editable; saving creates a new revision.
A revision identifies its content, author, and timestamp; inference_log records the revision used for each call.

4.6 KiB Raw Blame History Unescape Escape