/biz-scan

name: biz-scan
description: "Scans codebase for revenue opportunities, KPIs, monetization gaps. Triggers: business metrics, KPI, analytics gaps, monetization, revenue."
effort: medium
disable-model-invocation: true
argument-hint: "[area]"
agent: business-intelligence
context: fork
allowed-tools: Read, Grep, Glob

Biz Scan Command

$ARGUMENTS

Triggers the Business Intelligence agent to analyze the codebase for business opportunities and KPI gaps.

Usage

/biz-scan [scope]
# /biz-scan schema     : focus on database models and entity relationships
# /biz-scan api        : focus on API endpoints and data exposure
# /biz-scan all        : full codebase scan

Protocol

1. Model Scan: Analyze Data Layer

Scan for business-relevant data structures:

# Find database models, schemas, entities
grep -rl "model\|schema\|entity\|migration" --include="*.py" --include="*.ts" --include="*.rb" .
# Find ORM definitions
grep -rl "prisma\|sequelize\|typeorm\|sqlalchemy\|activerecord" .

Catalog: entity names, relationships, fields that map to business concepts (revenue, subscription, usage, billing).

2. Logic Scan: Analyze Business Logic

Scan controllers, services, and use cases:

# Find API endpoints and handlers
grep -rn "router\.\|app\.\(get\|post\|put\|delete\)\|@Controller\|@app\.route" --include="*.ts" --include="*.py" --include="*.js" .
# Find tracking/analytics events
grep -rn "track\|analytics\|event\|metric\|log_event" --include="*.ts" --include="*.py" --include="*.js" .

Catalog: exposed endpoints, tracked events, feature flags, A/B tests.

3. Synthesis: Match Data vs. Business Goals

Cross-reference findings to identify:

| Category | What to Look For | |----------|-----------------| | **Missing KPIs** | Entities with no associated tracking events | | **Underutilized features** | Endpoints with no analytics or feature-flag coverage | | **Monetization gaps** | Subscription/billing entities without conversion tracking | | **Data exposure** | Rich internal data not surfaced via API |

4. Report: Generate Opportunity Report

Output a structured markdown report:

## Business Opportunity Report: [scope]

### KPI Coverage
| Entity/Feature | Tracked Events | Gap |
|---------------|---------------|-----|
| [name] | [events or "none"] | [what's missing] |

### Opportunities (ranked by estimated impact)
1. **[Opportunity]**: [description, affected entities, suggested action]

### Quick Wins
- [ ] Add tracking to [feature], estimated lift: [low/med/high]

### Data Exposure Gaps
- [Entity] has [N fields] not exposed via any API endpoint

Rules

• **MUST** tie every opportunity to a concrete business metric or KPI name — "improve onboarding" is not an opportunity, "increase trial-to-paid conversion" is
• **MUST** rank the opportunity list by estimated impact (rough order of magnitude is enough) — alphabetical order hides the signal
• **NEVER** propose a new tracking event without first checking for an existing one — duplicate events corrupt analytics pipelines
• **CRITICAL**: output is advisory. Do not modify tracking code in the scan. The product owner decides what ships.
• **MANDATORY**: when the codebase has no analytics layer at all, say so explicitly and stop — the gap is "no instrumentation", not "no opportunities".

Gotchas

• ORM models and TypeScript/Zod types often drift. An entity may exist in the DB schema but be invisible to the API layer (and vice-versa) — grep both sides before declaring "no tracking coverage".
• Feature flags without analytics wiring are invisible to most scans. A flag can gate a feature with zero rollout data; treat a flag-without-exposure as its own gap category.
• "No tracking event on entity X" often means X is tracked via a parent event (e.g., `order_items` piggybacking on `order_completed`). Walk the event taxonomy one level up before calling a gap.
• Revenue attribution in multi-tenant apps often splits client-side (page views, clicks) from server-side (conversions). Scanning only one side produces systematically wrong conclusions about monetization coverage.
• Migration files may show deleted columns that live code no longer references — always check the current schema (`alembic current`, `prisma migrate status`) before treating a migration-declared field as live.

When NOT to Use

• For **implementing** a tracking change — use `/fix` or the relevant language skill
• For dashboard design or SQL queries — delegate to the `data-analyst` agent
• For generic code-quality metrics — use `/analyze`
• For security or CVE scans — use `/cve-scan` or `/security-patterns`
• When the project has no product-analytics layer configured — document the gap, do not speculate on events