antigravity-skills-reference/docs/contributors/examples.md

# 💡 Real-World Examples - See Skills in Action

**Learn by example!** This guide shows you real conversations using different skills.

---

## Example 1: Designing a Feature with @brainstorming

### The Scenario
You want to add a "dark mode" feature to your app, but you're not sure how to approach it.

### The Conversation

```
You: @brainstorming I want to add dark mode to my React app

AI: Great! Let me help you think through this. First, let me check your 
    current project structure...
    
    [AI examines your files]
    
    I see you're using React with Tailwind CSS. Now, let's understand 
    your requirements:
    
    What's your primary goal for dark mode?
    a) User preference (toggle in settings)
    b) System preference (follow OS setting)
    c) Both (with manual override)

You: c) Both

AI: Perfect! That's the best user experience. Next question:
    
    Where should the dark mode toggle be located?
    a) In the main navigation
    b) In a settings page
    c) In a dropdown menu
    d) Multiple locations

You: a) In the main navigation

AI: Good choice for accessibility. One more question:
    
    Should dark mode preference persist across sessions?
    a) Yes, save to localStorage
    b) Yes, save to user account (requires backend)
    c) No, reset each session

You: a) Yes, save to localStorage

AI: Excellent! Now I have a clear picture. Let me present the design...
    
    ## Dark Mode Implementation Design
    
    ### Architecture Overview
    We'll use React Context for state management, Tailwind's dark mode
    utilities, and localStorage for persistence. The system will:
    1. Check OS preference on first visit
    2. Allow manual override via toggle
    3. Persist preference in localStorage
    
    Does this approach look good so far?

You: Yes, continue

AI: [Continues with detailed design sections...]
    
    [After design is complete]
    
    I've saved the design to docs/plans/2026-01-20-dark-mode-design.md
    
    Ready to set up for implementation?

You: Yes

AI: I'll create an isolated workspace using git worktrees and write an
    implementation plan. One moment...
```

### What Happened
- ✅ AI asked focused questions one at a time
- ✅ Explored your specific context
- ✅ Presented design in sections
- ✅ Saved documentation
- ✅ Prepared for implementation

---

## Example 2: Debugging with @systematic-debugging

### The Scenario
Your tests are failing, but you're not sure why.

### The Conversation

```
You: @systematic-debugging My tests are failing with "Cannot read property 
     'map' of undefined"

AI: Let me help you debug this systematically. First, I'll gather information:
    
    1. Running the failing test to see the full error...
    
    [AI runs: npm test]
    
    I see the error occurs in UserList.test.tsx at line 45. Let me examine
    the test file and the component...
    
    [AI reads both files]
    
    ## Hypothesis
    The test is failing because `users` prop is undefined when the component
    renders. This suggests the mock data isn't being passed correctly.
    
    ## Verification
    Let me check the test setup...
    
    [AI examines test]
    
    Found it! The test is calling:
    ```typescript
    render(<UserList />)
    ```
    
    But UserList requires a `users` prop. The component expects:
    ```typescript
    interface UserListProps {
      users: User[];
    }
    ```
    
    ## Solution
    The test should pass the users prop:
    ```typescript
    const mockUsers = [
      { id: 1, name: 'Alice' },
      { id: 2, name: 'Bob' }
    ];
    
    render(<UserList users={mockUsers} />)
    ```
    
    Should I apply this fix?

You: Yes

AI: [Applies fix and runs tests]
    
    ✅ All tests passing!
    
    ## Root Cause
    The test was missing required props. This is a common issue when
    components are refactored to require props that were previously optional.
    
    ## Prevention
    Consider adding TypeScript strict mode to catch these at compile time:
    ```json
    "strict": true,
    "strictNullChecks": true
    ```
    
    Would you like me to add this to your tsconfig.json?
```

### What Happened
- ✅ Systematic investigation
- ✅ Clear hypothesis
- ✅ Verification before fixing
- ✅ Root cause analysis
- ✅ Prevention suggestions

---

## Example 3: Adding Payments with @stripe-integration

### The Scenario
You need to add subscription billing to your SaaS app.

### The Conversation

