@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-review/SKILL.md

@@ -0,0 +1,395 @@
+# /figma-review — Interactive Code Review for Figma Components
+
+## Purpose
+
+Guided review session for a Figma component implementation. Resolves the component, finds or creates the GitHub issue, shows relevant code, and walks the reviewer through approve/bug/inspect actions.
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `<ComponentName>` or `<IssueNumber>` | Yes | PascalCase component name **or** GitHub issue number |
+
+```
+/figma-review ModalsTitle
+/figma-review CheckinBoardingPassFlightInfo
+/figma-review 175
+```
+
+---
+
+## Constants
+
+```
+REPO_ROOT       = git repo root (auto-detect)
+GH_REPO         = {github.componentsRepo}
+REGISTRY_UTIL   = ${REPO_ROOT}/{repos.common.path}/.build/debug/FigmaRegistryUtility
+PROJECT_ID      = {github.projectV2Id}
+```
+
+---
+
+## STEP 0 — Resolve Component
+
+### Determine input type
+
+If the argument is a number → treat as **issue number**, fetch the issue first and extract `ComponentName` from the issue body's `### Component Name (PascalCase)` field.
+
+If the argument is a string → treat as **ComponentName** and search for the issue by name.
+
+### If input is issue number
+
+```bash
+gh issue view <NUMBER> --repo ${GH_REPO} --json number,title,body,labels,state
+```
+
+Extract `ComponentName` from the body field `### Component Name (PascalCase)`.
+If the field is missing → HALT: "Issue #N does not have a Component Name field."
+
+### Find component files
+
+```bash
+# Find SwiftUI view
+Glob: **/Sources/UIComponents/**/{ComponentName}.swift
+
+# Find configuration
+Glob: **/Sources/UIComponents/**/{ComponentName}Configuration.swift
+
+# Find FIGMA.md
+Glob: **/Sources/UIComponents/**/{ComponentName}/FIGMA.md
+
+# Find tests
+Glob: **/Tests/**/{ComponentName}Tests.swift
+Glob: **/Tests/**/{ComponentName}SnapshotTests.swift
+```
+
+If no `.swift` file found → HALT: "Component `{ComponentName}` not found in codebase."
+
+### Find GitHub issue (if input was ComponentName)
+
+**Primary: node-id search (deterministic)** — if the registry has an entry for this component, look up its nodeId and search for issues whose body references that exact string:
+
+```bash
+# Resolve ComponentName → nodeId via registry
+NODE_ID=$(python3 -c "
+import json, os, glob, sys
+d = '${FIGMA_DIR}/Components'
+for f in glob.glob(os.path.join(d, '*.json')):
+    with open(f) as fh: e = json.load(fh)
+    cn = e.get('componentName') or {}
+    ios = cn.get('ios') if isinstance(cn, dict) else cn
+    if ios == '{ComponentName}':
+        print(e.get('nodeId', ''))
+        sys.exit(0)
+")
+
+if [ -n "$NODE_ID" ]; then
+    gh issue list --repo ${GH_REPO} --state open --search "\"$NODE_ID\" in:body" --json number,title,body,labels,state
+fi
+```
+
+**Fallback: fuzzy name search** — only if node-id lookup returned nothing (component not in registry, or registry not cloned):
+
+```bash
+gh issue list --repo ${GH_REPO} --state open --label component --search "{ComponentName}" --json number,title,body,labels,state
+```
+
+**If issue found:** use it as the parent issue.
+
+**If no issue found:** print and STOP:
+
+```
+No open issue found for {ComponentName}.
+
+1. Create issue now
+2. Continue without issue
+```
+
+- If "1": run the same flow as `/figma-issue open` — registry lookup, create issue, add to board. Then continue.
+- If "2": continue review without issue tracking (no labels, no sub-issues — just code inspection).
+
+### Extract issue metadata
+
+From the issue body:
+- Figma URL, Node ID, Registry Name
+- Jira key (if linked)
+- Current progress checkboxes
+- Existing review status (from labels)
+
+---
+
+## STEP 1 — Show Review Context
+
+## STEP 2 — Review Menu
+
+Print the full review context AND the menu **together in a single output block**, then STOP. Wait for user's response.
+
+```
+═══════════════════════════════════════════════
+  REVIEW: {ComponentName}
+═══════════════════════════════════════════════
+  Issue:    #{N} — {title}
+  Jira:     {JIRA_KEY or "none"}
+  Phase:    {current phase from labels}
+  Review:   {X/4 from label or "not started"}
+  Open bugs: {count of open bug sub-issues}
+───────────────────────────────────────────────
+  Files:
+  • {path}/{ComponentName}.swift
+  • {path}/{ComponentName}Configuration.swift
+  • {path}/FIGMA.md
+  • Tests/{ComponentName}Tests.swift
+  • Tests/{ComponentName}SnapshotTests.swift
+───────────────────────────────────────────────
+  Recent:
+  {git log --oneline --since="7 days ago"}
+═══════════════════════════════════════════════
+
+What would you like to do?
+
+1. Open in Xcode
+2. Open in Xcode + Figma
+3. Approve
+4. Open bug
+5. Status (review progress)
+6. Done (exit review)
+```
+
+### Action: `1` — Open in Xcode
+
+Find the component's Swift file using Glob, then open it:
+
+```bash
+open -a Xcode "<resolved_path>"
+```
+
+Return to menu.
+
+### Action: `2` — Open in Xcode + Figma
+
+1. Open the Swift file in Xcode (same as Action 1):
+```bash
+open -a Xcode "<resolved_path>"
+```
+
+2. Build the Figma URL from issue metadata (`Figma URL` field). Open in Figma desktop app if installed, otherwise fall back to browser:
+```bash
+# Check if Figma desktop app is installed
+if [ -d "/Applications/Figma.app" ]; then
+  # Convert https://www.figma.com/design/... to figma://file/...
+  FIGMA_URL="{figma_url_from_issue}"
+  FIGMA_DEEP_LINK=$(echo "$FIGMA_URL" | sed 's|https://www.figma.com/design/|figma://file/|')
+  open "$FIGMA_DEEP_LINK"
+else
+  open "{figma_url_from_issue}"
+fi
+```
+
+Return to menu.
+
+### Action: `3` — Approve
+
+1. Get current reviewer's GitHub username:
+```bash
+gh api user --jq '.login'
+```
+
+2. Read issue body. Find `### Review` section. Check the reviewer's checkbox:
+   - Find `- [ ] @{username}` → replace with `- [x] @{username}`
+   - If reviewer not in the list → add `- [x] @{username}`
+
+3. Update issue body:
+```bash
+gh issue edit <N> --repo ${GH_REPO} --body "<UPDATED_BODY>"
+```
+
+4. Count approvals (`- [x]` entries). Update label:
+```bash
+# Remove old review label
+EXISTING=$(gh issue view <N> --repo ${GH_REPO} --json labels --jq '.labels[].name | select(startswith("review:"))' | head -1)
+[ -n "$EXISTING" ] && gh issue edit <N> --repo ${GH_REPO} --remove-label "$EXISTING"
+# Add new one (always out of 4)
+gh issue edit <N> --repo ${GH_REPO} --add-label "review:{APPROVED}/4"
+```
+
+5. Add comment:
+```bash
+gh issue comment <N> --repo ${GH_REPO} --body "Approved by @{username}"
+```
+
+6. If `review:4/4` AND no open bug sub-issues → print: "All 4 reviews complete. No open bugs. Ready to close with `/figma-issue close #N`."
+
+Print: "Approved. Review status: {APPROVED}/4"
+
+Return to menu.
+
+### Action: `4` — Open bug
+
+Print and STOP:
+
+```
+Describe the bug:
+```
+
+Wait for user's response. Capture as `BUG_DESCRIPTION`.
+
+Then ask via **AskUserQuestion** (discrete options only — no free text):
+
+```
+Question: "Bug severity?"
+Options:
+  - label: "Minor"  description: "Cosmetic, non-blocking — label bug-minor"
+  - label: "Major"  description: "Functional issue, must fix — label bug-major"
+```
+
+The answer drives a label, not a free-text comparison. Map:
+- "Minor" → add label `bug-minor`
+- "Major" → add label `bug-major`
+
+No "is this minor or major?" prose parsing. The label is the source of truth.
+
+Get the parent issue's assignee so the bug is assigned to the implementor:
+
+```bash
+PARENT_ASSIGNEE=$(gh issue view <PARENT_ISSUE_NUMBER> --repo ${GH_REPO} --json assignees --jq '.assignees[0].login // empty')
+```
+
+Create bug sub-issue (assigned to parent's assignee):
+
+```bash
+gh issue create --repo ${GH_REPO} \
+  --title "bug({ComponentName}): {short description from first line}" \
+  --label "bug" \
+  --label "review-fix" \
+  ${PARENT_ASSIGNEE:+-a "$PARENT_ASSIGNEE"} \
+  --body "$(cat <<'EOF'
+## Parent
+
+Closes #{PARENT_ISSUE_NUMBER}
+
+## Component
+
+{ComponentName}
+
+## Description
+
+{BUG_DESCRIPTION}
+
+## Severity
+
+{Minor/Major}
+
+## Reporter
+
+@{username}
+EOF
+)"
+```
+
+Add the bug as a sub-issue to the parent:
+
+```bash
+# Get sub-issue node ID
+BUG_NODE_ID=$(gh api graphql -f query='{ repository(owner: "{github.org}", name: "{project.slug}-components") { issue(number: <BUG_NUMBER>) { id } } }' --jq '.data.repository.issue.id')
+
+# Get parent issue node ID
+PARENT_NODE_ID=$(gh api graphql -f query='{ repository(owner: "{github.org}", name: "{project.slug}-components") { issue(number: <PARENT_NUMBER>) { id } } }' --jq '.data.repository.issue.id')
+
+# Link as sub-issue
+gh api repos/${GH_REPO}/issues/<PARENT_NUMBER>/sub_issues --method POST -f sub_issue_id="$BUG_NODE_ID"
+```
+
+Add `review-fix` label to parent issue:
+```bash
+gh issue edit <PARENT_NUMBER> --repo ${GH_REPO} --add-label "review-fix"
+```
+
+Print: "Bug #M created and linked to #N."
+
+Return to menu.
+
+### Action: `5` — Status
+
+Show detailed review progress:
+
+```
+Review Status: {ComponentName} (#N)
+
+Approvals: {COUNT}/4
+  ✅ @reviewer1 — approved 2026-03-22
+  ✅ @reviewer2 — approved 2026-03-22
+  ⬜ @reviewer3
+  ⬜ @reviewer4
+
+Open Bugs: {COUNT}
+  🔴 #108 — dark mode text color wrong (Major)
+  🟡 #109 — RTL padding missing (Minor)
+
+Closed Bugs: {COUNT}
+  ✅ #110 — wrong font token (fixed)
+```
+
+Fetch sub-issues:
+```bash
+gh api graphql -f query='{ repository(owner: "{github.org}", name: "{project.slug}-components") { issue(number: <N>) { subIssues(first: 50) { nodes { number title state labels(first: 5) { nodes { name } } } } } } }'
+```
+
+Return to menu.
+
+### Action: `6` — Done
+
+Print: "Review session ended." Exit.
+
+---
+
+## Review Setup (first time)
+
+When STEP 1 detects no `### Review` section in the issue body:
+
+1. Get the triggering user's GitHub username:
+```bash
+gh api user --jq '.login'
+```
+
+2. Add them as the first reviewer, **unchecked** (pending — they must use Action 3 to formally approve):
+
+```markdown
+### Review
+
+- [ ] @{current_username}
+```
+
+3. Update the issue body with the `### Review` section.
+
+4. Update label:
+```bash
+gh issue edit <N> --repo ${GH_REPO} --add-label "review:0/4"
+```
+
+5. Print:
+```
+You've been added as reviewer (@{current_username}). Review requires 4 approvals.
+Other reviewers can be added via the GitHub issue or by running /figma-review.
+```
+
+6. Continue to STEP 2 (review menu) — no need to stop again.
+
+---
+
+## Labels Used
+
+| Label | Purpose |
+|-------|---------|
+| `review:X/4` | X of 4 reviewers approved (required: 4) |
+| `review-fix` | Has open bugs from review |
+| `bug` | Bug sub-issue |
+
+---
+
+## Error Handling
+
+- **Component not found**: HALT with message.
+- **No issue + user chooses "continue without"**: Code-only review, no labels/tracking.
+- **Reviewer already approved**: Skip, print "Already approved."
+- **Sub-issues API unavailable**: Fall back to linking via comment reference (`Blocked by #N`).
+- **FigmaRegistryUtility not built**: Prompt to build.