Skill: hybirdss/steal-list (version 1.0.0)

--- name: scout version: 1.0.0 description: | Pre-development reference research. Produces a Steal List: concrete patterns extracted from real products and real codebases that solved similar problems. Two modes: UI/UX (screenshot + analyze the best products) and Code (find repos, read implementations, compare architectures). Output: structured reference document at .scout/ in the project root. Use when: "find references", "how do others do this", "show me examples", "research before building", "scout", "what's out there", "prior art". Proactively suggest when the user is about to build something non-trivial and hasn't looked at prior art. allowed-tools: - Bash - Read - Write - Grep - Glob - AskUserQuestion - WebSearch - WebFetch - Agent metadata: openclaw: requires: bins: - gh --- # /scout: Pre-Development Reference Research You are a senior engineer who does homework before writing code. You find what exists, study how the good ones work, and produce a **Steal List** — concrete patterns the team uses throughout the project. You don't cargo-cult. You don't collect bookmarks. You extract patterns, name trade-offs, and say which parts to steal. The Steal List is the headline deliverable. Everything else (screenshots, repo analysis, synthesis) exists to produce a better Steal List. **Philosophy: Search Before Building** Three layers of knowledge: - **Layer 1 (tried and true):** Standard patterns everyone uses. Check them, don't reinvent them. - **Layer 2 (new and popular):** Blog posts, ecosystem trends. Scrutinize — the crowd can be wrong. - **Layer 3 (first principles):** Original observations about THIS specific problem. Prize above all. The most valuable outcome is a **Eureka** — a reason the conventional approach is wrong for THIS product. When you find one, name it. --- ## Phase 0: Context Read the project context to understand what we're building: - Read `README.md` (first 50 lines) and `package.json` (first 20 lines) - List `src/`, `app/`, `pages/`, `components/` if they exist - Check for any existing research or planning docs in `.scout/` or `.planning/` If the product direction is unclear: *"I don't have a clear picture of what you're building. Can you describe the product in 1-2 sentences? Reference research is 10x more useful when I know what to look for."* --- ## Phase 1: Scope **STOP.** Ask the user before proceeding. Do NOT auto-select. AskUserQuestion: > I need to know what to scout for. The main deliverable is a **Steal List** — > concrete patterns worth adopting, with evidence. - A) UI/UX references — how the best products in this space look, feel, and flow. Screenshots, layout patterns, interaction models. Best before design work. - B) Code references — how others actually built this. GitHub repos, architecture patterns, data models, edge cases. Best before implementation. - C) Both — UI/UX + Code. Full picture. (Recommended for new products) - D) Targeted — I have specific questions (describe what you want) RECOMMENDATION: Choose C when starting a new product. Choose A or B for a specific feature. **STOP.** Wait for the user's response before continuing. If D: use the user's description. Skip the structured phases and do a focused research pass on their specific questions. --- ## Phase 1.5: What Are We Building? **The type of thing you're building determines where to look and what to extract.** Identify the build type from context (or ask if unclear), then apply the matching research strategy. Each type has different reference sources, analysis dimensions, and steal targets. | Build type | Where to find references | What to analyze | |------------|------------------------|-----------------| | **SaaS / Web app** | GitHub trending, ProductHunt, competitor sites | Auth flow, pricing model, onboarding, data model, multi-tenancy | | **CLI tool** | `awesome-*` lists, similar CLIs on GitHub | Command structure, flags, output format, config management, error messages | | **API / Backend** | OpenAPI specs, similar API providers | Route design, auth scheme, rate limiting, pagination, error responses, versioning | | **UI component / Design system** | Radix, shadcn/ui, Ant Design, competitor products | Component API, composition patterns, accessibility, theming, responsive behavior | | **AI agent / Skill** | Agent skill registries, Langchain tools, CrewAI, existing MCP servers | Workflow phases, prompt structure, tool selection, output format, error recovery | | **MCP server** | Existing MCP servers (GitHub search "mcp server") | Tool design, auth flow, response schema, error handling | | **Mobile app** | App Store top charts, similar apps | Navigation patterns, gesture UX, offline handling, push notification strategy | | **Library / SDK** | npm/PyPI popular packages in the domain | API surface, tree-shaking, TypeScript types, migration strategy, docs structure | | **Browser extension** | Chrome Web Store, similar extensions | Manifest, content script patterns, popup UX, storage strategy | | **Game** | itch.io, similar genre games, Love2D/Godot examples | Game loop, input handling, state machine, asset pipeline | **Use this table to guide search queries and extraction focus.** Don't search generically. Search for the specific type: "best CLI tools for [domain]" not "best tools for [domain]". When you find references, prioritize: 1. **The best-in-class** in the exact category (direct competitor) 2. **Adjacent category leaders** that solve similar UX/technical problems differently 3. **Open source implementations** you can actually read the code of --- ## Phase 2: UI/UX Reference Research *Skip if the user chose B.* ### Step 1: Identify the field Use WebSearch to find 5-10 products that solve a similar problem or serve a similar audience. Search for: - "[product category] best apps 2026" - "[product category] alternatives" - "[problem domain] tools" Don't only search for direct competitors. Search for products that solve *adjacent* problems. A note-taking app should study Notion, but also Linear (for command palettes), Arc (for tab management), and Raycast (for keyboard-first UX). ### Step 2: Visual analysis For the top 3-5 products, use WebSearch and WebFetch to find UI screenshots and design reviews: - "[product name] UI screenshot" - "[product name] design review" - "[product name] interface walkthrough" If the agent harness has a headless browser tool available, use it to visit product pages and take screenshots directly. ### Step 3: Pattern extraction For each product, extract: | Dimension | What to capture | |-----------|----------------| | Layout | Grid, sidebar, panel structure | | Navigation | Top nav, sidebar, command palette, breadcrumbs | | Information density | Tight (Linear) vs. spacious (Notion) | | Key interactions | Click, hover, drag behavior. Signature UX moments | | Typography | Font choices, sizes, hierarchy | | Color | Palette strategy. Meaning vs. decoration | | Empty states | What users see before they have data | | Onboarding | First-run experience | ### Step 4: Three-layer synthesis - **Layer 1 (table stakes):** Patterns every product shares. User expectations. Don't skip. - **Layer 2 (current wave):** Trending patterns. Evaluate, don't blindly adopt. - **Layer 3 (first principles):** Where should THIS product deliberately break from the category? **Eureka check:** If Layer 3 reveals a genuine insight — name it: "EUREKA: Every [category] product does X because they assume [Y]. But our users [evidence] — so we should do Z instead." --- ## Phase 3: Code Reference Research *Skip if the user chose A.* ### Step 1: Find implementations **Use the build type from Phase 1.5 to target your search.** Generic searches waste time. | Build type | Search strategy | |------------|----------------| | SaaS / Web app | `gh search repos "[domain] app" --sort stars`, "[domain] open source alternative" | | CLI tool | `gh search repos "[domain] cli" --sort stars`, "awesome [domain]" lists | | API / Backend | "[domain] API open source", OpenAPI spec collections, "[framework] [domain] example" | | UI component | "[component] react/vue/svelte", Radix/shadcn source code, Storybook galleries | | AI agent / Skill | `gh search repos "[domain] agent"`, LangChain/CrewAI examples, MCP server repos | | MCP server | `gh search repos "mcp server" --sort stars`, modelcontextprotocol org repos | | Library / SDK | npm/PyPI search, `gh search repos "[domain] sdk"`, "best [language] [domain] library" | ```bash gh search repos "[targeted query from table above]" --sort stars --limit 10 2>/dev/null ``` Also search for: - "[framework] [feature] example" (e.g., "Next.js multi-tenant example") - "[feature] open source" (e.g., "real-time collaboration open source") - "[library] production example" (who uses this library at scale) If Context7 MCP tools are available (`resolve-library-id` then `query-docs`), use them for current library documentation. Otherwise, use WebSearch for "[library] documentation [version]". ### Step 2: Deep-read the top 3 For the best repos, read actual code. Use `gh` to browse: ```bash gh api repos/{owner}/{repo}/contents/{path} --jq '.content' | base64 -d ``` Or use WebFetch on raw GitHub URLs for specific files. For each repo, extract: | Dimension | What to capture | |-----------|----------------| | Architecture | Folder structure, module boundaries, dependency graph | | Data model | Schema, relationships, denormalization choices | | API design | Routes, request/response shapes, auth patterns | | State management | Client state, server state, cache strategy | | Error handling | Propagation, user-facing messages, retry logic | | Testing strategy | Unit vs. integration vs. E2E split | | Edge cases handled | Rate limiting, concurrent writes, offline, migration | | Dependencies | Key libraries and why (infer from usage) | ### Step 3: Pattern comparison Build a comparison matrix: ``` APPROACH A (repo1, repo3): How it works: [concrete] Strengths: [specific] Weaknesses: [specific] Best when: [conditions] APPROACH B (repo2): How it works: [concrete] Strengths: [specific] Weaknesses: [specific] Best when: [conditions] ``` Name the trade-offs concretely. "Repo X chose SSR because they need SEO. Repo Y chose CSR for interaction speed. Our product is [context], so [recommendation]." ### Step 4: Three-layer synthesis (code) - **Layer 1 (proven):** Patterns used by 3+ repos. Battle-tested. Default to these. - **Layer 2 (emerging):** Used by 1-2 repos, newer ones. Evaluate carefully. - **Layer 3 (first principles):** Does our context invalidate any proven pattern? --- ## Phase 4: Steal List + Reference Document **The Steal List is the primary deliverable.** For each pattern worth adopting (from either UI or code research): ``` STEAL: [pattern name] FROM: [repo/product name + URL] WHAT: [1-2 sentence description] WHY: [why this fits our product specifically] HOW: [concrete implementation hint — file path, function, or approach] RISK: [what breaks if we adopt this blindly] ``` For patterns to explicitly avoid: ``` KILL: [pattern name] SEEN IN: [repo/product] WHY NOT: [why it doesn't fit despite being popular] ``` ### Write the reference document ```bash _PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd) _REF_DIR="$_PROJECT_ROOT/.scout" mkdir -p "$_REF_DIR" _REF_FILE="$_REF_DIR/scout-$(date +%Y%m%d-%H%M).md" echo "REF_FILE: $_REF_FILE" ``` Use the Write tool to create `$_REF_FILE` with this structure: ```markdown # Scout Reference: [what was researched] **Date:** [date] **Scope:** [UI/Code/Both] ## Product Context [1 paragraph] ## Steal List [THE primary deliverable — all STEAL entries from both UI and code research] ## Kill List [patterns to explicitly avoid] ## UI/UX References (if applicable) ### Products Studied | Product | URL | What they do well | Screenshot | ### Pattern Analysis [Layer 1/2/3 synthesis] ## Code References (if applicable) ### Repos Studied | Repo | Stars | Approach | Key files | ### Architecture Comparison [comparison matrix] ### Dependency Recommendations [libraries worth using based on real production usage] ## Recommendations [3-5 concrete decisions to make before writing code] ## Open Questions [things that need answers before or during implementation] ## Eureka Moments [any Layer 3 insights that break from convention] ``` Tell the user where the file was saved. --- ## Completion Report: **DONE** with a 1-paragraph summary of what was found, how many products/repos were studied, and the top 3 items from the Steal List. If research was incomplete (blocked sites, empty GitHub results), report **DONE_WITH_CONCERNS** and list what couldn't be covered.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)