Upstream Evaluation

Upstream Evaluation Skill

Systematic evaluation of upstream changes using Navigator's design frameworks. This skill focuses purely on decision-making — what to adopt, skip, or adapt — not execution.

Primary Reference

Read first: docs/architecture/DESIGN.md

This document defines Navigator's:

• Layer model (user surface vs. internals)
• Decision frameworks (A-E)
• Naming conventions
• Consolidation patterns
• Historical decisions as precedent

Evaluation Process

Step 1: Categorize Each Change

For each upstream change, determine its type:

Step 2: Apply Decision Framework

Framework A: New Upstream Feature

Does it benefit agents?
├─ NO → Skip or defer
└─ YES → Does Navigator have existing concept?
    ├─ YES → Extend existing (don't duplicate)
    └─ NO → Add new action
        └─ Is upstream naming agent-friendly?
            ├─ YES → Adopt (camelCase conversion)
            └─ NO → Create Navigator name

Output format:

### [feature-name]
- **Decision**: Adopt / Skip / Defer / Extend existing
- **Navigator name**: `camelCaseName` (if adopting)
- **Category**: Navigation / Interaction / Capture / etc.
- **Rationale**: Why this decision

Framework B: Upstream Renames Something

Which layer affected?
├─ INTERNAL → Align with upstream (no user impact)
└─ USER SURFACE → Is new name objectively better?
    ├─ NO → Keep Navigator name (stability wins)
    └─ YES → Migration with deprecation

Output format:

### [renamed-thing]
- **Decision**: Align internally / Keep Navigator name / Migrate with deprecation
- **Layer affected**: Internal / User surface
- **Rationale**: Why this decision

Framework C: Upstream Catches Up

Upstream adopts our concept
└─ Is naming identical?
    ├─ YES → Simplify executor (remove translation)
    └─ NO → Keep Navigator name, simplify mapping

Framework D: Consolidate vs. Mirror

Multiple upstream actions with related purpose
└─ Are they cognitively distinct for agents?
    ├─ YES → Mirror as separate actions
    └─ NO → Consolidate with parameters

Framework E: Quick Classification

Step 3: Check Naming Conventions

For each adopted feature, verify naming follows conventions:

Reordering rule: Verb should come first for CLI-friendly naming.

• tab_new → newTab (verb-noun in camelCase)
• recording_start → recordingStart (verb already first)

Step 4: Identify Schema Changes

For each adopted feature, specify:

### Schema Changes Required

#### [action-name]
**File**: `packages/core/src/schema/index.ts`
**Type**: New action / Extend existing / Modify parameters

```typescript
// Proposed schema
export const actionNameSchema = baseActionSchema.extend({
  action: z.literal('actionName'),
  // parameters...
})

Executor mapping: actionName → upstream action_name

### Step 5: Document Decisions

Compile all decisions into a structured format:

```markdown
## Evaluation Summary

### Adopt
| Feature | Navigator Name | Category | Schema Change |
|---------|---------------|----------|---------------|
| styles | `styles` | Capture | New action |
| recording_* | `recordingStart/Stop/Restart` | Capture | 3 new actions |

### Skip
| Feature | Reason |
|---------|--------|
| marketplace plugin | Branding-specific (Framework E) |

### Defer
| Feature | Reason | Revisit When |
|---------|--------|--------------|
| feature-x | Unclear agent benefit | When use case emerges |

### Extend Existing
| Feature | Existing Action | Change |
|---------|-----------------|--------|
| tab_new url param | `newTab` | Add optional `url` parameter |

Evaluation Checklist

Before completing evaluation:

• Every change categorized (new/rename/catchup/multiple/fix/branding)
• Appropriate framework applied to each
• Naming conventions verified for all adoptions
• Schema changes specified with code snippets
• Decisions documented with rationale
• Historical precedents checked in DESIGN.md

Invocation

This skill is loaded by the /agent-browser:integrate-changes command.

Handoff

After evaluation completes, hand off to:

• Documentation: /agent-browser:issue to create tracking issue
• Execution: /agent-browser:update for merge/sync steps
• Implementation: senior-dev agent for schema changes

The evaluation output becomes the "what and why" — other commands handle "how."