Skip to content
Docs

Extract

Extract is the layer where you pull the objects, personas, and tasks out of the product idea. It takes the Vision as input and commits the semantic structure: what things exist in the system, who uses them, and what workflows connect them. Every downstream layer reads Extract.

What Extract captures

Extract commits four files at once, each capturing a different facet of the semantic model.

Intent

The problem statement, the intended outcome, and the jobs to be done. A small file that anchors the rest of the extraction. One paragraph of problem framing, one paragraph of outcome description, and a short list of jobs.

Entities

The objects. The nouns.

Each entity has:

  • A name and a short description.
  • Attributes, each with a data type (string, number, currency, date, reference, enum, etc.) and a semantic role (identity, descriptor, status, metric, timestamp, reference).
  • States, for entities with a lifecycle (draft, submitted, approved). States include transitions with named triggers.
  • Relationships to other entities (has-many, has-one, belongs-to, many-to-many) with labels.
  • A cardinality (one, few, many, unbounded).
  • Optional ownership (which persona primarily owns this entity).

Attributes and roles are the traits that fire Visual Cues in the Map layer. A currency attribute fires the currency-treatment cue. An identity role earns the primary-label position. Without accurate attribute types and roles in Extract, Map has nothing to reason from.

Personas

The users.

Each persona has a name, goals, task frequency, tech comfort level, a mental model (how they think about the domain), success criteria, and the primary entities and tasks they touch.

Personas influence pattern selection. A power user who touches the same entity fifty times a day wants density. A casual user who touches the same entity monthly wants clarity.

Tasks

The verbs. The workflows.

Each task is a directed graph of steps with explicit edges. Steps represent actions (create, read, update, delete, transition, decide). Edges represent transitions between steps. Tasks can branch at decision points, loop, and terminate at multiple endpoints (success or error).

Each task also records:

  • The trigger that starts the task.
  • The persona who performs it.
  • The entities involved at each step.
  • The mutations (create, update, transition, delete) the task produces.

Tasks are the primary input for Pattern Matching in Map. A "browse and select" task shape assigns list_detail. A "create with steps" task shape assigns wizard. A "triage items awaiting action" task shape assigns inbox_queue.

The canvas

Extract renders as three grouped panels: Entities, Personas, Tasks. Intent renders as a small card at the top.

  • Entities. Each entity is a card showing name, description, attribute list with type and role, state diagram (if any), and relationships as arrows to other entity cards.
  • Personas. Each persona is a card with goals, frequency, tech comfort, mental model, and the entities and tasks they own.
  • Tasks. Each task renders as a flow graph on a canvas. Nodes are steps. Edges are transitions. Decision points are diamond-shaped. Success and error endpoints are distinguished.

You can edit any field inline. Adding an attribute, renaming an entity, splitting a step all happen directly on the card or the graph. Renames propagate silently to references in the other files through graph-mutations.ts.

The files written

Extract writes four files to design/.

  • design/intent.json, Problem, outcome, jobs-to-be-done.
  • design/entities.json, The entities array.
  • design/personas.json, The personas array.
  • design/tasks.json, The tasks array.

Keeping the files separate means each layer downstream can depend on just what it needs. Map reads all four. Structure reads entities and personas. Layout reads entities and tasks indirectly through pattern assignments.

The skill

/extract is the skill that populates the Extract layer.

Reads:

  • design/vision.json (the foundation, pulls confirmed goals, constraints, audience, and non-goals as context)
  • design/intent.json, design/entities.json, design/personas.json, design/tasks.json (if they exist, merges, preserves IDs)
  • Any additional context passed as arguments (a PRD, user stories, a transcript)

Writes:

  • All four Extract files, incrementally as the conversation progresses.

Behavior:

  • Extracts progressively. When a clear entity emerges, writes it immediately so you see it in the canvas.
  • Pushes on the four-question filter for every candidate entity: does it have identity, does it have multiple attributes, is it created or read or updated or deleted, does it appear in multiple contexts? Candidates that fail are probably attributes or views, not entities.
  • Names relationships explicitly with both a type and a domain-meaningful label.
  • Identifies gateway entities, the ones that appear in many workflows and connect to many others.
  • Flags ambiguity with null rather than fabricating attributes or states to fill the schema.

The recipe example

A Vision like the one from the previous page, run through /extract, produces this structure.

Intent

  • Problem: home cooks routinely scale recipes to serving counts that do not match the original, and existing recipe apps bury scaling or ignore it.
  • Outcome: a home cook scales any recipe to a target serving count in under thirty seconds, on a phone, with saved favorite ratios.
  • Job: "help me cook this recipe for a different number of people without redoing the math."

Entities

  • Recipe, identity attribute name, descriptor attributes photo (file), sourceUrl (url), baseServings (number), relationship has-many Ingredient, has-many ScalingRatio, cardinality many.
  • Ingredient, identity name, descriptor quantity (number), unit (enum: cup, tsp, tbsp, g, oz, ml), belongs-to Recipe, cardinality many.
  • Serving, a derived concept. Attributes count (number). Used by the scaling task.
  • ScalingRatio, attributes ratio (number), targetServings (number), belongs-to Recipe, cardinality few.

Personas

  • Home Cook, goals: "cook a recipe for a different number of people without mistakes"; frequency: "a few times a week"; tech comfort: moderate; mental model: "recipes come from websites and cookbooks; I read them on my phone in the kitchen"; primary entities: Recipe, Ingredient.

Tasks

  • Scale a recipe, trigger: "cook opens a recipe"; persona: Home Cook; steps: pick recipe → enter target servings → derive scaled ingredient list → optionally save ratio → return to cooking; mutations: reads Recipe and Ingredient, creates ScalingRatio.
  • Save a favorite ratio, inline inside the scaling task.
  • Browse saved scalings, trigger: "cook returns to a recipe they have scaled before"; reads Recipe and ScalingRatio.

This is enough for /map to fire Visual Cues (the photo attribute fires the image-entity cue, the name identity fires primary-label-position) and to reason about pattern assignments (browse task + image-heavy entity → card grid for the recipe list; single-entity task + scaling control → detail page for the recipe view).

What Extract is not for

  • Pattern decisions. Extract says what objects exist. Map says what patterns they get. Extract should not name list_detail or card_grid.
  • Page inventory. That is Structure. Extract does not enumerate pages or routes.
  • Copy or sample data. Extract captures types and shapes, not specific values.
  • Visual treatment. That is Map too. Extract does not say "status badges." It says "this entity has a status lifecycle with four states."

The discipline is that Extract commits to the semantic structure only. Every decision that follows (visual, spatial, aesthetic) reads from Extract but is made in a later layer.

Where to next

  • Map takes Extract as input and assigns governance (Visual Cues, patterns, priorities).
  • Vision is the input Extract reads from.
  • The governance schema for how Map uses the entity traits and task shapes Extract commits.