## Example 1: VS Code — Adding Type Safety

**User says:** "this function looks wrong, fix it"

**Screen Context:**
```
SYSTEM: VS Code 1.96
SCREEN: Open file `src/services/payment.ts`
VISIBLE ELEMENTS:
- Line 15-25: `processPayment(amount, userId)` function
- Line 17: `const result = await stripe.charges.create({ amount: amount });`
- Line 19: `return result.status;`
- No TypeScript errors visible (file may not be type-checked)
USER WANTS: "fix it" — unclear what is wrong
CONSTRAINTS: none stated
```

**What a naive agent would do:**
- Guess that the function needs error handling
- Guess that the amount needs validation
- Maybe add a try-catch and call it done

**What this skill produces:**

### Analysis
The instruction is too vague. "This function looks wrong" could mean:
- Missing error handling (most likely)
- Amount not in cents (Stripe requires cents)
- No input validation
- Missing return type annotation
- No handling of declined charges

### Precision Command
```
TASK: Fix processPayment function for type safety and correctness
FILE: src/services/payment.ts
ACTION: Modify the processPayment function (lines 15-25)
DETAILS:
1. Add input validation: check amount is a positive integer (Stripe expects cents)
2. Add try-catch around the stripe.charges.create call
3. Handle specific Stripe errors (card_declined, insufficient_funds, etc.)
4. Add TypeScript return type: Promise<'succeeded' | 'failed' | 'pending'>
5. Add type annotation for the amount parameter: number (positive integer)
CONSTRAINTS:
- Do not change the function signature's public behavior
- Use existing error types from the project if available
- Keep Stripe API call structure unchanged
DONE WHEN: Function has proper types, validates input, handles errors, 
and returns a union type instead of raw Stripe response
```

### Why This Command Works
- Targets the specific function with line numbers
- Lists exactly 5 changes to make
- Specifies what NOT to change (public API, Stripe call structure)
- Clear completion criteria
- No guessing — addresses the most likely issues

---

## Example 2: Browser — UI Bug Fix

**User says:** "the button doesn't look right on mobile"

**Screen Context:**
```
SYSTEM: Chrome 131, DevTools mobile view (iPhone 14)
SCREEN: Homepage of e-commerce site
VISIBLE ELEMENTS:
- Hero section with CTA button "Shop Now"
- Button appears cut off on the right edge
- Button text is truncated to "Shop N..."
- Other elements on page render correctly
USER WANTS: fix the button layout on mobile
CONSTRAINTS: responsive design must work on all screen sizes
```

**What a naive agent would do:**
- Add `white-space: nowrap` to the button
- Or reduce font size
- Or make the button full-width without considering the design

**What this skill produces:**

### Analysis
The button is truncated because its width exceeds the container on mobile. The text is being cut off by an overflow. This is a common responsive design issue where fixed-width or min-width values don't account for small screens.

### Precision Command
```
TASK: Fix CTA button truncation on mobile viewport
FILE: src/styles/hero.css (or equivalent)
ACTION: Modify the CTA button styling for mobile responsiveness
DETAILS:
1. Remove any fixed min-width on the button that exceeds mobile viewport
2. Add max-width: 100% to prevent overflow
3. Allow text wrapping or reduce padding for small screens
4. Test at 375px width (iPhone SE/14 mini) to confirm button renders fully
CONSTRAINTS:
- Button must remain visually prominent on desktop (keep min-width for desktop)
- Text must not be truncated at any viewport width >= 320px
- Do not change the button's visual hierarchy or color
- Use media query, not global style change
DONE WHEN: "Shop Now" button displays fully without truncation at 375px, 
390px, and 428px viewport widths while maintaining desktop appearance
```

### Why This Command Works
- Identifies the specific element (CTA button "Shop Now")
- Specifies the exact viewport widths to test
- Distinguishes between desktop and mobile behavior
- Includes 4 specific changes
- Clear completion criteria with concrete viewport sizes
- Constraints prevent breaking the desktop layout

---

## Example 3: Terminal — Database Migration

**User says:** "add a column to users"

**Screen Context:**
```
SYSTEM: macOS Terminal, zsh
SCREEN: Project root directory
VISIBLE ELEMENTS:
- `ls` output shows: src/, prisma/, package.json, .env
- `prisma/schema.prisma` exists
USER WANTS: add a column to the users table
CONSTRAINTS: using Prisma ORM, PostgreSQL database
```

**What a naive agent would do:**
- Edit `prisma/schema.prisma` and add a column
- Run `npx prisma migrate dev`
- Done

**What this skill produces:**

### Analysis
"Add a column to users" is missing critical information:
- What column name?
- What type?
- Is it required or optional?
- Default value?
- Should existing rows be backfilled?

### Precision Command
```
TASK: Add phone_number column to users table
FILE: prisma/schema.prisma
ACTION: Add new field to User model and generate migration
DETAILS:
1. Add to User model: `phone_number String?` (optional, no default)
2. Run: npx prisma migrate dev --name add_phone_number
3. Verify migration SQL looks correct before applying
CONSTRAINTS:
- Column must be nullable (existing users have no phone)
- No default value needed
- Do not modify existing fields
DONE WHEN: Migration file is created, prisma generate succeeds, 
and the database schema includes the new column
```

### Why This Command Works
- Specifies the column name and type
- Clarifies nullable vs required
- Includes the exact Prisma command to run
- Specifies what to verify before applying
- Clear completion criteria

If the user truly meant "add some column" without specifics, this skill would ask:
```
I can add a column to the users table. I need a few details:
1. What should the column be called?
2. What type? (String, Int, Boolean, DateTime, etc.)
3. Should it be required or optional?
4. Any default value?
```