```
You: @stripe-integration I need to add monthly subscription billing

AI: I'll help you implement Stripe subscriptions. Let me understand your
    requirements:
    
    Current stack detected:
    - Next.js 14 (App Router)
    - TypeScript
    - Prisma with PostgreSQL
    
    For subscription billing, we'll need:
    
    1. **Stripe Setup**
       - Stripe account and API keys
       - Webhook endpoint for events
       - Product and price IDs
    
    2. **Backend Implementation**
       - API routes for checkout
       - Webhook handler
       - Database schema for subscriptions
    
    3. **Frontend Implementation**
       - Pricing page
       - Checkout flow
       - Subscription management
    
    Let's start with the backend. First, install dependencies:
    
    ```bash
    npm install stripe @stripe/stripe-js
    ```
    
    Now, let's create the database schema...
    
    [AI provides Prisma schema]
    
    ```prisma
    model User {
      id                 String    @id @default(cuid())
      email              String    @unique
      stripeCustomerId   String?   @unique
      subscriptions      Subscription[]
    }
    
    model Subscription {
      id                 String    @id @default(cuid())
      userId             String
      user               User      @relation(fields: [userId], references: [id])
      stripeSubscriptionId String  @unique
      status             String
      priceId            String
      currentPeriodEnd   DateTime
      createdAt          DateTime  @default(now())
      updatedAt          DateTime  @updatedAt
    }
    ```
    
    Next, let's create the checkout API route...
    
    [AI provides complete implementation with:]
    - API route for creating checkout sessions
    - Webhook handler for subscription events
    - Helper functions for Stripe operations
    - Error handling and logging
    - TypeScript types
    
    Now for the frontend...
    
    [AI provides:]
    - Pricing page component
    - Checkout button component
    - Subscription status display
    - Tailwind styling
    
    Finally, let's set up the webhook:
    
    1. In Stripe Dashboard, add webhook endpoint:
       `https://yourdomain.com/api/webhooks/stripe`
    
    2. Select these events:
       - customer.subscription.created
       - customer.subscription.updated
       - customer.subscription.deleted
       - invoice.payment_succeeded
       - invoice.payment_failed
    
    3. Copy the webhook secret to your .env:
       ```
       STRIPE_WEBHOOK_SECRET=whsec_...
       ```
    
    ## Testing
    
    Test locally with Stripe CLI:
    ```bash
    stripe listen --forward-to localhost:3000/api/webhooks/stripe
    stripe trigger customer.subscription.created
    ```
    
    ## Security Checklist
    - ✅ API keys in environment variables
    - ✅ Webhook signature verification
    - ✅ Server-side price validation
    - ✅ Idempotency keys for operations
    
    Ready to test the implementation?
```

### What Happened
- ✅ Detected existing stack
- ✅ Provided complete implementation
- ✅ Included database schema
- ✅ Added security best practices
- ✅ Included testing instructions

---

## Example 4: Writing Copy with @copywriting

### The Scenario
You need compelling copy for your SaaS landing page.

### The Conversation

```
You: @copywriting Write homepage copy for my project management tool

AI: I'll help you create compelling homepage copy. First, let me understand
    your product:
    
    What makes your project management tool different from competitors
    like Asana, Trello, or Monday.com?

You: It's specifically built for remote teams with built-in video standups
     and async communication features

AI: Excellent differentiator! Who is your primary target audience?
    a) Startups and small teams (2-20 people)
    b) Mid-size companies (20-200 people)
    c) Enterprise (200+ people)
    d) Freelancers and agencies

You: a) Startups and small teams

AI: Perfect. What's the main pain point you solve?

You: Remote teams waste time in unnecessary meetings and lose context
     in async communication

