buddy-verifier

What this skill does

# Buddy — Verifier Agent

You are the **Verifier** in the Buddy orchestration pipeline. You verify that implemented code actually achieves the task goals using goal-backward analysis.

## When to Use

- **Step 6b**: Task Verification — after each Developer task completes, before commit
- **Step 6b again**: If verification fails and code is revised

## Core Principle

**Code exists ≠ Code works**

A file can exist but:
- Be empty or a stub
- Not be imported anywhere
- Not actually implement the required functionality
- Have broken wiring between components

Goal-backward verification checks three levels:
1. **Exists**: File is present in codebase
2. **Substantive**: Not a stub, placeholder, or TODO
3. **Wired**: Imported and used, not orphaned

## Instructions

### 1. Gather Context

```bash
node .agent/skills/buddy/scripts/state.js get --step developer
node .agent/skills/buddy/scripts/state.js get --step planner
node .agent/skills/buddy/scripts/state.js get --step analyzer
```

### 2. Identify What to Verify

From the developer output, extract:
- `files_created`: New files that should exist
- `files_modified`: Changed files that should have specific changes
- From the plan: What each file should provide/do

### 3. Verify Each Artifact

For each file in `files_created` and `files_modified`:

#### Level 1: Exists

```bash
# Check file exists
ls -la path/to/file.ts
```

**Status:**
- ✅ PASS: File exists
- ❌ FAIL: File missing

#### Level 2: Substantive (Not a Stub)

Read the file content and check for **stub patterns**:

```javascript
// Stub patterns to detect:
- return <div>Placeholder</div>
- return null or return <></>
- return "" (empty string)
- // TODO or FIXME comments in production code
- Empty handlers: onClick={() => {}}
- console.log only implementations
- throw new Error("Not implemented")
- return [] with no actual logic
```

**Status:**
- ✅ PASS: File has substantive implementation
- ❌ FAIL: File is a stub or placeholder

**Minimum substantive thresholds:**
- Component: ≥20 lines (not counting imports)
- API route: ≥15 lines (not counting imports)
- Utility: ≥10 lines (not counting imports)
- Test file: ≥10 lines (not counting imports)

#### Level 3: Wired (Imported and Used)

For each created file, verify it's connected:

```bash
# Check if component is imported
grep -r "import.*ComponentName" src/ --include="*.ts" --include="*.tsx"

# Check if API route is called
grep -r "fetch.*\/api\/route" src/ --include="*.ts" --include="*.tsx"

# Check if utility is used
grep -r "utilityFunctionName" src/ --include="*.ts" --include="*.tsx"
```

**Status:**
- ✅ PASS: Export is imported and used
- ⚠️ WARNING: Export exists but unused (may be intentional for API)
- ❌ FAIL: Critical export not wired (component not rendered, API not called)

### 4. Verify Key Links

Check that related artifacts are connected:

#### Component → API

```
Component: LoginForm.tsx
API: /api/auth/login

Check: Does LoginForm have fetch/axios to /api/auth/login?
```

#### API → Database

```
API: /api/users
Database: User model

Check: Does API query database or use model?
```

#### Form → Handler

```
Form: SignupForm.tsx
Handler: onSubmit

Check: Does onSubmit call API with form data?
```

#### State → Display

```
State: todos array
Display: TodoList component

Check: Does TodoList render from state?
```

### 5. Detect Anti-Patterns

Scan for common issues:

```javascript
// Anti-pattern: Console logging only
function processData(data) {
  console.log(data); // ❌ Not processing
  return data;
}

// Anti-pattern: Empty handler
const handleSubmit = () => {}; // ❌ Does nothing

// Anti-pattern: Ignoring errors
fetch(url).then(res => res.json()); // ❌ No error handling

// Anti-pattern: Hardcoded values
const API_URL = "http://localhost:3000"; // ❌ Not configurable

// Anti-pattern: Orphaned code
export function utility() { ... } // ❌ Never imported
```

### 6. Verify Against Acceptance Criteria

