detect-product

Evidence-based product reality extraction: features, monetization, instrumentation, and constraints.

Context Files

• $JAAN_LEARN_DIR/jaan-to-detect-product.learn.md - Past lessons (loaded in Pre-Execution)
• $JAAN_CONTEXT_DIR/tech.md - Tech stack (for framework-aware scanning)
• $JAAN_TEMPLATES_DIR/jaan-to-detect-product.template.md - Output template
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol

Output path: $JAAN_OUTPUTS_DIR/detect/product/ — flat files, overwritten each run (no IDs).

Input

Arguments: $ARGUMENTS — parsed in Step 0.0. Repository path and mode determined there.

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: detect-product Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_detect-product

Standards Reference

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-shared-reference.md for Evidence Format (SARIF), Evidence ID Generation, Confidence Levels, Frontmatter Schema, Platform Detection, Document Structure, and Codebase Content Safety.

This skill's namespace: E-PRD-* (e.g., E-PRD-001, E-PRD-WEB-001) Tool name in frontmatter: detect-product

Cross-platform linking: Use related_evidence field to link findings of the same feature across different platforms (see Step 0 for examples).

Feature Evidence Linking — 3-Layer Model

"Feature exists" requires evidence across up to 3 layers:

Confidence mapping:

• All 3 layers found -> Confirmed
• 2/3 layers -> Firm
• 1 layer + heuristics -> Tentative
• Inferred only -> Uncertain

PHASE 1: Detection (Read-Only)

Step 0.0: Parse Arguments

Arguments: $ARGUMENTS

Mode determination:

• If $ARGUMENTS contains --full as a standalone token → set run_depth = "full"
• Otherwise → set run_depth = "light"

Strip --full token from arguments. Set repo_path to remaining arguments (or current working directory if empty).

Thinking Mode

If run_depth == "full": ultrathink If run_depth == "light": megathink

Use extended reasoning for:

• Feature evidence linking across 3 layers
• Monetization model inference
• Instrumentation taxonomy analysis
• Constraint and risk assessment

Step 0: Detect Platforms

Purpose: Auto-detect platform structure for multi-platform product feature tracking.

Use Glob and Bash to identify platform folders (same as detect-dev - see detect-dev Step 0 for full patterns and disambiguation rules).

Platform Detection

1. Check for monorepo markers: pnpm-workspace.yaml, lerna.json, nx.json, turbo.json
2. List top-level directories: Exclude node_modules, .git, build outputs
3. Match against platform patterns: Apply disambiguation rules
4. Handle detection results:
   • No platforms → Single-platform: platforms = [{ name: 'all', path: '.' }]
   • Platforms detected → Multi-platform: Ask user to select all or specific platforms

Product Detection Applicability

Product detection is FULLY applicable to ALL platform types (web, mobile, backend, cli, etc.)

Cross-Platform Feature Linking

When the same feature appears across multiple platforms, use related_evidence field to link findings:

Example: User Authentication across Web + Mobile

# In web/product/features.md:
evidence:
  id: E-PRD-WEB-015
  type: feature
  related_evidence: [E-PRD-MOBILE-023, E-PRD-BACKEND-042]
  description: "User authentication feature with OAuth support"
  layers:
    surface: "web/src/pages/login.tsx"
    copy: "Sign in with Google"
    code_path: "web/src/auth/oauth.ts"
  confidence: 1.0  # Confirmed (all 3 layers)

# In mobile/product/features.md:
evidence:
  id: E-PRD-MOBILE-023
  type: feature
  related_evidence: [E-PRD-WEB-015, E-PRD-BACKEND-042]
  description: "User authentication feature with OAuth support"
  layers:
    surface: "mobile/screens/LoginScreen.tsx"
    copy: "Sign in with Google"
    code_path: "mobile/services/auth.ts"
  confidence: 1.0  # Confirmed (all 3 layers)

