universal-learner

name	universal-learner
description	Extracts reusable prompt elements from any input source — SkyyRose dossiers, gpt-image-2 prompts, brand docs, and design templates — into a structured element library aligned with the SkyyRose brand canon and gpt-image-2 output grammar. Supports SKU-aware dossier ingestion, brand-canon validation, human-review diff gating, and manifest export for design-master consumption.

Universal Learner

Version: 2.0 Architecture: classify → domain → extract → tag → brand-validate → score → dedup → diff-gate → write → report Mode: Semi-automatic (diff shown for human approval before any write) Schema contract: references/element-schema.md (shared with design-master — do not drift) Seed corpus output: references/skyyrose-seed-elements.json (produced by the seed ingestion procedure below)

---

Supported Domains

Eight domains, all mapped to the schema domain field:

domain	Sub-categories
fashion_editorial	garment_silhouette, fabric_texture, colorway_descriptor, construction_detail, model_direction, location_set, editorial_lighting
product	product types, materials, photography techniques
portrait	lighting setups, pose, skin tone, expression
interior	room type, furniture, architectural detail
art	art style, medium, special effects
design	layout, typography, graphic effects
video	motion type, transition, temporal style
common	cross-domain photography/composition techniques

fashion_editorial is the primary domain for all SkyyRose inputs. When a source touches multiple domains, emit elements in each domain with their own domain field.

---

Invocation Modes

Mode A — Single prompt or text snippet

/universal-learner learn: [paste full prompt text]

Mode B — SKU dossier ingestion (primary SkyyRose mode)

/universal-learner dossier: br-004

Reads wordpress-theme/skyyrose-flagship/data/dossiers/<slug>.md, parses YAML frontmatter + zone-structured body, extracts and tags elements with SKU provenance.

Mode C — Batch dossier sweep

/universal-learner batch-dossiers

