@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-cli-lean-iterate/SKILL.md

@@ -0,0 +1,283 @@
+# /figma-cli-lean-iterate — Lean Pipeline Orchestrator for CLI
+
+## Purpose
+
+Runs a **lean** Figma-to-SwiftUI pipeline for one or more issues: pick → start → implement (phases 0-4) → code connect (phase 6) → commit. **Skips testing (phase 5) and wiki (phase 7).** Returns a structured `ORCHESTRATOR_RESULT` block that the CLI orchestrator can parse.
+
+This skill is identical in structure to `/figma-cli-iterate` — the only difference is that phases 5 and 7 are omitted. Use this when you want a faster turnaround and will run tests/wiki separately (or not at all).
+
+This skill IS the orchestrator. It dispatches **only leaf-phase subagents** — individual phase instruction files that read one doc, execute gates, and return. It never delegates to multi-phase meta-skills.
+
+## Forbidden Dispatches
+
+**NEVER dispatch these as subagents — they are orchestrators that would try to dispatch further:**
+
+- `/figma-to-swift-ui-implement` (Phases 0-4)
+- `/figma-to-swift-ui-test` (Phase 5)
+- `/figma-to-swift-ui-code-connect` (Phase 6)
+- `/figma-to-swift-ui-wiki` (Phase 7)
+- `/figma-iteration-commit`
+- `/figma-to-swiftui` (entire pipeline)
+
+Instead, dispatch the **leaf phase instruction files** directly via Agent tool.
+
+## Parameters
+
+```
+/figma-cli-lean-iterate #230           ← implement specific issue (lean)
+/figma-cli-lean-iterate                ← auto-pick next available (lean)
+```
+
+---
+
+## Constants
+
+```
+GH_REPO         = {github.componentsRepo}
+REPO_ROOT       = git repo root (auto-detect)
+COMMON          = ${REPO_ROOT}/{repos.common.path}
+UICOMPONENTS    = ${REPO_ROOT}/{repos.components.path}
+PHASE_DIR       = .instructions/figma/figma-to-swiftui/phases
+REF_DIR         = .instructions/figma/figma-to-swiftui/reference
+SCRIPT_DIR      = .instructions/figma/figma-to-swiftui/scripts
+```
+
+Note: the `WIKI` submodule is intentionally omitted from the constants — the lean flow never touches it.
+
+---
+
+## STEP 0 — Pick Issue
+
+Same logic as `/figma-iterate` STEP 0. Read `.instructions/figma/figma-iterate/SKILL.md` STEP 0 for details.
+
+Extract from issue body: `componentName`, `figmaUrl`, `nodeId`, `jiraKey`, `registryName`, `figmaPage`, `acceptanceCriteria`.
+
+---
+
+## STEP 1 — Start
+
+Run inline (not as a skill). Read `.instructions/figma/figma-to-swift-ui-start/SKILL.md` for the full procedure:
+
+1. Parse issue → extract metadata
+2. Fetch latest → checkout `develop` (main stays on develop, NO feature branch), `iteration/develop` (submodules)
+3. Create feature branches on **submodules only** (common, uicomponents) — wiki submodule is NOT checked out
+4. Registry lookup → `componentLocation`, `artifactPath`
+5. Save specs artifact if acceptance criteria exist
+6. Assign (GitHub + Jira)
+7. **Move GitHub issue to "In Develop" on the Projects V2 board** — required. Read STEP 5 of the start skill. Run both GraphQL mutations: set Status option `bc6c45f7` (In Develop) and Phase option `0577dcda` (Implementation). Do NOT skip this — new issues are created with Status=Todo, so this transition is how the board reflects "someone is working on it".
+
+---
+
+## required PRE-READ
+
+Before dispatching any phase subagent, read:
+  ${REF_DIR}/orchestrator-discipline.md
+
+These 6 rules govern orchestrator behavior. Violations have caused repeated failures. Follow them strictly.
+
+---
+
+## STEP 2 — Implement (Phases 0-4, 6)
+
+This is the core orchestration. Run each phase by dispatching leaf subagents and scripts.
+
+**Phases 5 (testing) and 7 (wiki) are INTENTIONALLY skipped in the lean flow.** The `status.ios.tested` and `status.ios.wiki` registry flags will remain their previous values.
+
+### Spec Injection (Option A)
+
+Before dispatching any Phase 4+ subagent, check if `{artifactPath}/pass0/specs.md` exists. If it does:
+1. Read the specs
+2. Extract concrete requirements
+3. Inject them as **CRITICAL SPEC GATES** in the subagent dispatch prompt — NOT as a sidecar "also read this file" instruction
+
+This ensures spec requirements become indistinguishable from standard gates.
+
+### Phase Dispatch Table
+
+All instruction files relative to `${PHASE_DIR}/`.
+
+| Phase | Instruction | Model | Subagent? |
+|-------|-------------|-------|-----------|
+| 0 | `phase-0-init.md` | opus | Yes (leaf) |
+| 1 | `${SCRIPT_DIR}/phase1-gather.py` | N/A | No (script) |
+| 2A | `phase-2a-testing-identifiers.md` | opus | Yes (leaf) |
+| 2B | `phase-2b-localization.md` | sonnet | Yes (leaf) |
+| 2C | `phase-2c-accessibility.md` | opus | Yes (leaf) |
+| 2D | `phase-2d-analytics.md` | sonnet | Yes (leaf) |
+| 3A | `phase-3a-location.md` | sonnet | Yes (leaf) |
+| 3C | `phase-3c-nested.md` | sonnet | Yes (leaf) |
+| 3H | `phase-3h-variant-config.md` | opus | Yes (leaf) |
+| 3D | `phase-3d-patterns.md` | opus | Yes (leaf) |
+| 4A | `phase-4a-configuration.md` | opus | Yes (leaf, COMPLEX only) |
+| 4B | `phase-4b-view.md` | opus | Yes (leaf) |
+| 4C | `phase-4c-documentation.md` | sonnet | Yes (leaf) |
+| 4D | `phase-4d-preview.md` | sonnet | Yes (leaf) |
+| 4E | `phase-4e-modifiers.md` | sonnet | Yes (leaf, COMPLEX only) |
+| ~~5A~~ | *(skipped — lean)* | — | — |
+| ~~5B~~ | *(skipped — lean)* | — | — |
+| ~~5C~~ | *(skipped — lean)* | — | — |
+| 6 | `phase-6-code-connect.md` | opus | Yes (leaf) |
+| ~~7~~ | *(skipped — lean)* | — | — |
+
+### Dispatch Prompt Template
+
+For each leaf subagent:
+
+```
+You are executing {Phase Name} of the Figma-to-SwiftUI workflow (lean run — no testing, no wiki).
+
+## Context
+- Component: {componentName}
+- File Key: {fileKey}
+- Node ID: {nodeId}
+- Artifact Path: {artifactPath}
+- Component Location: {componentLocation}
+
+## CRITICAL SPEC GATES (only if specs exist)
+{Concrete requirements extracted from specs — phrased as mandatory instructions, not a file reference}
+
+## Tool Restrictions
+{from dispatch table}
+
+## Your Instructions
+Read and STRICTLY FOLLOW your phase instructions gate-by-gate from this file:
+  {PHASE_DIR}/{instruction file}
+
+Read the return protocol from:
+  {REF_DIR}/halt-return-protocol.md
+
+## Reference Files
+{relevant reference files from the read-order table in figma-to-swiftui/SKILL.md}
+
+## Previous Phase Artifacts
+{artifact paths in read order — compact first}
+```
+
+### Phase Execution Flow
+
+**Phase 0**: Dispatch subagent → verify `IMPLEMENTATION_HISTORY.md` created.
+
+**Phase 1**: Run script:
+```bash
+python3 ${SCRIPT_DIR}/phase1-gather.py \
+  --file-key "{fileKey}" --node-id "{nodeId}" \
+  --artifact-path "{artifactPath}" --component-name "{componentName}"
+```
+If `COMPLETE_WITH_DEFERRED` → dispatch Phase 1 deferred resolution subagent.
+
+**Phase 2**:
+1. Pre-check: verify `pass1/_index.md`
+2. Normalize: check sublayers in `design_context_response.json`
+3. Registry lookup: `FigmaRegistryUtility utility-lookup --node-id '{nodeId}'`
+4. Wave 1 (parallel): dispatch 2A + 2B + 2C subagents simultaneously
+5. Wave 2: dispatch 2D subagent
+6. Finalize: `python3 ${SCRIPT_DIR}/phase2-finalize.py ...`
+
+**Phase 3**:
+1. Wave 1 (parallel): `python3 ${SCRIPT_DIR}/phase3-scripts.py wave1 ...` + dispatch 3A + 3C + 3H subagents
+2. Missing token resolution: check `pass3/02_token_mapping.md` for "⚠️ not found". If any → dispatch resolution subagent
+3. Wave 2: dispatch 3D subagent
+4. Wave 3: `python3 ${SCRIPT_DIR}/phase3-scripts.py 3g ...`
+5. Spec: `python3 ${SCRIPT_DIR}/phase3-scripts.py spec ...`
+6. Write `pass3/_index.md`
+
+**Phase 4**:
+1. Read `pass3/05_complexity.md` → SIMPLE or COMPLEX
+2. Prepare directory: `mkdir -p {componentLocation}`
+3. Wave 1 (parallel): dispatch 4B + 4C (+ 4A if COMPLEX)
+4. Wave 2 (parallel): dispatch 4D (+ 4E if COMPLEX)
+5. Validate: `bash ${SCRIPT_DIR}/validate-phase4.sh ...`
+6. Build: `xcodebuild build ...` — fix errors if any
+7. Registry finalize: `python3 ${SCRIPT_DIR}/phase4-finalize.py ...`
+
+**Phase 5 (TESTING)**: **SKIPPED — lean flow.** Do NOT switch Package.swift to local common. Do NOT dispatch 5A/5B/5C. Do NOT run tests. The `status.ios.tested` flag will stay at its previous value.
+
+**Phase 6**: Dispatch subagent → run `${SCRIPT_DIR}/phase6-finalize.py` as safety net.
+
+**Phase 7 (WIKI)**: **SKIPPED — lean flow.** Do NOT dispatch 7A. Do NOT touch the wiki submodule. The `status.ios.wiki` flag will stay at its previous value.
+
+---
+
+## STEP 3 — Commit
+
+Run inline. Read `.instructions/figma/figma-iteration-commit/SKILL.md` for the full procedure, with these lean-mode adjustments:
+
+1. Rebase submodules to `iteration/develop` if on feature branch
+2. Build validation
+3. Commit to `iteration/develop` (**common → uicomponents only** — wiki submodule is intentionally untouched)
+4. Push with rebase-retry loop
+5. Clean up feature branches (common + uicomponents only)
+6. Issue housekeeping (comment, progress table — but the Tests and Wiki rows stay at their previous state)
+7. Auto-unblock dependents
+
+**Skip any step in `/figma-iteration-commit` that writes to or pushes the wiki submodule.**
+
+---
+
+## STEP 4 — Loop
+
+Same logic as `/figma-iterate` STEP 4. If specific issue → exit after one. If `--count` → decrement. Otherwise → pick next.
+
+---
+
+## STEP 5 — Output Result
+
+Output EXACTLY this block as your FINAL message. Nothing else after it.
+
+### On success (per component):
+
+```
+ORCHESTRATOR_RESULT:
+  status: COMPLETE
+  mode: lean
+  issueNumber: <N>
+  componentName: <name>
+  figmaUrl: <url>
+  nodeId: <nodeId>
+  jiraKey: <key>
+  commits:
+    common: <SHA>
+    uicomponents: <SHA>
+    wiki: null   # lean run — wiki not touched
+  phases: [0, 1, 2, 3, 4, 6]   # 5 and 7 intentionally omitted
+  testsRun: 0   # lean run — no tests executed
+  summary: <one-line>
+```
+
+### On failure:
+
+```
+ORCHESTRATOR_RESULT:
+  status: FAILED
+  mode: lean
+  issueNumber: <N>
+  componentName: <name>
+  failedPhase: <phase>
+  reason: <exact reason>
+  suggestion: <what to fix>
+```
+
+### On full iteration completion:
+
+```
+ORCHESTRATOR_RESULT:
+  status: ITERATION_COMPLETE
+  mode: lean
+  completed:
+    - { issue: <N>, component: <name>, commits: { common: <SHA>, uicomponents: <SHA> } }
+  failed:
+    - { issue: <N>, component: <name>, phase: <phase>, reason: <reason> }
+  remaining: <count>
+```
+
+---
+
+## Error Handling
+
+- **No available issues**: Output ORCHESTRATOR_RESULT with status ITERATION_COMPLETE, empty completed/failed.
+- **Blocked issue**: Output FAILED.
+- **Phase HALT**: Show reason, ask user. If resolved → retry phase. If skipped → FAILED for this component, move to next.
+- **Build failure**: Attempt auto-fix. If unfixable → FAILED.
+- **3 consecutive failures**: Stop iteration.
+- **Subagents can't dispatch subagents**: This is why we dispatch only leaf phases. If a phase instruction file references dispatching subagents, ignore that — run its gates directly in the subagent.
+- **Accidental phase-5 / phase-7 dispatch**: If you catch yourself dispatching a 5A/5B/5C/7A subagent, STOP immediately. This is the lean flow — those phases must not run.