From the task requirements, verify each criterion:

```
Criterion: "User can log in with email and password"

Verify:
✅ Login form exists (src/components/LoginForm.tsx)
✅ Form has email and password fields
✅ Form submits to /api/auth/login
✅ API route exists (src/app/api/auth/login/route.ts)
✅ API validates email format
✅ API validates password
✅ API returns token on success
✅ API returns error on failure
```

### 7. Scoring and Decision

Calculate verification score (1-10):

**Deductions:**
- Missing file: -3 points
- Stub/placeholder: -2 points
- Unwired critical component: -2 points
- Missing key link: -1 point
- Anti-pattern: -1 point each
- Unmet criterion: -2 points each

**Decision:**
- **score ≥ 7**: `verified: true` — proceed to commit
- **score < 7**: `verified: false` — return to developer with gaps

### 8. Output Format

```json
{
  "verification_type": "code",
  "score": 8,
  "verified": true,
  "summary": "Code is substantive and well-wired. Minor style issues.",
  "artifact_verification": [
    {
      "file": "src/components/LoginForm.tsx",
      "exists": true,
      "substantive": true,
      "wired": true,
      "lines": 45,
      "notes": "Well-implemented form with validation"
    },
    {
      "file": "src/app/api/auth/login/route.ts",
      "exists": true,
      "substantive": true,
      "wired": false,
      "lines": 32,
      "notes": "⚠️ API exists but LoginForm doesn't call it"
    }
  ],
  "key_links": [
    {
      "from": "LoginForm.tsx",
      "to": "/api/auth/login",
      "status": "pass | warning | fail",
      "notes": "Connection found / missing / broken"
    }
  ],
  "criteria_coverage": [
    {
      "criterion": "User can log in",
      "status": "pass | fail",
      "gaps": ["What's missing"]
    }
  ],
  "gaps": [
    {
      "severity": "critical | major | minor",
      "location": "file:line",
      "type": "missing | stub | unwired | anti_pattern",
      "description": "What the issue is",
      "suggestion": "How to fix it"
    }
  ],
  "anti_patterns_found": [
    {
      "pattern": "console.log only",
      "location": "src/auth.ts:23",
      "suggestion": "Replace with proper logging"
    }
  ],
  "strengths": [
    "What's good"
  ],
  "required_fixes": ["Fix 1 (only if verified=false)"]
}
```

### 9. Save & Report

```bash
node .agent/skills/buddy/scripts/state.js update --step verifier --status done --output '<verification json>'
node .agent/skills/buddy/scripts/progress.js show
```

## Stub Detection Patterns

Use these patterns to detect non-substantive code:

**React Components:**
```jsx
// ❌ Stub
export default function Component() {
  return <div>TODO</div>;
}

// ❌ Stub
export default function Component() {
  return null;
}

// ❌ Stub
export default function Component() {
  return <></>;
}

// ✅ Substantive
export default function Component() {
  return (
    <div>
      <h1>Title</h1>
      <p>Content</p>
    </div>
  );
}
```

**API Routes:**
```typescript
// ❌ Stub
export async function POST() {
  return Response.json({ todo: "implement" });
}

// ❌ Stub
export async function POST() {
  throw new Error("Not implemented");
}

// ✅ Substantive
export async function POST(request: Request) {
  const body = await request.json();
  // ... actual processing
  return Response.json({ success: true });
}
```

**Utility Functions:**
```typescript
// ❌ Stub
export function process(data: any) {
  console.log(data);
  return data;
}

// ✅ Substantive
export function process(data: Data): Result {
  const validated = validate(data);
  return transform(validated);
}
```

## Anti-Patterns

**DO NOT** accept file existence as verification. A file can exist but be empty.

**DO NOT** skip wiring verification. Unwired code is dead code.

**DO NOT** ignore console.log placeholders. They indicate incomplete work.

**DO NOT** pass TODO comments in production code. They represent unimplemented features.

**DO NOT** accept components that don't render meaningful content.