# In backend/product/features.md:
evidence:
  id: E-PRD-BACKEND-042
  type: feature
  related_evidence: [E-PRD-WEB-015, E-PRD-MOBILE-023]
  description: "OAuth authentication API endpoints"
  layers:
    surface: "POST /api/auth/oauth"
    code_path: "backend/routes/auth.ts"
  confidence: 0.90  # Firm (2/3 layers - no UI copy in backend)

Rationale:

• Preserves traceability: each platform's findings stay in its own output file
• Enables detect-pack to identify cross-platform features in merged reports
• Allows confidence comparison across platforms (e.g., web has full 3-layer evidence, backend has 2-layer)

Analysis Loop

For each platform in platforms:

1. Set current_platform = platform.name
2. Set base_path = platform.path
3. Run detection steps per run_depth:
   • If run_depth == "full": Run Steps 1-5 scoped to base_path
   • If run_depth == "light": Run Steps 1 and 3 only scoped to base_path (skip Steps 2, 4, 5)
4. When feature is detected, check if it's already detected in another platform:
   • Search across other platforms' findings for matching feature by name/description
   • If match found, add cross-platform links via related_evidence
5. Use platform-specific output paths in Step 7

Note: If single-platform mode (platform.name == 'all'), output paths have NO suffix. If multi-platform mode, output paths include -{platform} suffix.

Step 1: Scan Routes and Screens (Surface Layer)

Identify all user-facing surfaces:

Route Detection

