visual-component-finder

[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.

Find the Angular component(s) matching this screenshot: $ARGUMENTS

Quick Summary

Goal: Match screenshots to existing Angular components in the codebase for code reuse.

Workflow:

1. Analyze — Process screenshot with vision capabilities
2. Search — Grep/glob for matching component patterns in frontend source directories
3. Match — Return component paths with similarity assessment

Key Rules:

• Auto-activated when user provides UI screenshots
• Search shared component library, domain libraries, and app-specific components
• Report exact component file paths and usage examples

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Prerequisites

• MUST ATTENTION READ references/anti-hallucination-protocol.md before any output
• MUST ATTENTION READ references/matching-algorithm.md for the 6-step protocol

Workflow

Step 1: Load Component Index

Read docs/component-index.json. If missing or stale, regenerate:

# Full scan — rebuild entire index from all source files
python .claude/skills/visual-component-finder/scripts/build-component-index.py

# Incremental — only re-index files changed since last commit (fast)
python .claude/skills/visual-component-finder/scripts/build-component-index.py --git-changes

# Incremental — changes since a specific branch/ref
python .claude/skills/visual-component-finder/scripts/build-component-index.py --git-changes main

When to use which:

• --git-changes — after pulling new code or switching branches (seconds, not minutes)
• No flag (full scan) — first-time build, or when index seems corrupted/stale

Step 2: Analyze Screenshot

Use the Read tool on the screenshot image. Extract visual fingerprint:

• Visible text (headers, labels, button text, table columns)
• Layout pattern (sidebar+content, table, form, card grid, modal)
• URL path (if browser bar visible)
• BEM class patterns (if DevTools open)
• App identification (detect from project config, URL, or port mapping)

Step 3: Match Components

Follow the Signal Checklist in references/matching-algorithm.md:

• Check 6 boolean signals (S1-S6) against index
• Calculate confidence from signal count
• If 0-1 signals matched, run Live Grep Fallback (Step 6)

Step 4: Generate Component Graph

Follow references/component-graph-template.md to output Mermaid relationship diagram.

Step 5: Output Results

Report with: matched component(s), confidence %, evidence per signal, file paths, relationship graph.

Disambiguation

• Intent is to find/modify existing code → THIS skill
• Intent is to create new UI from screenshot → defer to design-screenshot
• Intent is to describe a design → defer to design-describe

Workflow Positioning

When attached to bugfix/feature/refactor prompts, this skill runs before /scout.

Important Notes

• Every match MUST ATTENTION cite file:line evidence — see anti-hallucination protocol
• Show ranked candidates when confidence <85%
• Detect reusable components (in libs/) and trace to page consumers
• Index covers all frontend application versions

---

Closing Reminders

• IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting
• IMPORTANT MUST ATTENTION search codebase for 3+ similar patterns before creating new code
• IMPORTANT MUST ATTENTION cite file:line evidence for every claim (confidence >80% to act)
• IMPORTANT MUST ATTENTION add a final review todo task to verify work quality MANDATORY IMPORTANT MUST ATTENTION READ the following files before starting:
• IMPORTANT MUST ATTENTION READ references/anti-hallucination-protocol.md before starting
• IMPORTANT MUST ATTENTION READ references/matching-algorithm.md before starting