package/pipeline/skills/figma-common/figma-cli-skip/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: figma-cli-skip
+description: CLI variant of /figma-skip — fetches origin iteration/develop on mobile-common, marks a Figma component as skipped in the registry, commits, pushes, and returns a structured ORCHESTRATOR_RESULT block for the CLI.
+user-invocable: true
+argument-hint: <figma-url> [<figma-url> ...] [--reason <reason>]
+allowed-tools: Bash, Read, Write, Edit
+status: wip-v5
+sourced-from: upstream/figma-cli-skip
+---
+
+# /figma-cli-skip — CLI Skip Orchestrator
+
+## Purpose
+
+CLI-friendly variant of `/figma-skip`. Marks one or more Figma components as
+skipped in the `mobile-common` component registry, then **commits and pushes
+to `origin/iteration/develop`** so the skip state is visible to other tools
+and teammates immediately. Returns a structured `ORCHESTRATOR_RESULT` block
+the CLI orchestrator can parse.
+
+This skill wraps the existing `/figma-skip` logic with:
+- A mandatory `git fetch origin iteration/develop` + fast-forward/rebase on
+  `mobile-common` **before** touching registry files.
+- A mandatory commit + push on `mobile-common` **after** writing the registry
+  entries and regenerating the catalog.
+- A structured machine-readable output block.
+
+It does **not** update Confluence (that's VPN-gated and not a CLI concern).
+Use `/figma-skip` directly when you need the Confluence dashboard refreshed.
+
+## Forbidden Operations
+
+> **NEVER create branches on the main repo (REPO_ROOT).** This skill only
+> touches the `mobile-common` submodule. Main repo submodule pointer updates
+> are out of scope — handle them separately.
+
+> **NEVER commit unrelated working-tree changes.** Stage only the registry
+> JSON(s) you wrote and the catalog output files the `FigmaRegistryUtility
+> catalog` command produced. Use explicit file paths with `git add` — never
+> `git add -A` / `git add .`.
+
+> **NEVER skip hooks (`--no-verify`) or force-push.** If push is rejected
+> because the remote moved, rebase and retry; do not force.
+
+## Parameters
+
+```
+/figma-cli-skip https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}
+/figma-cli-skip https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId} --reason "Cursor component, not needed on mobile"
+/figma-cli-skip <url1> <url2> <url3> --reason "Legacy components removed from scope"
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `<figma-url>` | Yes | One or more Figma URLs (space-separated for batch). |
+| `--reason <reason>` | No | Free-form skip reason. Captured in the commit message body. |
+
+### URL Parsing
+
+For each URL, extract:
+```
+https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}
+```
+Convert `-` to `:` in node-id (e.g., `3-9045` → `3:9045`). The registry
+filename is `{nodeId-with-colon-replaced-by-dash}.json` (e.g., `3-9045.json`).
+
+## Constants
+
+```
+REPO_ROOT       = git repo root (auto-detect via `git rev-parse --show-toplevel`)
+COMMON          = ${REPO_ROOT}/{repos.common.path}
+REGISTRY_DIR    = ${COMMON}/Shared/Figma/Components
+UTILITY         = ${COMMON}/.build/debug/FigmaRegistryUtility
+```
+
+---
+
+## STEP 0 — Parse Arguments
+
+Split `$ARGUMENTS` into URLs and flags. Extract:
+- `urls[]` — every non-flag argument that looks like a Figma URL
+- `reason` — value after `--reason` (may be empty)
+
+If `urls` is empty → output `FAILED` with `reason: "No Figma URL provided"`.
+
+For each URL, extract `fileKey` and `nodeId` (colon form).
+
+---
+
+## STEP 1 — Sync `mobile-common` to `origin/iteration/develop`
+
+```bash
+cd "${COMMON}"
+git fetch origin iteration/develop
+```
+
+Check current branch:
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+```
+
+**If `CURRENT_BRANCH == iteration/develop`**:
+```bash
+git pull --ff-only origin iteration/develop
+```
+If fast-forward fails (local has diverged work) → HALT with
+`FAILED / reason: "mobile-common iteration/develop has diverged from origin — resolve manually before running figma-cli-skip"`.
+
+**If on a different branch**:
+Check whether the working tree is clean:
+```bash
+git status --porcelain
+```
+- If dirty → HALT with `FAILED / reason: "mobile-common working tree is dirty on {branch} — commit or stash before running figma-cli-skip"`.
+- If clean → checkout and fast-forward:
+  ```bash
+  git checkout iteration/develop
+  git pull --ff-only origin iteration/develop
+  ```
+
+After this step, `mobile-common` must be on `iteration/develop` and even with
+`origin/iteration/develop`.
+
+---
+
+## STEP 2 — Ensure `FigmaRegistryUtility` Is Built
+
+```bash
+cd "${COMMON}"
+if [[ ! -x "${UTILITY}" ]]; then
+  swift build --product FigmaRegistryUtility
+fi
+```
+
+If the build fails → HALT with `FAILED / reason: "FigmaRegistryUtility build failed"` and include the build error tail.
+
+---
+
+## STEP 3 — Process Each URL
+
+For each `(fileKey, nodeId)` pair:
+
+### 3a. Resolve Component Name
+
+```bash
+cd "${COMMON}"
+"${UTILITY}" lookup --node-id '{nodeId-with-colon}'
+```
+
+Parse `suggestedComponentName` from the JSON output. If the lookup fails
+(node not in registry), still proceed — the lookup may return a suggested
+name even for unknown nodes. If no name is returned at all, use the raw
+`{nodeId}` as a placeholder and note it in the summary.
+
+### 3b. Check Existing Registry Entry
+
+Path: `${REGISTRY_DIR}/{nodeId-with-colon-replaced-by-dash}.json`
+
+**If file exists**:
+- Read it.
+- If `"skip": true` is already set → record this component as `ALREADY_SKIPPED` (no changes) and continue to next URL. Do NOT short-circuit the whole batch.
+- If not skipped → overwrite with the skip payload (below). Log that you're overwriting pre-existing implementation data.
+
+**If file does not exist**:
+- Create it with the skip payload.
+
+### 3c. Write the Skip Payload
+
+```json
+{
+  "nodeId": "{nodeId-with-colon}",
+  "componentName": {
+    "ios": "{componentName}",
+    "android": "{componentName}"
+  },
+  "skip": true,
+  "codeConnect": {
+    "ios": false,
+    "android": false
+  },
+  "confluence": {
+    "page": null,
+    "ios": null,
+    "android": null
+  },
+  "fileKey": "{fileKey}",
+  "lastUpdated": "{YYYY-MM-DD}",
+  "updatedBy": "ios",
+  "testingIdentifiers": [],
+  "localizationKeys": [],
+  "accessibilityKeys": [],
+  "analyticsEvents": []
+}
+```
+
+Use the current date (UTC) for `lastUpdated`.
+
+Collect the relative path (`Shared/Figma/Components/{filename}.json`) into a
+`written_files[]` list for later staging.
+
+---
+
+## STEP 4 — Regenerate Catalog
+
+Run once **after all URLs have been processed**, not per-URL:
+
+```bash
+cd "${COMMON}"
+"${UTILITY}" catalog
+```
+
+Capture the list of files the catalog command wrote/modified. In practice
+this writes into `Shared/Figma/Catalog/` (or similar). Use `git status
+--porcelain` to discover everything that changed under `Shared/Figma/` and
+stage those paths explicitly in STEP 5.
+
+If catalog regeneration fails → HALT with `FAILED / reason: "Catalog regeneration failed"`.
+
+---
+
+## STEP 5 — Commit & Push
+
+### 5a. Stage only the intended files
+
+```bash
+cd "${COMMON}"
+# Registry JSONs we wrote
+git add Shared/Figma/Components/{file1}.json Shared/Figma/Components/{file2}.json ...
+# Catalog files the utility regenerated (discover via `git status --porcelain`
+# — stage every modified/untracked path that lives under Shared/Figma/ AND was
+# not already present before STEP 4)
+git add <catalog paths discovered from git status>
+```
+
+**Do NOT** use `git add -A` or `git add .`. If there are unrelated dirty
+files in the working tree (there shouldn't be, STEP 1 guaranteed it), leave
+them alone.
+
+### 5b. Verify the index is what we expect
+
+```bash
+git diff --cached --name-only
+```
+
+Only `Shared/Figma/Components/*.json` and `Shared/Figma/Catalog/*` paths
+should appear. If anything else shows up → HALT with
+`FAILED / reason: "Unexpected files staged: {list}"`.
+
+### 5c. Commit
+
+Commit message format:
+
+- **Single skip**:
+  ```
+  chore(common): skip {componentName} [{nodeId}]
+
+  Reason: {reason or "Not specified"}
+  ```
+- **Batch skip (2+)**:
+  ```
+  chore(common): skip {N} components
+
+  - {componentName1} [{nodeId1}]
+  - {componentName2} [{nodeId2}]
+  - ...
+
+  Reason: {reason or "Not specified"}
+  ```
+
+Pass the body via HEREDOC to preserve formatting:
+
+```bash
+git commit -m "$(cat <<'EOF'
+chore(common): skip {componentName} [{nodeId}]
+
+Reason: {reason or "Not specified"}
+EOF
+)"
+```
+
+Capture the resulting commit SHA from `git rev-parse HEAD`.
+
+### 5d. Push with rebase retry
+
+```bash
+git push origin iteration/develop
+```
+
+**If push is rejected (non-fast-forward)**:
+```bash
+git fetch origin iteration/develop
+git rebase origin/iteration/develop
+git push origin iteration/develop
+```
+Allow up to 3 rebase-retry attempts. If it still fails → HALT with
+`FAILED / reason: "Push rejected after 3 rebase retries"`.
+
+After a successful rebase, re-read the new HEAD SHA for the output.
+
+---
+
+## STEP 6 — Output `ORCHESTRATOR_RESULT`
+
+Output EXACTLY this block as your FINAL message. Nothing else after it.
+
+### On success (single or batch, all components either skipped now or already skipped):
+
+```
+ORCHESTRATOR_RESULT:
+  status: COMPLETE
+  commit: <SHA>
+  pushed: true
+  branch: iteration/develop
+  skipped:
+    - { nodeId: <nodeId>, componentName: <name>, fileKey: <fileKey>, state: NEWLY_SKIPPED }
+    - { nodeId: <nodeId>, componentName: <name>, fileKey: <fileKey>, state: ALREADY_SKIPPED }
+  reason: <reason or "Not specified">
+  summary: <one-line — e.g. "Skipped 2 components, 1 already skipped">
+```
+
+If **all** components were `ALREADY_SKIPPED` (nothing new written, nothing
+committed, nothing pushed), the block looks like:
+
+```
+ORCHESTRATOR_RESULT:
+  status: NOOP
+  commit: —
+  pushed: false
+  branch: iteration/develop
+  skipped:
+    - { nodeId: <nodeId>, componentName: <name>, fileKey: <fileKey>, state: ALREADY_SKIPPED }
+  reason: <reason or "Not specified">
+  summary: All components already skipped
+```
+
+### On failure:
+
+```
+ORCHESTRATOR_RESULT:
+  status: FAILED
+  failedStep: <STEP 0 | 1 | 2 | 3 | 4 | 5>
+  reason: <exact reason>
+  branch: iteration/develop
+  skippedBeforeFailure:
+    - { nodeId: <nodeId>, componentName: <name>, state: <NEWLY_SKIPPED | ALREADY_SKIPPED> }
+  suggestion: <what to fix — e.g. "resolve rebase conflicts manually and re-run">
+```
+
+---
+
+## Error Handling Quick Reference
+
+| Failure | Action |
+|---------|--------|
+| No URLs provided | `FAILED / STEP 0 / "No Figma URL provided"` |
+| Dirty working tree on feature branch | `FAILED / STEP 1 / "mobile-common working tree is dirty"` |
+| Diverged `iteration/develop` | `FAILED / STEP 1 / "mobile-common has diverged from origin"` |
+| `FigmaRegistryUtility` build failure | `FAILED / STEP 2` + build error tail |
+| `FigmaRegistryUtility lookup` returns nothing usable | Continue with `{nodeId}` as placeholder; note in summary |
+| Catalog regeneration failure | `FAILED / STEP 4` |
+| Unexpected files staged | `FAILED / STEP 5 / "Unexpected files staged: ..."` |
+| Push rejected after 3 rebase retries | `FAILED / STEP 5 / "Push rejected after 3 rebase retries"` |