---
name: Competitive Analysis & Integration Blueprint
description: Systematic methodology for studying competitors/tools, extracting lessons, and applying them to our products. Includes self-evaluation gates.
category: Research
tags: [competitive-analysis, architecture, integration, evaluation]
version: 1.0.0
authority: read_only
---

# Competitive Analysis & Integration Blueprint

This skill defines the process for evaluating external tools, extracting architectural lessons, and integrating those lessons into our products. Every competitive analysis MUST follow this process.

## Phase 1: Discovery (Before Installing)

1. **Identify the tool** — name, URL, GitHub, license, star count, age
2. **Understand the market signal** — why does this have traction? What pain does it solve?
3. **Map to our products** — which of our products does this compete with or complement?
4. **Read the README** — understand positioning, features, architecture claims
5. **Find user content** — YouTube videos, blog posts, Twitter threads from USERS (not marketing)
6. **Get a transcript** if video content exists — full transcript, not summary

**Output:** Discovery brief (< 500 words) answering: What is it? Why do people use it? How does it relate to us?

## Phase 2: Source Analysis (Before Running)

1. **Clone the repo** — read actual source code, not just docs
2. **Map the database schema** — every table, every column, every index. This is the ground truth of what a product ACTUALLY does vs what it claims.
3. **Study the API routes** — what endpoints exist? What data flows through them?
4. **Read the UI components** — what pages exist? What does the user actually see and interact with?
5. **Identify the service layer** — how is business logic organized? What patterns are used?
6. **Document the data model** — entities, relationships, state machines, constraints
7. **Check the test suite** — what's tested? What's NOT tested? What edge cases are handled?

**Output:** Source analysis document with:
- Full table/schema mapping
- API endpoint list
- UI page inventory
- Service pattern summary
- Feature-by-feature comparison table: Their Feature → Our Equivalent → Gap

## Phase 3: Hands-On Evaluation (Running It)

1. **Install and run** — document every step, every error, every friction point
2. **Complete the onboarding** — go through their first-run experience as a new user
3. **Test core flows** — create an agent, assign a task, run a heartbeat, check the dashboard
4. **Test edge cases** — what happens with bad input? Network errors? Budget exceeded?
5. **Screenshot everything** — save screenshots of every UI state for reference
6. **Measure performance** — startup time, response time, resource usage

**Output:** Hands-on evaluation with screenshots, friction points, and UX notes

## Phase 4: Architectural Extraction

For every significant feature in the competitor:

1. **How do they implement it?** (specific: table schema, API pattern, UI component)
2. **What should we adopt?** (specific: exact table structure, exact API shape)
3. **What do we already do better?** (specific: our approach and why it's superior)
4. **What's the gap?** (specific: what we're missing and what it would take to build)
5. **What's the integration opportunity?** (can we complement rather than compete?)

**Output:** Feature extraction table with concrete implementation details, not vague descriptions

## Phase 5: Architecture Design

1. **Start from current state** — read OUR actual code first, not just memory of it
2. **Design the migration path** — how to get from current → target without breaking existing users
3. **Define schemas precisely** — every table, column, type, constraint, index
4. **Define APIs precisely** — every endpoint, request/response shape, error codes
5. **Define evaluation metrics** — how will we KNOW if the implementation is correct?
6. **Define backward compatibility** — what existing features must keep working?
7. **Define rollback strategy** — if the change breaks something, how do we undo it?

**Output:** Architecture document that passes the self-evaluation gate (see below)

## Phase 6: Self-Evaluation Gate

Before declaring the architecture "done," answer these questions honestly:

### Completeness Check
- [ ] Did I read the ACTUAL source code, or am I working from summaries?
- [ ] Did I read OUR actual code before designing changes?
- [ ] Does the migration plan preserve all existing functionality?
- [ ] Is every new table/column justified by a specific user need?
- [ ] Are error cases handled (not just happy path)?
- [ ] Is backward compatibility addressed?

### Quality Check
- [ ] Would I bet my career on this being correct?
- [ ] If a senior engineer reviewed this, what would they flag?
- [ ] What's the weakest part of this design? (Be honest)
- [ ] What metric proves this design is better than the current state?
- [ ] Have I tested any of this, or is it purely theoretical?

### Measurement Check
- [ ] How will we know if this succeeded?
- [ ] What's the specific number that improves?
- [ ] What's the rollback trigger?
- [ ] What's the timeline and what are the milestones?

**If any answer is "no" or "I don't know" — go back and fix it before proceeding.**

## Phase 7: Implementation Planning

1. **Order by impact** — what saves the most money/time/risk first?
2. **Order by dependency** — what must be built before what?
3. **Define "done" for each step** — specific, measurable criteria
4. **Estimate effort honestly** — double your first estimate
5. **Plan verification** — how will each step be tested?

## Anti-Patterns to Avoid

- **Summary-driven design** — designing from agent summaries instead of reading actual code
- **Feature shopping** — adopting features because they're cool, not because users need them
- **Big bang migration** — trying to change everything at once instead of incremental steps
- **Theoretical architecture** — designing without verifying against actual code constraints
- **Copying without understanding** — adopting patterns without understanding WHY they work
- **Ignoring existing users** — designing for new users while breaking the experience for current ones

## When to Use This Skill

- Evaluating any competitor product
- Studying any open-source tool for architectural lessons
- Before any major product redesign
- Before integrating any external system
- When Decker says "look at what X is doing"

## Example Applications

- Paperclip → AIBrain orchestration features (completed 2026-04-06)
- Workshop.ai → Demo video creation pipeline (pending)
- skills.sh → Brain Marketplace design (pending)
- Mem0/Zep → Memory architecture comparison (pending)
