@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-2-orchestrator.md

@@ -0,0 +1,333 @@
+# PHASE 2 — Utility Integration Orchestrator
+
+Orchestrates Phase 2 sub-phases: dispatches sub-agents, collects results, writes pass2/_index.md.
+PREV: Phase 1.5 (Existing Component Discovery)
+NEXT: Phase 3 (Data Analysis)
+
+---
+
+## ENTRY GATE — discovery status
+
+Phase 2 reads `agent-state.discovery.status` written by Phase 1.5:
+
+| `discovery.status` | Phase 2 action |
+|---|---|
+| `GREENFIELD_OK` (or absent for backward compat) | EXECUTE — run all sub-phases below |
+| `GAP_ANALYSIS` | SKIP — Phase 2 outputs are not needed; jump to Phase 4 (only run Documentation / Code Connect / tests / wiki sub-phases that target the gap list) |
+| `ALREADY_MAPPED` (no user override) | SKIP — same as `GAP_ANALYSIS` |
+| `EXISTING_SOURCE_NO_CC` (publish-only path picked) | SKIP — jump to Phase 6 |
+| `CANCELLED` | HALT |
+| Any other value | HALT — unknown discovery state, refuse to proceed |
+
+If `discovery` field is absent on `agent-state.json`, log a one-line warning ("phase-1.5 not run; assuming GREENFIELD_OK") and proceed. This preserves backward compatibility with runs started before the discovery gate existed.
+
+---
+
+## IMPLEMENTATION_MODULE
+
+All utilities from this phase are consumed via `UIComponentUtilities`:
+
+```swift
+import UIComponentUtilities
+```
+
+| Category | Extension | Usage |
+|----------|-----------|-------|
+| Testing | `View.accessibilityIdentifier(_ key: UITestingIdentifierKey)` | `.accessibilityIdentifier(.ComponentName.element)` |
+| Localization | `Text(_ key: LocalizationStringKey)` | `Text(.ComponentName.title)` |
+| Accessibility | `View.accessibilityLabel(_ key: LocalizedAccessibilityStringKey)` | Only when SwiftUI can't read visible text — many components need NO accessibility modifiers |
+| Analytics | `View.analyticsButton(id:label:type:)` | `.analyticsButton(id: "id", label: "Submit", type: .primary)` |
+
+SOURCE: `Sources/UIComponentUtilities/`
+
+---
+
+## PRE-CHECK: Phase 1 Complete
+
+```
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+Read: {artifactPath}/pass1/_index.md
+```
+
+EXTRACT:
+- `componentName`
+- `artifactPath`
+- `nodeId`
+- `fileKey`
+
+| Result | Action |
+|--------|--------|
+| Both files exist | Proceed to REGISTRY_LOOKUP |
+| Either missing | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-2
+GATE: PRE_CHECK
+REASON: IMPLEMENTATION_HISTORY.md or pass1/_index.md not found. Phase 1 must complete first.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 1 first.
+```
+
+Verify `pass2/` directory exists. If not:
+
+```bash
+mkdir -p {artifactPath}/pass2
+```
+
+---
+
+## NORMALIZE_DESIGN_CONTEXT: Handle Sublayer Format
+
+Phase 1 script may produce a sublayer format for large components. Normalize it before dispatching sub-phases so they always see a single `response` field.
+
+```
+Read: {artifactPath}/pass1/design_context_response.json
+```
+
+Check the JSON structure:
+
+| Format | Detection | Action |
+|--------|-----------|--------|
+| Normal | `sublayers` is `false` or absent | No action needed — `response` field exists |
+| Sublayer | `sublayers` is `true` | Concatenate all `responses` values (see below) |
+
+### Sublayer normalization
+
+If `sublayers: true`:
+
+1. Read all values from the `responses` object (keyed by node ID, e.g. `"123:456": "...code..."`)
+2. Concatenate them into a single string, separated by `\n\n// --- Sublayer: {nodeId} ---\n\n`
+3. Add a `response` field to the JSON with the concatenated string
+4. Keep the original `sublayers`, `sublayerNodeIds`, and `responses` fields intact (for traceability)
+5. Write the updated JSON back to `{artifactPath}/pass1/design_context_response.json`
+
+After normalization, all sub-phases read the `response` field as usual — no sublayer awareness needed.
+
+```json
+{
+  "sublayers": true,
+  "sublayerNodeIds": ["123:456", "789:012"],
+  "responses": { "123:456": "...code...", "789:012": "...code..." },
+  "response": "...concatenated code from all sublayers..."
+}
+```
+
+---
+
+## REGISTRY_LOOKUP: Check Pre-existing Keys
+
+Lookup whether this component already has utility keys registered (e.g., by Android or a previous iOS run).
+
+```bash
+cd {repos.common.path} && .build/debug/FigmaRegistryUtility utility-lookup --node-id '{nodeId}'
+```
+
+> **If binary not found:** `swift build --package-path {repos.common.path} --product FigmaRegistryUtility`
+
+| Result | Action |
+|--------|--------|
+| Returns JSON with keys | Pass pre-existing keys to each sub-phase as `registryData` input |
+| Returns `{}` (empty) | Proceed normally (fresh generation) |
+| Tool error | Log warning, proceed without registry data (non-blocking) |
+
+The `registryData` is passed to sub-phases so they can:
+- Skip CLI check calls for keys already in the registry AND in the data files
+- Merge new keys with existing ones instead of duplicating
+
+---
+
+## ROUTING
+
+### Sub-phase inventory
+
+| Sub-phase | Skill Doc | Purpose | Required | Depends On |
+|-----------|-----------|---------|----------|------------|
+| 2A | `phase-2a-testing-identifiers.md` | UI testing identifiers | **ALWAYS** | Phase 1 |
+| 2B | `phase-2b-localization.md` | Localized display text | If visible text exists | Phase 1 |
+| 2C | `phase-2c-accessibility.md` | VoiceOver labels/hints | **ALWAYS** | Phase 1 |
+| 2D | `phase-2d-analytics.md` | Event tracking | If interactive elements exist | Phase 1 + **2A** |
+
+### Execution flow
+
+```
+PRE-CHECK
+    ↓
+NORMALIZE_DESIGN_CONTEXT
+    ↓
+REGISTRY_LOOKUP
+    ↓
+┌───────────────────────────────────┐
+│  PARALLEL DISPATCH (sub-agents)   │
+│                                   │
+│   2A — Testing Identifiers        │  ← required
+│   2B — Localization Keys          │  ← if visible text
+│   2C — Accessibility Keys         │  ← required
+│                                   │
+└───────────────────────────────────┘
+    ↓ wait for all to complete
+    ↓
+    2D — Analytics Events              ← if interactive elements (depends on 2A output)
+    ↓
+COLLECT RESULTS
+    ↓
+UPDATE_IMPLEMENTATION_HISTORY
+    ↓
+WRITE_PASS2_INDEX
+    ↓
+PHASE OUTPUT
+```
+
+### Dispatch instructions
+
+**Wave 1 (parallel):** Launch 2A, 2B, 2C as sub-agents simultaneously.
+- Each reads `pass1/_index.md` independently.
+- Each writes its own artifact to `pass2/`.
+- Wait for ALL to complete before proceeding.
+
+**Wave 2 (sequential):** Launch 2D after Wave 1 completes.
+- 2D requires `pass2/utility_identifiers.md` from 2A (uses testing identifiers as analytics event IDs).
+- Skip 2D if no interactive elements found in `pass1/design_context_response.json`.
+
+### Skip conditions
+
+| Sub-phase | Skip when |
+|-----------|-----------|
+| 2B | No visible text in design_context_response.json |
+| 2D | No interactive elements (buttons, links, toggles, cards) in design_context_response.json |
+
+If skipped, write a placeholder artifact:
+
+```markdown
+# {Category}: {componentName}
+
+No {category} required for this component.
+Generated: {ISO_DATE}
+Reason: No {condition} found in design context.
+```
+
+---
+
+## GATE 1: COLLECT_RESULTS
+
+After all sub-phases complete, verify each produced its artifacts (both JSON sidecar and markdown):
+
+```
+[ ] pass2/utility_identifiers.md exists (Phase 2A)
+[ ] pass2/utility_identifiers.json exists (Phase 2A — JSON sidecar)
+[ ] pass2/utility_localization.md exists (Phase 2B — or skipped placeholder)
+[ ] pass2/utility_localization.json exists (Phase 2B — JSON sidecar)
+[ ] pass2/utility_accessibility.md exists (Phase 2C)
+[ ] pass2/utility_accessibility.json exists (Phase 2C — JSON sidecar)
+[ ] pass2/utility_analytics.md exists (Phase 2D — or skipped placeholder)
+[ ] pass2/utility_analytics.json exists (Phase 2D — JSON sidecar)
+```
+
+ANY markdown missing →
+```
+STATUS: HALT
+PHASE: phase-2
+GATE: COLLECT_RESULTS
+REASON: Sub-phase artifact missing.
+MISSING: [list missing files]
+USER_ACTION_REQUIRED: Re-run the failed sub-phase.
+```
+
+If a JSON sidecar is missing but the markdown exists, the finalize script will log a warning and use empty arrays — this is non-blocking.
+
+---
+
+## GATE 2: FINALIZE (script)
+
+**IMPORTANT:** Do NOT read sub-phase markdown files in the main orchestrator context. The finalize script handles everything: building component-utilities.json, registering, and writing _index.md.
+
+```bash
+python3 {skillPath}/scripts/phase2-finalize.py \
+    --artifact-path '{artifactPath}' \
+    --node-id '{nodeId}' \
+    --file-key '{fileKey}' \
+    --component-name '{componentName}'
+```
+
+The script:
+1. Reads the 4 JSON sidecar files (NOT the markdowns)
+2. Builds `pass2/component-utilities.json`
+3. Registers via `FigmaRegistryUtility utility-register`
+4. Writes `pass2/_index.md`
+5. Outputs a JSON summary to stdout
+
+Parse the stdout JSON:
+```json
+{"status": "ok", "testing": 5, "localization": 0, "accessibility": 0, "analytics": 0, "registry": true}
+```
+
+| Result | Action |
+|--------|--------|
+| `status: "ok"` | Use counts for IMPLEMENTATION_HISTORY.md update |
+| `status: "error"` | HALT with error message |
+
+---
+
+## GATE 3: UPDATE_IMPLEMENTATION_HISTORY
+
+Using the counts from the finalize script output, append to `{artifactPath}/IMPLEMENTATION_HISTORY.md`:
+
+```markdown
+## Phase 2: Utility Integration
+- Testing Identifiers: ✅ pass2/utility_identifiers.md ({testing} added)
+- Localization Keys: ✅ pass2/utility_localization.md ({localization} keys) | ⏭️ Skipped (no visible text)
+- Accessibility Keys: ✅ pass2/utility_accessibility.md ({accessibility} keys)
+- Analytics Events: ✅ pass2/utility_analytics.md ({analytics} events) | ⏭️ Skipped (no interactive elements)
+- Registry: ✅ {repos.common.path}/Shared/Figma/Components/{nodeId}.json updated | ⚠️ Registry update failed (non-blocking)
+- Completed: {DATE}
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] IMPLEMENTATION_HISTORY.md loaded from Phase 1
+[ ] design_context_response.json normalized (sublayer → flat response field)
+[ ] Registry lookup performed (utility-lookup)
+[ ] Pre-existing keys passed to sub-phases (if registry data found)
+[ ] Phase 2A completed — utility_identifiers.md + .json exists (required)
+[ ] Phase 2B completed — utility_localization.md + .json exists (or skipped with placeholder)
+[ ] Phase 2C completed — utility_accessibility.md + .json exists (required)
+[ ] Phase 2D completed — utility_analytics.md + .json exists (or skipped with placeholder)
+[ ] phase2-finalize.py ran successfully (builds component-utilities.json, registers, writes _index.md)
+[ ] IMPLEMENTATION_HISTORY.md updated with Phase 2 summary (using script output counts)
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-2
+GATES_PASSED: [PRE_CHECK, NORMALIZE_DESIGN_CONTEXT, REGISTRY_LOOKUP, DISPATCH_WAVE_1, DISPATCH_WAVE_2, COLLECT_RESULTS, FINALIZE, UPDATE_IMPLEMENTATION_HISTORY]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass2/utility_identifiers.json + .md (via Phase 2A)
+  - {artifactPath}/pass2/utility_localization.json + .md (via Phase 2B)
+  - {artifactPath}/pass2/utility_accessibility.json + .md (via Phase 2C)
+  - {artifactPath}/pass2/utility_analytics.json + .md (via Phase 2D)
+  - {artifactPath}/pass2/component-utilities.json (via finalize script)
+  - {artifactPath}/pass2/_index.md (via finalize script)
+  - {repos.common.path}/Shared/Figma/Components/{nodeId}.json (via finalize script registry)
+SUMMARY: Utility integration complete. {testing} testing, {localization} loc, {accessibility} a11y, {analytics} analytics. Registry updated.
+```
+
+---
+
+## REFERENCES
+
+| Topic | File |
+|-------|------|
+| Phase 2A | `phases/phase-2a-testing-identifiers.md` |
+| Phase 2B | `phases/phase-2b-localization.md` |
+| Phase 2C | `phases/phase-2c-accessibility.md` |
+| Phase 2D | `phases/phase-2d-analytics.md` |
+| UIComponentUtilities | `Sources/UIComponentUtilities/` |

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-2a-testing-identifiers.md