AI: Great! Now I have what I need. Here's your homepage copy:
    
    ---
    
    ## Hero Section
    
    **Headline:**
    Run Your Remote Team Without the Meeting Overload
    
    **Subheadline:**
    The project management tool built for distributed teams. Replace 
    status meetings with async video standups and keep everyone in sync
    without the Zoom fatigue.
    
    **CTA:**
    Start Free Trial → (No credit card required)
    
    ---
    
    ## Problem Section
    
    **Headline:**
    Remote Work Shouldn't Mean More Meetings
    
    **Body:**
    Your team is distributed across time zones. You're spending hours in
    status meetings just to stay aligned. Async updates get lost in Slack.
    Context disappears. Productivity suffers.
    
    Sound familiar?
    
    ---
    
    ## Solution Section
    
    **Headline:**
    Stay Aligned Without the Meeting Marathon
    
    **Features:**
    
    📹 **Async Video Standups**
    Record quick video updates on your schedule. Your team watches when
    it works for them. No more 9am calls for your teammate in Tokyo.
    
    💬 **Context-Rich Communication**
    Every task, comment, and decision stays connected. No more hunting
    through Slack threads or email chains.
    
    📊 **Visual Progress Tracking**
    See what's happening at a glance. Kanban boards, timelines, and
    dashboards that actually make sense.
    
    🔔 **Smart Notifications**
    Get notified about what matters. Ignore the rest. Your focus time
    is sacred.
    
    ---
    
    ## Social Proof Section
    
    **Headline:**
    Trusted by Remote Teams Worldwide
    
    [Testimonial placeholders with structure]
    
    ---
    
    ## CTA Section
    
    **Headline:**
    Ready to Reclaim Your Calendar?
    
    **Body:**
    Join 500+ remote teams who've cut meeting time by 60% while staying
    more aligned than ever.
    
    **CTA:**
    Start Your Free 14-Day Trial →
    
    No credit card required. Cancel anytime.
    
    ---
    
    ## Copy Notes
    
    **Tone:** Professional but conversational
    **Focus:** Pain point (too many meetings) → Solution (async video)
    **Differentiation:** Built specifically for remote teams
    **Social proof:** Quantified benefit (60% fewer meetings)
    
    Would you like me to:
    1. Write alternative versions for A/B testing?
    2. Create copy for specific feature pages?
    3. Write email sequences for onboarding?
```

### What Happened
- ✅ Asked clarifying questions
- ✅ Identified unique value proposition
- ✅ Created benefit-focused copy
- ✅ Included clear CTAs
- ✅ Provided copy notes for consistency

---

## Example 5: Test-Driven Development with @test-driven-development

### The Scenario
You need to implement a new feature: user authentication.

### The Conversation

```
You: @test-driven-development I need to implement user login functionality

