Shipkit Review Shipping

shipkit-review-shipping

Review-only verification — Claude reviews your work across 12 quality dimensions and reports findings with evidence. You decide what to fix.

Report, don't fix. Scans changes, classifies findings by severity, and presents a structured report. The reviewer never modifies code.

---

When to Invoke

• /verify — review all recent changes
• /verify — focus on specific area
• "Check my work", "Am I ready to commit?"

For deeper review: If user asks for "deep check", "thorough review", or "really scrutinize this" → see [Deeper Review Option](#deeper-review-option) below.

---

Arguments

If $ARGUMENTS is provided (e.g. /shipkit-review-shipping auth module), use it as the explicit verification scope. Skip scope detection and treat it as the answer to "What should I verify?".

If $ARGUMENTS is empty, proceed normally with automatic scope detection (git diff, session context).

---

Process

Completion Tracking

After detecting scope, create tasks:

• TaskCreate: "Pre-scan: Quick pass across 12 dimensions"
• TaskCreate: "Pattern ripple: Expand scope to affected files"
• TaskCreate: "Deep review: All 12 dimensions with evidence"
• TaskCreate: "Write verification-report.json"

TaskUpdate each task to in_progress when starting it, completed when done. Track dimension progress: "Reviewing dimension {N}/12: {name}". The pre-scan is NOT the final report — the deep review (Step 3) must follow. Do NOT present findings until verification-report.json is written to disk.

Step 1: Detect Scope

Determine what to verify:

# Get uncommitted changes
git diff --name-only HEAD

# If nothing uncommitted, check recent commits
git diff --name-only HEAD~3..HEAD

Also consider: What did Claude work on this session?

If unclear, ask: "What should I verify?"

Step 1.1: Quick Pre-Scan (Before Loop)

Run a lightweight first pass across the 12 dimensions on the changed files only (no pattern ripple yet). This is a fast scan to surface the landscape of findings.

Present a summary to the user:

## Pre-Scan Summary

Found findings across these themes:

| # | Finding | L · I · E |
|---|---------|-----------|
| 1 | 🔴 Missing auth checks on 2 API routes | L:High · I:High · E:Low |
| 2 | 🔴 Broken import in Dashboard.tsx | L:High · I:High · E:Low |
| 3 | 🟡 Magic numbers in config (3 instances) | L:Low · I:Low · E:Low |
| 4 | 🟡 Missing loading states on admin pages | L:Medium · I:Medium · E:Medium |
| 5 | 🟢 console.logs left in (4 files) | L:Low · I:Low · E:Low |

**Any themes to dismiss?** I'll skip dismissed themes during the detailed review.
(Reply "none" to proceed with all, or list numbers to dismiss)

Wait for user response. The user may:

• Dismiss themes: "dismiss 3 and 4" → those won't be flagged or fixed
• Dismiss none: "none" or "go" → proceed with everything
• Add context: "3 is intentional, 4 is low priority" → record the reasoning

Step 1.2: Expand Scope via Pattern Ripple

Changed files may affect other files using the same patterns. Expand verification scope:

Index-Accelerated Ripple — If .shipkit/codebase-index.json exists, use concepts mapping to immediately identify related files by concept area (e.g., if a changed file is in concepts.auth, all auth files are in the ripple scope). This narrows the Explore agent's search significantly.

USE SUBAGENT FOR PATTERN RIPPLE - Launch Explore subagent for efficient parallel scanning:

Agent tool with subagent_type: "Explore"
Prompt: "Detect pattern ripple from these changed files: [list files]
[If index exists, include: 'The codebase index maps these concept areas: [list concepts with their files]. Use this to immediately identify same-concept files. Focus your scanning on cross-concept ripple effects the index doesn't capture.']

For each file, identify which patterns it uses:
- Auth: getSession, requireAuth, isAuthorized
- API Response: NextResponse, Response.json
- Error Handling: try/catch, .catch(
- Validation: zod, schema.parse
- Data Fetching: fetch, useSWR, useQuery

Then expand: find ALL other files using the same patterns.
Return: pattern type → list of affected files (both changed and ripple)."

Why subagent: Pattern ripple requires multiple parallel greps across the codebase. Explore agent handles this efficiently and returns a focused summary.

Fallback (if subagent unavailable) - Manual pattern detection:

| Pattern Type | Detection (in changed files) | Expansion (find all instances) | |--------------|------------------------------|--------------------------------| | Auth | getSession\|requireAuth\|isAuthorized | Grep all files with auth patterns | | API Response | NextResponse\|Response.json | Glob all API routes | | Error Handling | try\s*{\|\.catch\( | Grep async code for consistency | | Validation | zod\|schema\.parse | Grep all form/input handlers | | Data Fetching | fetch\(\|useSWR\|useQuery | Grep all data fetching code | | External Service | openai\|anthropic\|gemini\|stripe\|fetch\( | Grep all files with external calls, check for timeout/limits |

Expansion logic:

1. For each changed file, grep for pattern indicators
2. If pattern detected, expand scope:

• Auth pattern → Grep: pattern="getSession|requireAuth|isAuthorized" glob="**/*.{ts,tsx}"
• API route changed → Glob: pattern="**/api/**/route.{ts,js}"
• Validation pattern → Grep: pattern="zod|schema\.parse" glob="**/*.{ts,tsx}"

1. Add ALL matches to verification scope
2. Mark as RIPPLE:pattern-type in output

Scope categories:

| Category | Description | |----------|-------------| | CHANGED | Files in git diff (always checked) | | RIPPLE:auth | All files using auth patterns | | RIPPLE:api | All API routes (check consistent response shapes) | | RIPPLE:error | Files with error handling patterns | | RIPPLE:validation | Files with validation schemas |

Report ripple scope in output:

Reviewed: 3 changed + 7 ripple files
- Changed: src/api/trips/route.ts, src/lib/auth.ts, src/components/Form.tsx
- Ripple (auth): +4 files (detected auth pattern change)
- Ripple (api): +3 files (detected API route change)

When to expand:

• Auth file changed → Check ALL auth usages for consistency
• API route changed → Check other routes for response shape consistency
• Validation schema changed → Check all forms using that schema
• Error handling pattern changed → Check all async code for consistency

When NOT to expand:

• Simple typo fix in a comment
• Style-only changes
• Test file changes (contained scope)

Step 2: Read Context

Load relevant context for the review:

| File | Purpose | |------|---------| | Changed files | The actual code to review | | .shipkit/specs/active/* | Check spec compliance | | .shipkit/architecture.json | Check pattern consistency | | .shipkit/codebase-index.json | Find related code |

Step 3: Work Through Quality Dimensions

Review changes against these 12 dimensions, emphasizing based on what changed.

FOR LARGE CHANGE SETS (10+ files), USE PARALLEL SUBAGENTS:

Launch these Agent subagents IN PARALLEL (single message, multiple tool calls):

1. STRUCTURAL & SPEC AGENT (subagent_type: "Explore")
   Prompt: "Verify structural integrity and spec alignment for these files: [list files]
   STRUCTURAL: Check for orphan code, missing wiring, broken imports, circular deps, incomplete refactors.
   SPEC: If .shipkit/specs/active/* exists, verify implementation matches spec criteria.
   Report findings with file:line evidence and classification (NOT_CREATED, CREATED_UNUSED, WIRING_MISSING, etc.)."

2. ERROR & SECURITY AGENT (subagent_type: "Explore")
   Prompt: "Verify error resilience and security for these files: [list files]
   ERROR: Check for unhandled async, missing try/catch, empty state handling, swallowed errors.
   SECURITY: Check for auth on routes, input validation, SQL injection risk, hardcoded secrets, XSS, IDOR.
   Report findings with file:line evidence and severity (critical/should-fix/minor)."

3. STATE & PERFORMANCE AGENT (subagent_type: "Explore")
   Prompt: "Verify state management, edge cases, and performance for these files: [list files]
   STATE: Check for race conditions, stale state, missing loading states, N+1 queries.
   EDGE CASES: Check for empty states, boundary values, unicode, timezone issues.
   PERFORMANCE: Check for unnecessary re-renders, missing memoization, heavy deps, unoptimized queries.
   Report findings with file:line evidence."

4. UX & MAINTAINABILITY AGENT (subagent_type: "Explore")
   Prompt: "Verify UX completeness and maintainability for these files: [list files]
   UX: Check for loading indicators, action feedback, destructive confirmations, data-testid/ARIA attrs.
   MAINTAINABILITY: Check for magic numbers, duplicated logic, component duplication, missing types, TODOs, console.logs.
   Report findings with file:line evidence."

When to use parallel agents:

• 10+ files in change set (including ripple files)
• Multiple categories of changes (UI + API + DB)
• Deep verify requested

When to use single-pass:

• Small change set ( Run-scoped output (parallel-safe). verification-report.json is a transient per-run result. Under the orchestration engine, write/read it under the run root (/verification-report.json) per install/shared/references/run-artifacts.md; with no run context it stays at .shipkit/verification-report.json (back-compatible). Writer and readers resolve the same base.

---

The 12 Quality Dimensions

1. Structural Integrity

• Orphan code (defined but never used)
• Missing wiring (component exists but not rendered, route not registered)
• Broken imports (importing deleted/moved file)
• Circular dependencies
• Incomplete refactors (changed in one place, not others)

2. Spec & Intent Alignment

• Implementation matches active spec
• All acceptance criteria covered
• Edge cases from spec handled
• Feature actually solves the stated problem
• Fix didn't break the general case — if a bug spec exists (.shipkit/specs/active/bug-*.json), check that the fix handles the reported case WITHOUT regressing the happy path or other documented edge cases. Read fix.robustness.findings for what was considered.

3. Error Resilience

• Unhandled promise rejections
• Missing try/catch on async operations
• Empty/null/undefined states not handled
• API failure handling missing
• Missing error boundaries (React)
• Errors swallowed silently

4. State & Data

• Race conditions possible
• Stale cache / state issues
• Missing loading states
• Optimistic updates without rollback
• N+1 query patterns

5. Security

• Auth checks missing on new routes
• Input validation/sanitization missing
• Raw SQL queries (injection risk)
• Secrets/credentials in code
• XSS vulnerabilities
• IDOR (accessing other users' data)

6. Edge Cases

• Empty state not handled (zero items)
• Boundary values (0, negative, very large)
• Unicode/special characters
• Timezone issues
• Concurrent access scenarios
• Overengineered edge case handling — fix for one edge case broke or degraded the happy path or other cases (e.g., added loading guard that blocks normal render, validation so strict it rejects valid input, error handling that swallows success paths)

7. Performance Landmines

• Unnecessary re-renders
• Missing memoization where needed
• Heavy dependency for light use (moment.js for one format)
• Unoptimized queries
• Missing pagination on lists

8. UX Completeness

• Missing loading indicators
• No feedback on user actions
• Broken/incomplete flows
• Missing confirmation on destructive actions
• Inconsistent patterns vs rest of app
• Interactive elements missing data-testid or ARIA attributes (blocks AI testing)

8.5. Design System Compliance (when .shipkit/design-system/ exists)

• If changes include UI code and .shipkit/design-system/ exists: verify design tokens are used instead of hardcoded color/spacing/typography values, and component patterns align with design principles
• If .shipkit/design-system/ does not exist, skip this check entirely

9. Maintainability

• Magic numbers/strings
• Duplicated logic (same thing multiple ways)
• Component duplication (same component in multiple feature directories instead of shared)
• Not using shared components (shared version exists but feature has local copy)
• Similar-purpose components (Modal vs Dialog, Card vs Tile — should standardize)
• Confusing/misleading naming
• Missing types on public interfaces
• TODOs/FIXMEs left behind
• console.logs left in

10. Environment & Config

• New env vars not documented
• Hardcoded URLs/endpoints
• Works locally but will break in prod
• Docker/CI config not updated for new deps
• Missing feature flags for WIP features

10.5. External Service Boundaries

• External API calls without timeout config
• LLM/AI calls without token/output limits
• Serverless routes with external calls missing maxDuration export
• Streaming endpoints without keepalive signals
• Sequential external call chains without cumulative timeout tracking
• Pay-per-call services without cost visibility (token tracking, usage counters)

11. API Contract

• Breaking changes to existing endpoints
• Inconsistent response shapes
• Missing input validation
• Undocumented new endpoints
• Version compatibility issues

12. Database Integrity

• Schema changes without migrations
• Missing indexes on query patterns
• Orphan records possible (no cascading delete)
• Data type mismatches
• Missing foreign key constraints

---

Verification Integrity Protocol

Critical Rule: Never claim without evidence.

Every finding MUST be backed by actual tool output. Claims like "file not created" or "component unused" without verification are verification theater.

The 5-Step Verification Gate

Before reporting ANY finding, execute these steps:

| Step | Action | Example | |------|--------|---------| | 1. IDENTIFY | What tool call proves this claim? | "I need to confirm UserCard is unused" | | 2. RUN | Execute the tool call | Grep: pattern="UserCard" glob="**/*.{ts,tsx}" | | 3. READ | Examine full output | "Found 2 matches: definition + one import" | | 4. CLASSIFY | Determine exact state from evidence | "CREATED_USED (imported in Dashboard.tsx:14)" | | 5. REPORT | State finding WITH evidence | "UserCard is imported in Dashboard.tsx:14" |

Language Precision Rules

Use precise language that matches verification evidence:

| Claim | Required Evidence | Tool | |-------|-------------------|------| | "File not created" | Glob returns empty | Glob: pattern="**/UserCard.*" | | "File exists but unused" | Glob finds file AND Grep for imports returns 0 | Glob + Grep | | "Component orphaned" | File exists + no imports + no exports used | Glob + Grep | | "Import broken" | Import statement exists + target file missing | Read + Glob | | "Missing wiring" | Component exists + not rendered/registered anywhere | Grep for component usage | | "Circular dependency" | A imports B AND B imports A | Read both files |

Never say:

• ❌ "This file is not used" (without grepping for imports)
• ❌ "This component doesn't exist" (without globbing)
• ❌ "The route is missing" (without checking route registration)

Always say:

• ✅ "Grep for UserCard returned 0 matches → unused"
• ✅ "Glob for **/auth-callback.* returned empty → not created"
• ✅ "Found import UserCard but Glob for UserCard.tsx returned empty → broken import"

State Classification

Classify each finding into ONE of these states:

| State | Definition | Evidence Pattern | |-------|------------|------------------| | NOT_CREATED | File/component doesn't exist | Glob returns empty | | CREATED_UNUSED | File exists but nothing imports/uses it | Glob finds file + Grep returns 0 imports | | CREATED_WRONG | File exists but implementation doesn't matc

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stefan-stepzero
• Source: stefan-stepzero/shipkit
• License: MIT

Install and usage instructions live in the source repository linked above.