detect-product

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:

Layer	What	Example
Surface	Route, page, or screen	/pricing route, PricingPage.tsx
Copy	User-facing text	"Upgrade to Pro", pricing table copy
Code path	Business logic	checkSubscription(), Stripe API call

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

Argument	Effect
(none)	Light mode (default): Surface + business logic scan, single summary file
[repo]	Scan specified repo (applies to both modes)
--full	Full mode: All detection steps, 7 output files (current behavior)

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.)

Platform Type	Product Analysis Scope
web, mobile, androidtv, ios, android, desktop	Full feature detection (UI + business logic)
backend, api, services	Full feature detection (API endpoints, business logic, data models)
cli, cmd	Full feature detection (commands, flags, help text)

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:

File	Content
$JAAN_OUTPUTS_DIR/detect/product/overview{suffix}.md	Product overview with feature summary
$JAAN_OUTPUTS_DIR/detect/product/features{suffix}.md	Feature inventory with 3-layer evidence + related_evidence for cross-platform features
$JAAN_OUTPUTS_DIR/detect/product/value-prop{suffix}.md	Value proposition signals from copy
$JAAN_OUTPUTS_DIR/detect/product/monetization{suffix}.md	Monetization model with evidence
$JAAN_OUTPUTS_DIR/detect/product/entitlements{suffix}.md	Entitlement enforcement mapping
$JAAN_OUTPUTS_DIR/detect/product/metrics{suffix}.md	Instrumentation reality (analytics, flags, events)
$JAAN_OUTPUTS_DIR/detect/product/constraints{suffix}.md	Technical/business constraints and risks

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)