• Glob: **/pages/**/*.{tsx,jsx,vue} — file-based routing (Next.js, Nuxt)
• Glob: **/app/**/page.{tsx,jsx,ts,js} — Next.js app router
• Grep for route definitions: <Route, useRoutes, createBrowserRouter
• Grep for API routes: app.get(, router.post(, @Get(, @Post(

Screen/Page Inventory

For each route/page, extract:

• Route path
• Page/component name
• Public vs authenticated (look for auth guards, middleware)
• Feature domain (billing, settings, dashboard, etc.)

If run_depth == "light": Skip Step 2. Proceed to Step 3 (Scan Business Logic).

Step 2: Scan User-Facing Copy (Copy Layer)

Extract product-relevant text:

Value Proposition Signals

• Grep: **/landing*, **/home*, **/marketing* for taglines and value statements
• Grep for hero sections: <Hero, hero-section, landing-hero
• Extract: headlines, subheadlines, CTA button text

Pricing Copy

• Glob: **/pricing.*, **/tiers.*, **/plans.*
• Grep for pricing patterns: \$\d+, /month, /year, per seat, upgrade, downgrade
• Grep for tier names: free, starter, pro, enterprise, premium, basic

Feature Descriptions

• Grep for feature lists: features, capabilities, benefits
• Extract feature names and descriptions from marketing/product pages

Step 3: Scan Business Logic (Code Path Layer)

Monetization / Billing

• Grep for Stripe: stripe.subscriptions, stripe.invoices, stripe.checkout, stripe.prices
• Grep for PayPal: paypal, braintree
• Grep for custom billing: checkSubscription(), requiresPremium, userTier, planId
• Grep for entitlement gates: canAccess, hasFeature, isAllowed, checkPermission
• Grep for usage limits: rateLimited, usageCount, quota, limit

Entitlement Enforcement

• Grep for tier checks: user.plan, user.tier, subscription.status
• Grep for feature flags as gates: isFeatureEnabled, featureToggle
• Grep for middleware/guards: requiresAuth, requiresPlan, checkEntitlement

Distinguish "pricing copy" (what the product claims) from "enforcement" (what the code actually enforces). Gates must be proven by code locations; absence = "absence" evidence item.

If run_depth == "light": Skip Steps 4-5. Proceed directly to Step 6 (Present Detection Summary).

Note: In light mode, features are capped at Tentative confidence (1 of 3 evidence layers from surface scan only). Cross-platform related_evidence linking works but is degraded (no copy-layer features).

Step 4: Scan Instrumentation / Analytics

Analytics SDKs

• Grep: gtag('event' — Google Analytics 4
• Grep: mixpanel.track — Mixpanel
• Grep: analytics.track — Segment
• Grep: posthog.capture — PostHog
• Grep: amplitude.track — Amplitude
• Grep: plausible — Plausible Analytics

Feature Flags

• Grep: unleash.isEnabled — Unleash
• Grep: launchdarkly.variation, ldClient — LaunchDarkly
• Grep: splitio, getTreatment — Split.io
• Grep: flagsmith — Flagsmith
• Grep: FEATURE_, FF_ — custom feature flag patterns

Event Taxonomy

For each analytics call found, extract:

• Event name
• Properties/parameters
• Location (file:line)

Assess taxonomy consistency: naming convention, property standardization, coverage gaps.

Step 5: Scan Product Constraints

Technical Constraints

• Grep for rate limiting: rateLimit, throttle, rateLimiter
• Grep for file size limits: maxFileSize, MAX_UPLOAD, fileSizeLimit
• Grep for user limits: maxUsers, seatLimit, teamSize

Business Rules

• Grep for trial/expiration: trialEnd, expiresAt, gracePeriod
• Grep for geo-restrictions: allowedCountries, blockedRegions, geoRestrict
• Grep for compliance: GDPR, CCPA, HIPAA, SOC2, PCI

Risk Signals

• Features with routes but no tests
• Pricing copy without enforcement code
• Analytics events without consistent naming
• Entitlement checks with hardcoded values

HARD STOP — Detection Summary & User Approval

Step 6: Present Detection Summary

If run_depth == "light":

PRODUCT DETECTION COMPLETE (Light Mode)
-----------------------------------------

PLATFORM: {platform_name or 'all'}

FEATURES DETECTED: {n}
  Tentative (surface-layer): {n}
  Cross-platform:            {n} features linked via related_evidence

MONETIZATION
  Model:        {free|freemium|subscription|usage-based|one-time|none detected}
  Tiers:        {tier names or "none detected"}
  Enforcement:  {n} code gates found    [Confidence: {level}]

SEVERITY SUMMARY
  Critical: {n}  |  High: {n}  |  Medium: {n}  |  Low: {n}  |  Info: {n}

OVERALL SCORE: {score}/10

OUTPUT FILE (1):
  $JAAN_OUTPUTS_DIR/detect/product/summary{-platform}.md

Note: Features at Tentative confidence (surface layer only).
Run with --full for copy layer, instrumentation audit, constraint analysis,
and 3-layer evidence linking (7 output files).

"Proceed with writing summary to $JAAN_OUTPUTS_DIR/detect/product/? [y/n]"

If run_depth == "full":

PRODUCT DETECTION COMPLETE
---------------------------

PLATFORM: {platform_name or 'all'}

FEATURES DETECTED: {n}
  Confirmed (3-layer): {n}
  Firm (2-layer):      {n}
  Tentative (1-layer): {n}
  Inferred:            {n}
  Cross-platform:      {n} features linked via related_evidence

MONETIZATION
  Model:        {free|freemium|subscription|usage-based|one-time|none detected}
  Tiers:        {tier names or "none detected"}
  Enforcement:  {n} code gates found    [Confidence: {level}]

INSTRUMENTATION
  Analytics:    {tool names or "none detected"}
  Feature flags: {tool names or "none detected"}
  Events:       {n} tracked events

SEVERITY SUMMARY
  Critical: {n}  |  High: {n}  |  Medium: {n}  |  Low: {n}  |  Info: {n}

OVERALL SCORE: {score}/10

OUTPUT FILES (7):
  $JAAN_OUTPUTS_DIR/detect/product/overview{-platform}.md       - Product overview
  $JAAN_OUTPUTS_DIR/detect/product/features{-platform}.md       - Feature inventory
  $JAAN_OUTPUTS_DIR/detect/product/value-prop{-platform}.md     - Value proposition signals
  $JAAN_OUTPUTS_DIR/detect/product/monetization{-platform}.md   - Monetization model
  $JAAN_OUTPUTS_DIR/detect/product/entitlements{-platform}.md   - Entitlement enforcement
  $JAAN_OUTPUTS_DIR/detect/product/metrics{-platform}.md        - Instrumentation reality
  $JAAN_OUTPUTS_DIR/detect/product/constraints{-platform}.md    - Constraints and risks

Note: {-platform} suffix only if multi-platform mode (e.g., -web, -backend). Single-platform mode has no suffix.

"Proceed with writing 7 output files to $JAAN_OUTPUTS_DIR/detect/product/? [y/n]"

Do NOT proceed to Phase 2 without explicit approval.

PHASE 2: Write Output Files

Step 7: Write to $JAAN_OUTPUTS_DIR/detect/product/

Create directory $JAAN_OUTPUTS_DIR/detect/product/ if it does not exist.

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-shared-reference.md sections "Output Path Logic" and "Stale File Cleanup" for platform-specific suffix convention and run_depth cleanup rules.

If run_depth == "light": Write Single Summary File

Write one file: $JAAN_OUTPUTS_DIR/detect/product/summary{suffix}.md

Contents:

1. Universal YAML frontmatter with platform field, findings_summary, and overall_score
2. Executive Summary — BLUF of product findings
3. Feature Inventory — routes/screens with auth classification, Tentative confidence (from Step 1)
4. Monetization + Entitlement Summary — billing integrations, tier detection, code gates (from Step 3)
5. Top Findings — up to 5 highest-severity findings with evidence blocks
6. Note: "Features at Tentative confidence (surface layer only). Run with --full for copy layer analysis, instrumentation audit, feature flag detection, constraint analysis, and 3-layer evidence linking."

If run_depth == "full": Write 7 Output Files

Write 7 output files:

Note: {suffix} is empty for single-platform mode, or -{platform} for multi-platform mode.

Each file MUST include:

1. Universal YAML frontmatter with platform field and findings_summary/overall_score
2. Executive Summary
3. Scope and Methodology
4. Findings with evidence blocks (using E-PRD-{PLATFORM}-NNN or E-PRD-NNN IDs)
   • For cross-platform features, include related_evidence field linking to same feature in other platforms
5. Recommendations

Step 7a: Seed Reconciliation

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/seed-reconciliation-reference.md for comparison rules, discrepancy format, and auto-update protocol.

1. Read domain-relevant seed files: $JAAN_CONTEXT_DIR/tech.md, $JAAN_CONTEXT_DIR/integrations.md
2. Compare detection results against seed content (feature references, analytics tools, external integrations, monetization providers)
3. If discrepancies found:
   • Display discrepancy table to user
   • Offer auto-updates for non-destructive changes: [y/n]
   • Suggest /jaan-to:learn-add commands for patterns worth documenting
4. If no discrepancies: display "Seed files are aligned with detection results."

Step 8: Capture Feedback

"Any feedback on the product detection? [y/n]"

If yes:

• Run /jaan-to:learn-add detect-product "{feedback}"

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Evidence-based findings with confidence scoring
• Fork-isolated execution (context: fork)
• Output to standardized $JAAN_OUTPUTS_DIR path

Definition of Done

If run_depth == "light":

• Single summary file written to $JAAN_OUTPUTS_DIR/detect/product/summary{suffix}.md
• Universal YAML frontmatter with overall_score
• Feature inventory at Tentative confidence with evidence blocks
• Monetization + entitlement summary included
• "--full" upsell note included
• User approved output

If run_depth == "full":

• All 7 output files written to $JAAN_OUTPUTS_DIR/detect/product/
• Universal YAML frontmatter with platform field in every file
• Every finding has evidence block with correct ID format (E-PRD-NNN for single-platform, E-PRD-{PLATFORM}-NNN for multi-platform)
• Feature evidence uses 3-layer model with confidence mapping
• Cross-platform features linked via related_evidence field (if multi-platform)
• Monetization distinguishes "copy" from "enforcement"
• Absence evidence used where appropriate (not claims without evidence)
• Instrumentation taxonomy consistency assessed
• Confidence scores assigned to all findings
• Output filenames match platform suffix convention (no suffix for single-platform, -{platform} suffix for multi-platform)
• User approved output
• Seed reconciliation check performed (discrepancies reported or alignment confirmed)