@@ -0,0 +1,368 @@
+# PHASE 2A — Testing Identifiers
+
+UI testing identifier integration.
+REF: `reference/testing-identifiers-naming.md`
+
+required — always execute this phase.
+PARALLEL WITH: Phase 2B, Phase 2C (all read from pass1/_index.md independently)
+NEXT: Phase 2D (depends on this phase's output)
+
+---
+
+## IMPLEMENTATION_PATTERN
+
+Extension: `Sources/UIComponentUtilities/TestingIdentifiers/View+UITestingIdentifierKey.swift`
+
+```swift
+import UIComponentUtilities
+
+// Static identifier
+Button("Submit") { }
+    .accessibilityIdentifier(.ComponentName.submitButton)
+
+// Dynamic identifier (list items)
+ForEach(items.indices, id: \.self) { index in
+    ItemRow(item: items[index])
+        .accessibilityIdentifier(.ComponentName.Item.row.with(index))
+}
+```
+
+---
+
+## PRE-CHECK: Phase 1 Complete
+
+```
+Read: {artifactPath}/pass1/_index.md
+```
+
+Verify this file exists and lists the expected Phase 1 output files.
+
+Then read the files needed for this phase:
+- `{artifactPath}/pass1/design_context_response.json`
+- `{artifactPath}/pass1/component_properties.json`
+
+Also read:
+- `{artifactPath}/IMPLEMENTATION_HISTORY.md`
+
+Extract: `componentName`, `artifactPath`, `nodeId`, `fileKey`.
+
+### Registry Input (optional)
+
+The orchestrator may pass `registryData` containing pre-existing keys from `{repos.common.path}/Shared/Figma/Components/{nodeId}.json`.
+If `registryData.testingIdentifiers` exists and is non-empty, use it to pre-populate the identifiers list.
+Keys found in both registry AND the data files can be marked "Existing" immediately (skip CLI check in GATE 4).
+
+If any required file is missing:
+
+```
+STATUS: HALT
+PHASE: phase-2a
+GATE: PRE_CHECK
+REASON: Required Phase 1 artifacts missing. Pass1/_index.md or referenced files not found.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 1 first to gather Figma data.
+```
+
+---
+
+## CONTEXT-AWARE IDENTIFIERS
+
+Components are reusable — the same `TurkishButton` appears in many screens.
+Testing identifiers cascade via `UIIdentifierContext` (SwiftUI EnvironmentKey).
+
+### How It Works
+
+Parent views set context using `UITestingIdentifierKey` or raw strings:
+
+```swift
+// Type-safe (recommended) — uses key's identifier string as segment
+PassengerListView()
+    .identifierContext(.PassengerList.screen)
+
+// Raw string (fallback)
+SearchSection()
+    .identifierContext("search")
+```
+
+Child components use standard `.accessibilityIdentifier(.Component.element)` —
+the context is prepended automatically:
+
+```
+context = ["passenger_list", "search"]
+.accessibilityIdentifier(.TurkishButton.button)
+→ "passenger_list_search_turkishbutton_button"
+```
+
+### What Phase 2A Generates
+
+Phase 2A generates **component-level** identifiers only (e.g., `TurkishButton.button`).
+Context prefixes are NOT baked into component identifiers — they come from the
+parent view hierarchy at runtime via `.identifierContext()`.
+
+### Artifact Guidance
+
+In the Implementation section of `utility_identifiers.md`, include a note:
+
+> **Context**: These identifiers support hierarchical context via `.identifierContext()`.
+> Parent screens should set `.identifierContext(.ScreenKey.name)` to disambiguate
+> reusable components. The component itself does NOT need modification.
+> Use `.testIdentifier()` as an alias for `.accessibilityIdentifier()`.
+
+---
+
+## GATE 1: COLLECT_REQUIREMENTS
+
+| Priority | Source | Check |
+|----------|--------|-------|
+| 1 | User prompt | Explicit identifier requests |
+| 2 | Attached file | README.md, Confluence export, screenshot |
+| 3 | Generated | From design_context_response.json |
+
+USE: Merge all sources. User input overrides generated.
+
+---
+
+## GATE 2: GENERATE_FROM_DESIGN_CONTEXT
+
+INPUT: `{artifactPath}/pass1/design_context_response.json`
+INPUT: `{artifactPath}/pass1/component_properties.json`
+
+SCAN for:
+
+| Node Pattern | Identifier Type | Key Suffix |
+|--------------|-----------------|------------|
+| Root text element | Static | `.title` |
+| Button/link element | Static | `.submitButton`, `.link` |
+| Repeated sibling structure | Dynamic | `.Item.row` |
+| Input field | Static | `.input` |
+| Card container | Static | `.card` |
+| Image element | Static | `.image` |
+| Close/dismiss button | Static | `.closeButton` |
+| Header text | Static | `.header` |
+| Badge/tag | Static | `.badge` |
+
+Also use `component_properties.json` to identify:
+- Variant properties → identifier per variant state
+- Boolean properties → identifiers for togglable elements
+- Text slots → identifiers for text elements
+- Nested components → identifiers for sub-component containers
+
+OUTPUT: List of `{ key, value, usage }`.
+
+---
+
+## GATE 3: VALIDATE_NAMING
+
+REF: `reference/testing-identifiers-naming.md`
+
+| Pattern | Key Format (PascalCase.Dot) | Value Format (snake_case) |
+|---------|------------|--------------|
+| Static | `<ComponentName>.<Element>` | `<componentname>_<element>` |
+| List Item | `<ComponentName>.Item.<Element>` | `<componentname>_item_<element>_%@` |
+| Variant | `<ComponentName>.Item.<Variant>` | `<componentname>_item_<variant>_%@` |
+
+VALIDATE each identifier:
+- Key follows PascalCase.Dot.Notation
+- Value is snake_case
+- Value length ≤ 100 characters
+- No spaces or special characters in value
+- Unique within component scope
+- Max 5 levels in key hierarchy
+
+If any identifier fails validation, fix it before proceeding.
+
+---
+
+## GATE 4: CHECK_EXISTING_IDENTIFIERS
+
+### Registry fast-path
+
+If `registryData.testingIdentifiers` contains this key, run the CLI check to confirm it still exists in the data file.
+If both registry AND CLI confirm → mark "Existing" immediately.
+If registry has it but CLI says not found → mark "To Add" (re-add it).
+
+### CLI check
+
+For each identifier in the list, check if it already exists:
+
+```bash
+{repos.common.path}/.build/debug/UITestingIdentifierTool check --key '<KEY>'
+```
+
+> **If binary not found:** `swift build --package-path {repos.common.path} --product UITestingIdentifierTool`
+
+OUTPUT:
+```
+✅ Key exists: <KEY>
+   Value: <VALUE>
+```
+or
+```
+❌ Key not found: <KEY>
+```
+
+| Result | Action |
+|--------|--------|
+| `✅ Key exists` | Mark status: "Existing" |
+| `❌ Key not found` | Mark status: "To Add" |
+
+FAIL (tool error) →
+```
+STATUS: HALT
+PHASE: phase-2a
+GATE: CHECK_EXISTING_IDENTIFIERS
+REASON: UITestingIdentifierTool failed.
+COMPLETED_GATES: [PRE_CHECK, COLLECT_REQUIREMENTS, GENERATE_FROM_DESIGN_CONTEXT, VALIDATE_NAMING]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Retry command
+  2) Build tool first: swift build --package-path {repos.common.path} --product UITestingIdentifierTool
+  3) Skip identifier integration
+```
+
+---
+
+## GATE 5: ADD_MISSING_IDENTIFIERS
+
+For each identifier with status "To Add":
+
+```bash
+{repos.common.path}/.build/debug/UITestingIdentifierTool add --key '<KEY>' --value '<VALUE>'
+```
+
+OUTPUT:
+```
+✅ Added: <KEY> = <VALUE>
+```
+
+After all additions, generate Swift code:
+
+```bash
+{repos.common.path}/.build/debug/UITestingIdentifierTool generate
+```
+
+OUTPUT:
+```
+✅ Generated iOS code: iOS/Sources/UITestingIdentifiers/Generated/UITestingIdentifierKeys.swift
+```
+
+| Result | Action |
+|--------|--------|
+| All succeeded | Proceed to GATE 6 |
+| Any failed | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-2a
+GATE: ADD_MISSING_IDENTIFIERS
+REASON: Failed to add identifier or generate code.
+COMPLETED_GATES: [PRE_CHECK, COLLECT_REQUIREMENTS, GENERATE_FROM_DESIGN_CONTEXT, VALIDATE_NAMING, CHECK_EXISTING_IDENTIFIERS]
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Options:
+  1) Retry failed command
+  2) Skip this identifier and continue
+  3) Skip identifier integration entirely
+```
+
+---
+
+## GATE 6: WRITE_ARTIFACT
+
+### JSON Sidecar (machine-readable)
+
+Write `{artifactPath}/pass2/utility_identifiers.json`:
+
+```json
+{
+  "testingIdentifiers": [
+    { "key": "ComponentName.element", "value": "componentname_element", "usage": "Element description" }
+  ]
+}
+```
+
+This JSON is consumed by `phase2-finalize.py` to build `component-utilities.json`. The orchestrator reads ONLY this JSON — never the markdown.
+
+### Markdown Artifact (human-readable)
+
+Write `{artifactPath}/pass2/utility_identifiers.md`:
+
+```markdown
+# Testing Identifiers
+
+Component: {componentName}
+Generated: {ISO_DATE}
+Source: pass1/design_context_response.json, pass1/component_properties.json
+
+## Identifiers
+
+| Key | Value | Status | Usage |
+|-----|-------|--------|-------|
+| {ComponentName}.title | {componentname}_title | Added | Title label |
+| {ComponentName}.submitButton | {componentname}_submit_button | Added | Submit button |
+| {ComponentName}.closeButton | {componentname}_close_button | Existing | Close button |
+| {ComponentName}.Item.row | {componentname}_item_row_%@ | Added | Row (dynamic) |
+
+## Implementation
+
+```swift
+import UIComponentUtilities
+
+// Static identifier
+Text(title)
+    .accessibilityIdentifier(.{ComponentName}.title)
+
+Button("Submit") { }
+    .accessibilityIdentifier(.{ComponentName}.submitButton)
+
+// Dynamic identifier (list items)
+ForEach(items.indices, id: \.self) { index in
+    ItemRow(item: items[index])
+        .accessibilityIdentifier(.{ComponentName}.Item.row.with(index))
+}
+
+// With analytics (identifiers used as analytics IDs)
+Button("Submit") { }
+    .accessibilityIdentifier(.{ComponentName}.submitButton)
+    .analyticsButton(
+        id: UITestingIdentifierKey.{ComponentName}.submitButton.description,
+        label: "Submit",
+        type: .primary
+    )
+```
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+Before marking complete, verify:
+
+```
+[ ] All text elements in design_context have identifiers
+[ ] All interactive elements have identifiers
+[ ] All list/repeated structures have dynamic identifiers with %@
+[ ] Key format: PascalCase.Dot.Notation
+[ ] Value format: snake_case, ≤100 chars
+[ ] No duplicate keys within component scope
+[ ] UITestingIdentifierTool check passes for all added keys
+[ ] UITestingIdentifierTool generate completed successfully
+[ ] utility_identifiers.json written to pass2/ (JSON sidecar for finalize script)
+[ ] utility_identifiers.md written to pass2/
+[ ] Implementation section shows correct import and usage patterns
+```
+
+---
+
+## SUCCESS OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-2a
+GATES_PASSED: [PRE_CHECK, COLLECT_REQUIREMENTS, GENERATE_FROM_DESIGN_CONTEXT, VALIDATE_NAMING, CHECK_EXISTING_IDENTIFIERS, ADD_MISSING_IDENTIFIERS, WRITE_ARTIFACT]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass2/utility_identifiers.json
+  - {artifactPath}/pass2/utility_identifiers.md
+SUMMARY: Testing identifiers: {ADDED} added, {EXISTING} existing.
+```