extract-structure

# Extract Structure Data

Interpretation-only companion to `create-structure`. This skill **does not extract data from Figma**. It reads `{cachePath}/{componentSlug}-_base.json` (produced by the uSpec Extract Figma plugin), applies the same reasoning layer as `create-structure`, and writes the normalized `StructureSpecData` JSON to disk for the `create-component-md` orchestrator to consume.

**Quality contract:** every reasoning step (section planning, ownership resolution, override promotion, design-intent notes, anomaly detection) mirrors `create-structure/SKILL.md`. Any improvement to structure-extraction quality must be made in both places.

**Batch-mode contract.** This skill MUST NOT call `AskQuestion`, prompt for confirmation, or pause for user input. When a value cannot be resolved from `_base.json` (and a Step 3-delta doesn't recover it), emit a row with `provenance: "not-measured"` and `values: ["—", …]` instead of asking. No mid-interpretation clarifications.

## Invocation Contract

The orchestrator calls this skill with these inputs (already resolved — do NOT re-parse URLs or re-read `uspecs.config.json`):

- `componentSlug` — filename-safe slug
- `cachePath` — cache directory, typically `.uspec-cache/{componentSlug}/`
- `optionalContext` — free-form string from the user (may be `"none"`)
- `mcpProvider` — `figma-console` or `figma-mcp` (only needed if a Step 3-delta escape hatch fires AND a live Figma link was provided to the orchestrator)
- `deltaAvailable` — boolean. When the orchestrator received only a `baseJsonPath` (no `figmaLink`), this is `false` and the Step 3-delta escape hatch must not fire; log the gap in `data._deltaExtractions[]` with `unavailable: "no-figma-link"` and continue with best-effort output.
- `apiDictionaryPath` — absolute or workspace-relative path to `{cachePath}/{componentSlug}-api-dictionary.json`. Optional. When present, this file is the canonical vocabulary for axis/value/sub-component/state naming (see Step 2.5). When absent, the skill continues with `_dictionaryUnavailable: true` in its output envelope and the renderer treats the produced cache as lower-confidence.

`fileKey` and `nodeId` are **not** pass-through parameters anymore. Read them from `{cachePath}/{componentSlug}-_base.json._meta.fileKey` and `_meta.nodeId` at the start of Step 1.

**Output:**

- Writes `{cachePath}/{componentSlug}-structure.json` containing the full `StructureSpecData` object.
- Returns a single-line summary to the orchestrator: `"Structure extracted: N sections, M sub-components, K slot contents → {path}"`.
- Never creates or mutates Figma nodes.

## MCP Adapter

This skill typically makes **zero** MCP calls — it reads `_base.json` from disk. The adapter applies only to the optional Step 3-delta escape hatch.

| Operation | `figma-console` | `figma-mcp` |
|-----------|-----------------|-------------|
| Execute Plugin JS (delta only) | `figma_execute` with `code` | `use_figma` with `fileKey`, `code`, `description` |

For `figma-mcp` delta scripts, include the page-focus preamble after `getNodeByIdAsync`:

```javascript
let _p = node; while (_p.parent && _p.parent.type !== 'DOCUMENT') _p = _p.parent;
if (_p.type === 'PAGE') await figma.setCurrentPageAsync(_p);
```

## Workflow

```
Task Progress:
- [ ] Step 1: Read instruction file
- [ ] Step 2: Load _base.json and optionalContext
- [ ] Step 2.5: Load API dictionary (canonical vocabulary) — optional
- [ ] Step 3: Build working evidence set (from _base.json fields only)
- [ ] Step 3-delta: OPTIONAL — read-only Figma call if a fact is genuinely missing
- [ ] Step 4: AI interpretation layer — section plan, ownership, design-intent notes, anomalies
- [ ] Step 5: Generate StructureSpecData object
- [ ] Step 6: Audit (re-read instruction file)
- [ ] Step 7: Write JSON to cache and return one-line summary
```

### Step 1: Read Instructions

Read [agent-structure-instruction.md]({{ref:structure/agent-structure-instruction.md}}). This is the **same** instruction file used by `create-structure`. Treat it as the single source of truth for the `StructureSpecData` schema, row emission rules, and audit checklists.

#### Rendering-only sections to skip

The shared instruction file describes both extraction and Figma rendering. This skill only performs interpretation — ignore guidance in the sections below. The data schema and audit checklists still apply.

- **§Role — "render structure documentation directly into Figma"** — framing only; this skill writes JSON to disk instead.
- **§Inputs — the `figma_execute` row's "render sections" phrasing** — this skill does not render.
- **§Data Structure Reference — "The data is passed directly into Figma template placeholders — no JSON output is needed"** — inverted: we **do** output JSON. Keep the schema; discard the "no JSON" framing.
- **§Field Rules — "Render order: first column → values[0..n] → Notes", "Renders between Spec and Notes columns", "Always renders in the final Notes column"** — rendering-order prose. The `spec` / `values[]` / `notes` shape is still the authoritative schema.
- **§Common Mistakes — "Overriding preview frame layout" and any bullet about `#Preview` frame behavior** — rendering concerns. Data-level mistakes (missing sub-component sections, wrong axis grouping, bad display strings) still apply.
- **§Pre-Render Validation Checklist — "Sub-component preview sourcing" and "Preview frame untouched" rows** — do not apply. All other checks (shape of `sections`, correctness of `rows`, column counts, measurement labels) DO still apply.
- **§Inputs → "Authoritative `.md`" (including the child "What the `.md` already tells you (Mode B extraction scope)" subsection)** — Mode-B-only concepts for the downstream `create-structure` skill. `extract-structure` produces the data that becomes the `.md`; it never consumes a `.md` as input and never runs Mode B. Ignore the entire `### Authoritative .md` block.

Note: Fields that look like rendering config but are part of the ou