Iterates all 33 SKU entries from the per-collection SOT JSONs at data/collections/*.json (products[].sku), ingests each dossier, runs full pipeline. Produces one combined diff for review before writing.

Mode D — gpt-image-2 prompt extraction

/universal-learner gpt-image-2: [paste prompt text or point to scripts/oai_render/prompt.py]

Parses the BASE_PROCEDURE / COLLECTION_SCENES grammar, assigns grammatical_position to each parsed clause, and emits elements tagged with source_type: "prompt".

Mode E — Brand document ingestion

/universal-learner brand-doc: [file path]

Accepts knowledge-base/seed/from-interview.md, docs/brand/collection-stories.md, or any brand/design-spec markdown. Extracts editorial language, scene vocabulary, and canonical aesthetics as source_type: "brand-doc" elements.

Mode F — Design system / template ingestion

/universal-learner design-system: [file path or pasted content]

Auto-detected when input contains structural keywords: system, framework, workflow, template, module. Stores both extracted elements and the full raw content (in visual_reference) as a design-template record.

Mode G — Seed corpus procedure

/universal-learner seed

Runs batch-dossiers + brand-doc ingestion for knowledge-base/seed/from-interview.md and docs/brand/collection-stories.md as a single founding sweep. Output written to references/skyyrose-seed-elements.json. See "Seed Corpus Procedure" section below.

Mode H — Manifest export

/universal-learner export [--collection <slug>] [--mode <ghost|on-model|flatlay>]

Queries the element library and emits a gpt-image-2 element manifest consumable by design-master. See "Manifest Export" section below.

---

Pipeline — Step by Step

Input
  │
  ▼
Step 0: Source Classification
  │   Determine input type: dossier | prompt | brand-doc | design-system | raw-text
  │   For dossiers: parse YAML frontmatter (sku, name, collection, logo_reference,
  │     reference_image) + zone-structured body sections
  │   For gpt-image-2 mode: detect BASE_PROCEDURE slot labels
  │   Output: { source_type, source_id, collection_hint, raw_sections }
  │
  ▼
Step 1: Domain Classification
  │   Assign primary domain and optional secondary domains.
  │   SkyyRose dossiers → primary: fashion_editorial
  │   Sub-category selection from the 7 fashion_editorial sub-cats:
  │     garment_silhouette, fabric_texture, colorway_descriptor,
  │     construction_detail, model_direction, location_set, editorial_lighting
  │   Output: { primary: "fashion_editorial", secondary: [], sub_categories: [] }
  │
  ▼
Step 2: Element Extraction
  │   Extract all reusable prompt fragments from the source.
  │   Per domain, extract into the schema shape:
  │     element_id, prompt_fragment, grammatical_position, domain
  │   For dossier mode, read zone sections:
  │     • Garment-type lock → subject + material elements
  │     • Branding zones (front-chest / back / sleeves / pocket / collar) →
  │       construction_detail + colorway_descriptor elements
  │     • Negative list → exclusion elements (grammatical_position: "exclusion",
  │       prompt_fragment prefixed with "DO NOT")
  │     • Scene direction → scene + background + lighting elements
  │   For gpt-image-2 mode, map parsed clauses to grammatical_position slots:
  │     subject | presentation | view | lighting | background |
  │     material | fidelity | scene | exclusion
  │   Output: List[partial element records]
  │
  ▼
Step 3: Auto-Tagging
  │   Assign collection_tags using keyword signals:
  │     silver | armor | concrete | thorn | Cinzel → black-rose
  │     crimson | bloodline | grief | beast | gothic → love-hurts
  │     gold | origin | bedrock | confident | script → signature
  │     rose-gold | heir | regal | legacy | velvet → kids-capsule
  │   Assign mode_tags from presentation context:
  │     ghost | on-model | flatlay | campaign | lifestyle
  │   Attach sku and collection provenance from YAML frontmatter when in dossier mode.
  │   Output: elements with collection_tags and mode_tags populated
  │
  ▼
Step 3.5: Brand-Canon Validation  ← GUARD — runs before scoring, blocks on violations
  │
  │   AFFIRM signals (raise brand_alignment):
  │     concrete, urban, Oakland, streetwear, luxury-athletic, sport-heritage,
  │     cinematic-desaturated, monogram-editorial, West-Coast, thorn-motif,
  │     armor, Bay Bridge, golden hour, blue hour, candlelit-gothic
  │
  │   BLOCK signals → populate violation_flags:
  │     european-luxury-lineage
  │       (triggers: Bottega, Numéro, Hedi Slimane, Celine minimalist, Rick Owens
  │        register, Acne FW24 palette, Givenchy-Tisci, 032c, Off-White-early,
  │        Burberry-Imagined)
  │     pastel-preppy
  │       (triggers: pastel palette outside kids-capsule, preppy, ivy-league,
  │        country-club, polo-casual)
  │     minimalist-corporate
  │       (triggers: corporate minimalism, Helvetica-white-space, SaaS aesthetic,
  │        stock-photo lighting)
  │     cartoon
  │       (triggers: cartoon, illustrated, cel-shaded, anime, kawaii)
  │     mannequin-seams
  │       (triggers: visible seams, headless mannequin artifact, seam line)
  │
  │   RULE: if violation_flags is non-empty → set brand_canon.validated = false
  │     The element is held in a FLAGGED state.
  │     It will appear in the diff gate with a REJECT marker unless the user
  │     provides an explicit override (e.g., "OVERRIDE: approve flagged").
  │     No flagged element is written to the library without override.
  │
  │   Output: elements with brand_canon { validated, violation_flags } set
  │
  ▼
Step 4: Scoring
  │   Compute four independent scores per element:
  │
  │   reusability_score (int 1–10)
  │     Cross-context generic reuse:
  │       9–10  Universal across all collections and modes
  │       7–8   Domain-wide (any SkyyRose fashion shoot)
  │       5–6   Collection-specific but transferable across SKUs
  │       3–4   SKU-specific, limited reuse
  │       1–2   One-off; extract only if forced by source type
  │
  │   collection_specificity (int 0–3)
  │     0  Collection-agnostic
  │     1  Leans toward one collection but not locked
  │     2  Strongly associated with one collection
  │     3  Inseparable from exactly one collection's canon
  │
  │   brand_alignment (int 0–3)
  │     0  Neutral; no The-Five signal
  │     1  Weak alignment (one signal: e.g. streetwear but not Oakland)
  │     2  Clear alignment (urban-West-Coast, luxury-athletic, sport-heritage)
  │     3  Deep alignment (concrete + Oakland + garment protagonist + The Five)
  │     Note: violation_flags forces brand_alignment = 0 regardless of other signals.
  │
  │   gpt_image2_compatibility (int 0–3)
  │     0  Fragment likely to confuse the model (abstract, contradictory)
  │     1  Usable but may require tuning
  │     2  Renders reliably in edit-mode grammar
  │     3  Known-good against gpt-image-2 — used in production prompts
  │
  │   Output: all four scores attached to each element
  │
  ▼
Step 5: Deduplication
  │   Before assigning a new element_id, search existing library for:
  │     • Exact prompt_fragment match → skip (already exists)
  │     • High semantic overlap (>80% token overlap, same grammatical_position) →
  │       flag as MODIFY candidate (propose merging prompt_fragment variants)
  │     • Deprecated element with same concept → propose superseded_by linkage
  │   Output: deduplicated list; new elements, modify candidates, skip list
  │
  ▼
Step 6: Human-Review Diff Gate  ← NO WRITES UNTIL APPROVED
  │
  │   Emit a structured diff. Format per element:
  │
  │   [ADD] element_id: <id>
  │     prompt_fragment : "<text>"
  │     grammatical_position: <slot>
  │     domain / sub_category: <value>
  │     collection_tags: [<tags>]
  │     scores: reusability=N  specificity=N  alignment=N  gpt2=N
  │     brand_canon: validated=<bool>  flags=[<list or empty>]
  │     source: <source_type> / <source_id>
  │     → [APPROVE] / [REJECT] / [MODIFY: <suggested change>]
  │
  │   [MODIFY] element_id: <existing-id>
  │     current: "<old fragment>"
  │     proposed: "<new fragment>"
  │     reason: <why merging or updating>
  │     → [APPROVE] / [REJECT]
  │
  │   [DEPRECATE] element_id: <id>
  │     reason: <dossier corrected / superseded / canon violation>
  │     superseded_by: <new-id or null>
  │     → [APPROVE] / [REJECT]
  │
  │   Flagged (violation_flags non-empty) elements always receive [REJECT] by default.
  │   User may override with explicit "OVERRIDE: approve <element_id>".
  │
  │   WAIT for user response before proceeding to Step 7.
  │
  ▼
Step 7: Library Write
  │   Apply only the [APPROVE]d items from the diff.
  │   For each ADD:
  │     • Assign element_id (kebab-case, prefix: be-/lh-/sig-/kc-/common-)
  │     • Set added_date = today (YYYY-MM-DD)
  │     • Set version = 1, deprecated = false, superseded_by = null
  │     • Write to skyyrose-seed-elements.json (or active library file)
  │   For each MODIFY:
  │     • Increment version
  │     • Update prompt_fragment, scores as approved
  │   For each DEPRECATE:
  │     • Set deprecated = true, superseded_by = <new-id>
  │   For design-system mode:
  │     • Also write a design-template record with full raw content in visual_reference
  │
  ▼
Step 8: Learning Report
    Emit the post-write summary:
      • Elements added / modified / deprecated / skipped
      • Domain breakdown
      • Brand-canon violations caught (with element count)
      • Average scores across the new batch
      • Provenance summary (source files / SKUs ingested)

---

SKU-Aware Dossier Ingestion

Dossier path: wordpress-theme/skyyrose-flagship/data/dossiers/<slug>.md

YAML frontmatter fields consumed

sku: br-004
name: "Black Rose Hoodie"
collection: black-rose
logo_reference: "assets/images/logos/black-rose-logo.png"
reference_image: "data/product-references/br-004-hoodie-real-front.jpeg"

All five fields are mapped into provenance:

• source_type: "dossier"
• source_id: <sku>
• collection_tags seeded from collection field (no guessing required)
• reference_image and logo_reference emitted into the manifest export as reference_images

Zone-to-grammatical_position mapping

Dossier zone	Extracted as grammatical_position
Garment-type lock	subject
Materials / fabric description	material
Branding zones (front-chest / back / sleeves / pocket / collar)	construction_detail sub-cat
Colorway / accent description	colorway_descriptor sub-cat
Scene direction	scene + background + lighting
Negative list items	exclusion (prefixed "DO NOT")

Collection SOT JSONs

data/collections/*.json → products[] with fields: sku, name, dossier, references

The 33-SKU SOT is the authoritative index for batch mode. Never substitute a memory-based list.

---

gpt-image-2 Extraction Mode

When the source is a gpt-image-2 prompt or scripts/oai_render/prompt.py:

Parse by BASE_PROCEDURE slot labels:

Prompt clause pattern	grammatical_position
PRODUCT: <garment> (SKU <id>)	subject
ghost / on-model / flatlay presentation block	presentation
front view / back view directive	view
lighting description (studio / golden hour / blue hour / candlelit)	lighting
background / location description	background
fabric / texture clause	material
high-fidelity / photorealistic / 100 megapixel	fidelity
COLLECTION SCENE: block	scene
DO NOT ... clause	exclusion

Tag each element with source_type: "prompt" and source_id: "scripts/oai_render/prompt.py:<label>".

---

Collection Auto-Tagging Reference

Keyword signals in source	→ collection_tag	accent
silver, armor, concrete, thorn, Cinzel, Bay Bridge, blue hour, dark-on-dark	black-rose	#C0C0C0
crimson, bloodline, grief, beast, gothic, château, candlelit, burgundy	love-hurts	#DC143C
gold, origin, bedrock, confident, West-Coast, golden hour, script-anchor	signature	#D4AF37
rose-gold, heir, regal, legacy, velvet, throne, scaled-down	kids-capsule	#B76E79

Empty collection_tags = collection-agnostic element (valid and common for common/product/lighting elements).

---

Brand-Canon Validation Reference

Affirm — raises brand_alignment

• Concrete / urban texture
• Oakland / Bay Area geography
• Streetwear silhouette
• Luxury-athletic / sport-heritage construction
• Cinematic-desaturated color grade
• Monogram-editorial composition
• West-Coast street-luxury confidence
• Thorn / rose motif (all collections)
• The Five reference aesthetics: Kith / Oaklandish / Culture Kings / Fear of God / Palm Angels

Block — populates violation_flags, prevents write without override

Flag key	Trigger terms
european-luxury-lineage	Bottega Veneta weave, Numéro editorial, Hedi Slimane Celine, Rick Owens architectural drape, Acne FW24 palette, Givenchy-Tisci, 032c, Off-White-early, Burberry-Imagined
pastel-preppy	pastel palette (outside kids-capsule hero accent), preppy, ivy-league, country-club, polo-casual
minimalist-corporate	corporate minimalism, Helvetica white-space layout, SaaS product-shot aesthetic, stock-photo lighting rig
cartoon	cartoon, illustrated, cel-shaded, anime, kawaii, comic-book
mannequin-seams	visible seam lines, headless-mannequin artifact

---

Provenance Fields (per schema)

Every element carries full provenance per references/element-schema.md:

{
  "source_type": "dossier",
  "source_id": "br-004",
  "added_date": "2026-06-13",
  "version": 1,
  "deprecated": false,
  "superseded_by": null
}

source_type enum: dossier | prompt | template | brand-doc | manual

On edit: bump version. On retirement: set deprecated: true, set superseded_by to the replacing element_id or null.

---

Seed Corpus Procedure

The founding corpus is built from these sources (run once, then maintained via incremental ingestion):

Source	Mode	SKUs / docs
All 33 dossiers in data/collections/*.json	batch-dossiers	33 SKUs
knowledge-base/seed/from-interview.md	brand-doc	founder voice, brand DNA
docs/brand/collection-stories.md	brand-doc	per-collection narrative canon

Procedure:

1. Run Mode G: /universal-learner seed
2. Pipeline ingests all three source groups sequentially.
3. A single combined diff is emitted for human review.
4. After approval, elements are written to references/skyyrose-seed-elements.json.
5. This file is the seed corpus — design-master and universal-learner both reference it.
6. The file is NOT produced or overwritten by this skill directly during non-seed runs; incremental additions are staged for review first.

The seed JSON output path is references/skyyrose-seed-elements.json. The schema for every record in that file is defined in references/element-schema.md. Do not create or overwrite it without running the full seed procedure and completing the diff-gate approval.

---

Manifest Export

The manifest export (Mode H) produces the gpt-image-2 element manifest that design-master consumes to assemble render prompts.

Format (array of element records per schema, filtered and sorted):

[
  {
    "element_id": "be-bg-blue-hour-bay-bridge",
    "prompt_fragment": "the Bay Bridge silhouetted behind, shot from the Oakland shore at blue hour, framed by a moody black-rose garden",
    "grammatical_position": "background",
    "domain": "fashion_editorial",
    "collection_tags": ["black-rose"],
    "mode_tags": ["on-model", "campaign"],
    "reusability_score": 7,
    "collection_specificity": 3,
    "brand_alignment": 3,
    "gpt_image2_compatibility": 3,
    "brand_canon": { "validated": true   
     
     
     
     
     
     
  

Export filters:

• --collection <slug>: restrict to elements with that collection_tag (or collection-agnostic elements)
• --mode <ghost|on-model|flatlay>: restrict to elements whose mode_tags include the target
• Deprecated elements are always excluded from export
• Flagged elements (brand_canon.validated = false) are always excluded from export

design-master reads this manifest and assembles grammatical_position slots into the images.edit call: client.images.edit(model="gpt-image-2", image=[...refs...], prompt=<assembled>, size="1024x1536", quality="high", background="auto", n=1)

---

Learning Report Format

# Universal Learner — Learning Report

Date      : YYYY-MM-DD
Source(s) : <source_type> / <source_id>
Mode      : <A–H>

## Domain Breakdown

primary  : fashion_editorial
  sub-cats: garment_silhouette(N), fabric_texture(N), colorway_descriptor(N),
            construction_detail(N), model_direction(N), location_set(N), editorial_lighting(N)
secondary: product(N), common(N)

## Diff Results

  ADD      : N elements approved / N rejected / N modified
  MODIFY   : N elements updated
  DEPRECATE: N elements retired

## Brand-Canon Report

  Validated     : N elements
  Flagged       : N elements
    european-luxury-lineage : N
    pastel-preppy           : N
    minimalist-corporate    : N
    cartoon                 : N
    mannequin-seams         : N
  Overrides applied: N

## Score Summary (approved batch)

  reusability avg        : N.N / 10
  collection_specificity : N.N / 3
  brand_alignment        : N.N / 3
  gpt_image2_compat      : N.N / 3

## Provenance

  SKUs ingested : [list]
  Docs ingested : [list]

## Library State

  Total elements (post-write): N
  By collection tag:
    signature    : N
    black-rose   : N
    love-hurts   : N
    kids-capsule : N
    agnostic     : N

---

Scoring Reference

reusability_score (1–10)

Score	Criterion
9–10	Universal — cross-collection, cross-mode, cross-domain
7–8	Domain-wide — any SkyyRose fashion shoot, any collection
5–6	Collection-transferable — fits multiple SKUs in one collection
3–4	SKU-specific — tied to one garment's details
1–2	One-off — extract only when source_type demands preservation

collection_specificity (0–3)

Score	Criterion
0	Collection-agnostic
1	Leans toward one collection, not locked
2	Strongly associated with one collection's aesthetic
3	Inseparable from exactly one collection's locked canon

brand_alignment (0–3)

Score	Criterion
0	Neutral; no The-Five signal. Always 0 when violation_flags non-empty.
1	Weak: one affirmation signal (e.g. streetwear but not Oakland-anchored)
2	Clear: urban-West-Coast or luxury-athletic or sport-heritage confirmed
3	Deep: concrete + Oakland + garment protagonist + The-Five reference

gpt_image2_compatibility (0–3)

Score	Criterion
0	Fragment likely to confuse the model (abstract, contradictory, or over-specified)
1	Usable but may require prompt tuning before production use
2	Renders reliably in images.edit mode grammar
3	Known-good — used in production prompts in scripts/oai_render/prompt.py

---

Acceptance Criteria

• Correctly identifies and assigns fashion_editorial as primary domain for all SkyyRose inputs
• Parses YAML frontmatter (sku / name / collection / logo_reference / reference_image) from dossiers
• Tags elements with correct collection_tag from keyword signals AND from frontmatter
• Brand-canon validation catches all BLOCK-list terms; flagged elements never written without override
• All four scores (reusability / collection_specificity / brand_alignment / gpt_image2_compatibility) computed per element
• gpt-image-2 extraction mode assigns grammatical_position correctly from BASE_PROCEDURE slot labels
• All elements carry provenance fields (source_type / source_id / added_date / version / deprecated / superseded_by)
• Human-review diff gate emitted before every write; no element written without explicit [APPROVE]
• Seed corpus procedure documented; output path references/skyyrose-seed-elements.json referenced
• Manifest export produces schema-valid JSON consumable by design-master
• All element records conform to references/element-schema.md
• No deprecated elements appear in manifest export
• No flagged elements appear in manifest export

---

Status: Active Last updated: 2026-06-13 Schema contract: references/element-schema.md Seed corpus: references/skyyrose-seed-elements.json Consumers: design-master (manifest reader), oai_render pipeline (prompt assembler)