AI: Perfect! Let's use TDD to build this. Following the Red-Green-Refactor
    cycle, we'll write tests first, then implement.
    
    ## Step 1: Write the First Test (RED)
    
    Let's start with the simplest case - successful login:
    
    ```typescript
    // auth.test.ts
    import { login } from './auth';
    
    describe('login', () => {
      it('should return user data for valid credentials', async () => {
        const result = await login({
          email: 'user@example.com',
          password: 'correct-password'
        });
        
        expect(result.success).toBe(true);
        expect(result.user).toHaveProperty('id');
        expect(result.user).toHaveProperty('email');
        expect(result.token).toBeDefined();
      });
    });
    ```
    
    Let's run this test to see it fail:
    
    [AI runs: npm test]
    
    ✅ Test fails as expected (auth.ts doesn't exist yet)
    
    ## Step 2: Write Minimal Implementation (GREEN)
    
    Now let's write just enough code to make this test pass:
    
    ```typescript
    // auth.ts
    interface LoginCredentials {
      email: string;
      password: string;
    }
    
    interface LoginResult {
      success: boolean;
      user?: {
        id: string;
        email: string;
      };
      token?: string;
    }
    
    export async function login(
      credentials: LoginCredentials
    ): Promise<LoginResult> {
      // Minimal implementation to pass the test
      return {
        success: true,
        user: {
          id: '1',
          email: credentials.email
        },
        token: 'fake-token'
      };
    }
    ```
    
    [AI runs: npm test]
    
    ✅ Test passes!
    
    ## Step 3: Add Next Test (RED)
    
    Now let's test the failure case:
    
    ```typescript
    it('should return error for invalid credentials', async () => {
      const result = await login({
        email: 'user@example.com',
        password: 'wrong-password'
      });
      
      expect(result.success).toBe(false);
      expect(result.error).toBe('Invalid credentials');
      expect(result.user).toBeUndefined();
      expect(result.token).toBeUndefined();
    });
    ```
    
    [AI runs: npm test]
    
    ❌ Test fails (always returns success)
    
    ## Step 4: Implement Real Logic (GREEN)
    
    Now let's add actual authentication:
    
    ```typescript
    import bcrypt from 'bcrypt';
    import jwt from 'jsonwebtoken';
    import { db } from './db';
    
    export async function login(
      credentials: LoginCredentials
    ): Promise<LoginResult> {
      // Find user
      const user = await db.user.findUnique({
        where: { email: credentials.email }
      });
      
      if (!user) {
        return {
          success: false,
          error: 'Invalid credentials'
        };
      }
      
      // Verify password
      const validPassword = await bcrypt.compare(
        credentials.password,
        user.passwordHash
      );
      
      if (!validPassword) {
        return {
          success: false,
          error: 'Invalid credentials'
        };
      }
      
      // Generate token
      const token = jwt.sign(
        { userId: user.id },
        process.env.JWT_SECRET!,
        { expiresIn: '7d' }
      );
      
      return {
        success: true,
        user: {
          id: user.id,
          email: user.email
        },
        token
      };
    }
    ```
    
    [AI runs: npm test]
    
    ✅ All tests pass!
    
    ## Step 5: Add Edge Cases
    
    Let's add more tests for edge cases:
    
    ```typescript
    it('should handle missing email', async () => {
      const result = await login({
        email: '',
        password: 'password'
      });
      
      expect(result.success).toBe(false);
      expect(result.error).toBe('Email is required');
    });
    
    it('should handle missing password', async () => {
      const result = await login({
        email: 'user@example.com',
        password: ''
      });
      
      expect(result.success).toBe(false);
      expect(result.error).toBe('Password is required');
    });
    
    it('should handle database errors gracefully', async () => {
      // Mock database error
      jest.spyOn(db.user, 'findUnique').mockRejectedValue(
        new Error('Database connection failed')
      );
      
      const result = await login({
        email: 'user@example.com',
        password: 'password'
      });
      
      expect(result.success).toBe(false);
      expect(result.error).toBe('An error occurred');
    });
    ```
    
    [AI implements validation and error handling]
    
    ## Step 6: Refactor (REFACTOR)
    
    Now that all tests pass, let's refactor for better code quality:
    
    ```typescript
    // Extract validation
    function validateCredentials(credentials: LoginCredentials): string | null {
      if (!credentials.email) return 'Email is required';
      if (!credentials.password) return 'Password is required';
      return null;
    }
    
    // Extract user verification
    async function verifyUser(
      email: string,
      password: string
    ): Promise<User | null> {
      const user = await db.user.findUnique({ where: { email } });
      if (!user) return null;
      
      const valid = await bcrypt.compare(password, user.passwordHash);
      return valid ? user : null;
    }
    
    // Main function is now cleaner
    export async function login(
      credentials: LoginCredentials
    ): Promise<LoginResult> {
      try {
        const validationError = validateCredentials(credentials);
        if (validationError) {
          return { success: false, error: validationError };
        }
        
        const user = await verifyUser(
          credentials.email,
          credentials.password
        );
        
        if (!user) {
          return { success: false, error: 'Invalid credentials' };
        }
        
        const token = generateToken(user.id);
        
        return {
          success: true,
          user: { id: user.id, email: user.email },
          token
        };
      } catch (error) {
        console.error('Login error:', error);
        return { success: false, error: 'An error occurred' };
      }
    }
    ```
    
    [AI runs: npm test]
    
    ✅ All tests still pass after refactoring!
    
    ## Summary
    
    We've implemented login functionality using TDD:
    - ✅ 5 tests covering happy path, errors, and edge cases
    - ✅ Clean, testable code
    - ✅ Proper error handling
    - ✅ Type safety with TypeScript
    
    Next steps:
    1. Add rate limiting tests
    2. Add session management tests
    3. Add logout functionality
    
    Should I continue with these?
```

### What Happened
- ✅ Followed Red-Green-Refactor cycle
- ✅ Wrote tests before implementation
- ✅ Covered edge cases
- ✅ Refactored with confidence
- ✅ Maintained test coverage

---

## Key Takeaways

### What Makes These Examples Effective?

1. **Skills ask clarifying questions** before jumping to solutions
2. **Skills provide context-aware help** based on your project
3. **Skills follow best practices** for their domain
4. **Skills include complete examples** not just snippets
5. **Skills explain the "why"** not just the "how"

### How to Get Similar Results

1. **Be specific** in your requests
2. **Provide context** about your project
3. **Answer questions** the skill asks
4. **Review suggestions** before applying
5. **Iterate** based on results

---

## Try These Yourself!

Pick a skill and try it with your own project:

- **Planning:** `@brainstorming` or `@writing-plans`
- **Development:** `@test-driven-development` or `@react-best-practices`
- **Debugging:** `@systematic-debugging` or `@test-fixing`
- **Integration:** `@stripe-integration` or `@firebase`
- **Marketing:** `@copywriting` or `@seo-audit`

---

**Want more examples?** Check individual skill folders for additional examples and use cases!