---
name: vrew-analyze
description: Investigate codebase behavior before fixing or changing it. Use when asked to find root causes, analyze regressions, assess the impact or side effects of a proposed code/config change, trace failures across layers, compare behavior by environment/input/config, determine blast radius, or produce an evidence-backed report.
---

# Codebase Cause and Impact Investigator

Investigate first. Choose one mode and keep the analysis focused. Use the other mode only as supporting context.

## Inputs

Collect or infer:

- Symptom: observed failure, error, regression, log, UI behavior, performance issue, or resource growth.
- Proposed change: code/config/default/behavior change to evaluate without applying.
- Reproduction conditions: OS, app version, build mode, input, timing, account state, feature flag, or hardware.
- Suspected area: files, modules, services, APIs, recent PRs, or config.
- Expected behavior.
- Scope: inspect only, run tests, modify code, or write a report.

If something important is missing, continue best-effort and mark it as unknown.

## Modes

### Cause Analysis

Use when the user asks why an observed symptom happens.

Start from the symptom, find evidence, trace back to the trigger and forward to the failure boundary. Identify the most likely root cause, affected conditions, blast radius, and verification. Check fix impact only enough to avoid recommending a harmful direction.

### Change Impact Analysis

Use when the user asks what happens if code/config/default behavior changes.

Do not modify code unless explicitly asked. Treat the proposed change as a hypothesis. Compare current behavior with proposed behavior, find existing dependencies on the current behavior, trace affected call sites and boundaries, and report side effects, compatibility risks, affected conditions, and verification. Check historical cause only when it explains why the current behavior may be intentional.

## Core Rules

- Start from evidence, not guesses.
- Prefer concrete references: file paths, functions, call sites, config keys, commits, commands, tests, and observed output.
- Separate facts, hypotheses, rejected hypotheses, and unknowns.
- Trace each layer boundary instead of jumping to conclusions.
- If evidence is insufficient to confirm the cause or expected impact, say so explicitly and provide the missing information needed plus how to obtain it.
- Do not recommend a fix or change until the likely cause or impact, affected paths, and verification method are clear.

## Workflow

### 1. Find Entry Points

Search exact evidence from the active mode:

- Error messages, logs, UI strings, analytics events, API names, status codes, feature flags, file names, extensions, or snapshots.
- Proposed code symbols, config keys, defaults, environment variables, imports, call sites, tests, mocks, or docs.

Pick up to 3 likely entry points. For each, record:

- File and function/component.
- Layer.
- Why it matches.
- Confidence: high, medium, or low.

Use these layers unless the codebase has clearer boundaries:

`ui -> client state -> runtime boundary -> service/library -> persistence/network/native/platform`

For Electron when relevant:

`react/ui -> renderer -> ipc/preload -> main -> chromium/web api -> native/gpu/os/driver`

### 2. Trace the Real Path

In Cause Analysis, trace backward to the trigger and forward to the failure boundary.

In Change Impact Analysis, trace outward from the proposed change to consumers, contracts, state, resource ownership, and runtime boundaries.

Inspect:

- Callers, callees, event handlers, subscriptions.
- Async tasks, workers, timers, cancellation, retries.
- State stores, derived state, defaults, fallbacks.
- IPC, RPC, network, DB, file, worker, native, or third-party boundaries.
- Serialization, deserialization, type conversion, swallowed errors, mapped errors, logs, and rethrows.

At each boundary, note what crosses it, how it changes, and who owns retry or cleanup.

### 3. Check Lifecycle and Conditions

When the issue involves state, resources, async behavior, leaks, or repeated actions, trace:

`create -> configure -> use -> suspend/retry -> cleanup/dispose`

Look for missing cleanup, success-only cleanup, cancellation/error/unmount gaps, duplicate creation, reuse after dispose, shared mutable ownership, queue growth, unbounded caches, sessions, pools, or temporary files.

Compare relevant condition axes:

- OS, app/build/runtime version, architecture.
- Feature flags, environment variables, experiments.
- File type, codec, size, duration, resolution, metadata.
- Account, permission, workspace, locale, region.
- Network/offline state, retry policy.
- Third-party library version or adapter.

Classify paths as always affected, condition-specific, or unknown.

### 4. Check Config and History Only When Relevant

If config, flags, build settings, or behavior switches matter:

- Locate definitions, readers, and writers.
- Trace how values reach runtime behavior.
- Compare dev, test, CI, production, and packaged defaults.
- Use git blame/log/diff to find when and why behavior changed.

For regressions, compare old and new behavior at the smallest meaningful boundary. Look for changed defaults, ownership moves, cleanup gaps, async ordering changes, broadened selectors, dependency-array changes, error-handling changes, or weakened tests.

### 5. Determine Blast Radius

Before recommending a fix, inspect affected:

- Imports and call sites.
- Shared utilities, adapters, stores, caches, pools, and config keys.
- Similar lifecycle patterns.
- Tests, mocks, telemetry, performance, security, compatibility, and user-visible behavior.

Risk:

- Low: isolated path, clear ownership, tests exist.
- Medium: shared code or multiple feature paths.
- High: cross-layer behavior, config defaults, lifecycle ownership, runtime/platform behavior, or weak tests.

### 6. Define Verification

State how to prove or disprove the root cause or impact hypothesis:

- Minimal reproduction or failing test.
- Existing tests to run.
- New regression test if needed.
- Temporary logs/instrumentation.
- Manual scenario matrix.
- Resource counters or profiling for lifecycle issues.
- Expected evidence if true.
- Expected evidence if false.

## Report Format

Return this structure:

```markdown
## Summary

- Symptom:
- Mode:
- Proposed change:
- Most likely root cause:
- Expected impact:
- Confidence:
- Affected conditions:
- Blast radius:
- Recommended next action:

## Evidence

Concrete file paths, functions, logs, commits, tests, commands, and outputs.

## Trace

Relevant call, data, or resource path.

## Root Cause / Impact Analysis

- Confirmed facts:
- Strong hypotheses:
- Rejected hypotheses:
- Unknowns:
- If not confirmed: missing information and how to get it:

## Blast Radius

Affected modules, features, users, tests, and possible side effects.

## Verification Plan

How to confirm or falsify the finding.

## Fix Direction

Minimal fix direction only. Do not write a large implementation plan unless asked.
```