# Business Analytics Project

## Build & Test
- Run analysis: `Rscript src/main.R` or `python src/main.py`
- Run tests: `Rscript -e "testthat::test_dir('tests')"`
- Generate report: `quarto render reports/monthly.qmd`

## Conventions
- Use tidyverse style for R (snake_case, |> pipe)
- All dates in ISO 8601 format (YYYY-MM-DD)
- CSV files go in data/raw/, processed data in data/clean/
- Visualizations: ggplot2 with our custom theme (R/theme_company.R)

## Architecture
- data/ -- raw and processed data files
- R/ -- reusable functions and utilities
- src/ -- main analysis scripts
- reports/ -- Quarto reports
- tests/ -- testthat test files

## Important
- Never commit files in data/raw/ (may contain sensitive client data)
- The "revenue" column is in USD cents, not dollars
- Always validate results against source data in data/clean/actuals.csv

---
paths:
  - "R/**/*.R"
  - "src/**/*.R"
---
# R Code Rules
- Use tidyverse conventions (snake_case, |> pipe operator)
- All functions must have roxygen2 documentation
- Use stopifnot() for input validation
- Prefer purrr::map() over base lapply()

---
paths:
  - "reports/**/*.qmd"
  - "reports/**/*.Rmd"
---
# Report Rules
- Use professional tone, no jargon
- Include executive summary at top
- All charts must have titles, axis labels, and source notes
- Tables must be formatted with kableExtra

# Project Instructions
@.claude/rules/r-conventions.md
@.claude/rules/data-pipeline.md
@docs/architecture-overview.md

# Phase 1: Explore (Plan Mode)
# Press Shift+Tab to enter Plan Mode
# "Read the files in R/forecast/ and explain the current forecasting approach"

# Phase 2: Plan
# "Create a detailed plan to add ARIMA forecasting alongside the existing
#  exponential smoothing. Show me what files to create and modify."

# Phase 3: Implement (switch to auto-accept)
# Press Shift+Tab to switch to acceptEdits mode
# "Implement the plan. Run the tests after each major change."

# Phase 4: Commit
# "Create a commit with a descriptive message explaining the ARIMA addition"

# Pipe data for analysis
cat data/clean/inventory_levels.csv | claude "Analyze this inventory data. \
Find items below safety stock and suggest reorder quantities."

# Reference multiple files
# In the Claude Code prompt:
# "Using @R/forecast.R and @R/inventory.R, create a combined
#  demand-forecast-to-reorder-point pipeline"

# Use shell output as context
# "The output of !Rscript -e 'sessionInfo()' shows my R setup.
#  Install any missing packages needed for time series analysis."

# Chain 1: Data Understanding
"Read data/raw/purchase_orders.csv and describe the schema,
data quality issues, and date range."

# Chain 2: Data Cleaning
"Based on your analysis, write an R script that cleans this data:
handle missing values, standardize date formats, remove duplicates."

# Chain 3: Analysis
"Using the cleaned data, calculate: average lead time by supplier,
on-time delivery rate, and order fill rate."

# Chain 4: Visualization
"Create a ggplot2 dashboard with 4 charts showing these KPIs.
Use our custom theme from @R/theme_report.R"

# Chain 5: Report
"Generate a Quarto report combining the analysis and visualizations
with executive summary and recommendations."

# Check context usage
/context

# Compact when getting large
/compact

# Delegate research to keep main context clean
"Use an Explore subagent to find all files that read from the
 inventory database and summarize the patterns used."

# Example Dashboard Prompt

Create a self-contained HTML dashboard for business KPIs.
Use Chart.js (CDN) for visualizations.

Data source: @data/clean/monthly_metrics.csv

Include these sections:
1. Header with date range and key metrics (revenue, margin, customer count)
2. Line chart: Monthly revenue trend (last 12 months)
3. Bar chart: Revenue by region or department (top 10)
4. Gauge chart: Current quarterly target progress vs goal
5. Table: Key accounts with status indicators and action items

Design: Professional, dark sidebar navigation, responsive layout.
Color scheme: Blue/slate corporate theme.
Include filters for date range and department.
Save as dashboards/business-kpi.html

# Quick analysis with piped data
cat data/raw/sales_data.csv | claude "Analyze this sales data. \
Show me: top 5 products by revenue, average deal size by region, \
and identify any transactions with unusual amounts (>3 std dev from mean)."

# In-session reference
# "Read @data/raw/customer_data.csv and create a summary report:
#  - Total customers by segment (enterprise/mid-market/SMB)
#  - Average lifetime value by acquisition channel
#  - Churn rate by cohort
#  - Save the analysis as an R script in R/customer_analysis.R"

# Report Generation Prompt

Generate the weekly business performance report using:
- Data: @data/clean/weekly_metrics.csv
- Template: @reports/templates/weekly_template.qmd
- Previous report: @reports/2026-W09.html (for comparison)

Structure:
1. Executive Summary (3-4 bullet points, highlight changes from last week)
2. KPI Dashboard (revenue, conversion rate, margin, customer satisfaction)
3. Team Performance (top/bottom 5 teams by goal attainment)
4. Risk Alerts (metrics trending below target, accounts at risk of churn)
5. Recommendations (2-3 actionable items)

Tone: Professional, data-driven, concise. Audience: VP / Department Head.
Render to reports/2026-W10.html

# Forecasting Prompt

Using @data/clean/monthly_revenue.csv (columns: date, segment, revenue):

1. For each segment, fit three models: ETS, ARIMA, and Prophet
2. Use last 3 months as holdout for validation
3. Select best model per segment by MAPE
4. Generate 12-month forecasts with 80% and 95% prediction intervals
5. Create a summary table: segment, best_model, MAPE, next_quarter_forecast
6. Visualize top segments with forecast bands
7. Flag any segments where all models have MAPE > 30% (needs manual review)

Save R script to R/revenue_forecast.R
Save forecasts to data/output/forecasts_12month.csv

# Risk Analysis Prompt

Create a business risk analysis tool in R:

1. Risk Matrix: Plot likelihood vs impact for risks in @data/risk_register.csv
   - Color code by risk category (financial, operational, market, regulatory)
   - Label high-risk items (likelihood * impact > 15)

2. Monte Carlo Simulation: For our revenue model in @data/clean/revenue_drivers.csv
   - Simulate 10,000 scenarios varying key assumptions (+/- 20%)
   - Calculate probability of missing quarterly target
   - Show P10, P50, P90 revenue outcomes

3. Concentration Analysis: Using @data/client_revenue.csv
   - Identify revenue concentration risk (top 10 clients as % of total)
   - Calculate revenue at risk if any top-5 client churns

Output: Interactive HTML report with all three analyses.
Save to reports/risk_analysis.html

# Build a data pipeline
# "Create an R script that:
#  1. Reads all CSV files from data/raw/monthly_exports/
#  2. Standardizes column names (snake_case)
#  3. Converts all dates to ISO 8601
#  4. Validates: no negative amounts, no future dates
#  5. Deduplicates by transaction_id
#  6. Joins with @data/reference/departments.csv for department names
#  7. Writes cleaned output to data/clean/transactions_combined.csv
#  8. Logs summary stats: rows processed, rows rejected, date range
#  Save as R/etl_transactions.R"

# R Project Configuration (for CLAUDE.md)

## R Environment
- R version: 4.4+ with Rscript at /usr/local/bin/Rscript
- Package manager: renv (run renv::restore() if packages missing)
- Run scripts: Rscript src/main.R
- Run tests: Rscript -e "testthat::test_dir('tests')"

## R Conventions
- Use tidyverse style: snake_case, |> pipe (not %>%)
- Prefer tibble over data.frame
- Use readr::read_csv() not base read.csv()
- Visualization: ggplot2 with theme_minimal() as base
- Dates: lubridate for all date manipulation
- Strings: stringr for all string operations

## Package Preferences
- Data manipulation: dplyr, tidyr, purrr
- Time series: forecast, tsibble, fable
- Optimization: lpSolve, ompr
- Reporting: quarto, kableExtra for tables
- Interactive: plotly for dashboards, DT for tables

# ROI and Break-Even Analysis with Claude Code
# Prompt: "Write R functions for ROI calculation and break-even analysis"

library(tidyverse)

calculate_roi <- function(investment, returns_monthly, months, discount_rate = 0.08) {
  # Simple ROI
  total_return <- sum(returns_monthly[1:min(months, length(returns_monthly))])
  simple_roi <- (total_return - investment) / investment

  # Net Present Value
  monthly_rate <- discount_rate / 12
  npv <- -investment + sum(returns_monthly / (1 + monthly_rate)^seq_along(returns_monthly))

  # Payback period (months)
  cumulative <- cumsum(returns_monthly)
  payback <- which(cumulative >= investment)[1]

  tibble(simple_roi = simple_roi, npv = npv, payback_months = payback)
}

# Scenario comparison
compare_scenarios <- function(scenarios_df, weight_col = NULL) {
  # Weighted scoring model for decision analysis
  if (is.null(weight_col)) {
    scenarios_df |> mutate(score = rowMeans(across(where(is.numeric))))
  } else {
    scenarios_df |> mutate(
      weighted_score = rowSums(across(where(is.numeric)) * .data[[weight_col]])
    )
  }
}

# Prompt: "Transform sales data into a team performance scorecard"

library(tidyverse)
library(lubridate)
library(scales)

team_scorecard <- read_csv("data/clean/sales_activity.csv") |>
  filter(activity_date >= today() - months(6)) |>
  group_by(team_id, team_name) |>
  summarise(
    total_deals      = n(),
    total_revenue    = sum(deal_value),
    avg_deal_size    = mean(deal_value, na.rm = TRUE),
    win_rate         = mean(status == "won", na.rm = TRUE),
    avg_cycle_days   = mean(days_to_close, na.rm = TRUE),
    customer_sat     = mean(csat_score, na.rm = TRUE),
    .groups = "drop"
  ) |>
  mutate(
    composite_score = 0.3 * win_rate + 0.3 * rescale(customer_sat) +
                      0.2 * rescale(total_revenue) + 0.2 * (1 - rescale(avg_cycle_days)),
    rank = min_rank(desc(composite_score)),
    tier = case_when(
      composite_score >= 0.9 ~ "Gold",
      composite_score >= 0.7 ~ "Silver",
      TRUE ~ "Bronze"
    )
  ) |>
  arrange(rank)

# Prompt: "Build a multi-model forecast comparison for our revenue segments"

library(tidyverse)
library(tsibble)
library(fable)
library(fabletools)

revenue_ts <- read_csv("data/clean/monthly_revenue.csv") |>
  mutate(month = yearmonth(date)) |>
  group_by(segment, month) |>
  summarise(revenue = sum(revenue), .groups = "drop") |>
  as_tsibble(key = segment, index = month)

# Fit multiple models
models_fit <- revenue_ts |>
  filter(month <= yearmonth("2025-09")) |>   # training set
  model(
    ets     = ETS(revenue),
    arima   = ARIMA(revenue),
    snaive  = SNAIVE(revenue)      # seasonal naive baseline
  )

# Forecast and evaluate
fc <- models_fit |>
  forecast(h = "6 months")

accuracy_tbl <- models_fit |>
  forecast(new_data = revenue_ts |> filter(month > yearmonth("2025-09"))) |>
  accuracy(revenue_ts) |>
  select(segment, .model, MAPE, RMSE) |>
  arrange(segment, MAPE)

# Select best model per segment
best_models <- accuracy_tbl |>
  group_by(segment) |>
  slice_min(MAPE, n = 1)

# Prompt: "Create a business theme and key visualizations"

library(ggplot2)
library(scales)

theme_business <- function(base_size = 12) {
  theme_minimal(base_size = base_size) +
  theme(
    plot.title = element_text(face = "bold", size = rel(1.2)),
    plot.subtitle = element_text(color = "grey50"),
    panel.grid.minor = element_blank(),
    panel.grid.major.x = element_blank(),
    legend.position = "bottom",
    strip.text = element_text(face = "bold")
  )
}

# Performance heatmap by team and month
team_performance <- ggplot(team_data, aes(x = month, y = reorder(team, -avg_score))) +
  geom_tile(aes(fill = goal_attainment), color = "white", linewidth = 0.5) +
  scale_fill_gradient2(
    low = "#EF4444", mid = "#F59E0B", high = "#10B981",
    midpoint = 1.0,
    name = "Goal Attainment"
  ) +
  labs(title = "Team Performance by Month", x = "Month", y = NULL) +
  theme_business()

# Revenue trend with target line
revenue_trend <- ggplot(monthly_metrics, aes(x = month, y = revenue)) +
  geom_line(linewidth = 1, color = "#4F46E5") +
  geom_point(size = 2, color = "#4F46E5") +
  geom_hline(yintercept = quarterly_target / 3, linetype = "dashed", color = "#EF4444") +
  annotate("text", x = max(monthly_metrics$month), y = quarterly_target / 3 * 1.02,
           label = "Monthly Target", hjust = 1, color = "#EF4444", size = 3) +
  scale_y_continuous(labels = dollar_format()) +
  labs(title = "Monthly Revenue", y = "Revenue") +
  theme_business()

# Prompt for Claude Code:

"Create a Quarto report template for our monthly business review.
File: reports/monthly_review.qmd

YAML header:
- Title: 'Monthly Business Review'
- Format: html with table of contents, code folding
- Parameters: month (default: current month), department (default: 'all')

Sections:
1. Executive Summary (auto-generated key metrics vs targets)
2. Revenue & Pipeline (actuals vs forecast, pipeline health)
3. Operational Metrics (productivity, throughput, cycle time)
4. Team Performance (goal attainment, headcount, engagement)
5. Cost Analysis (budget vs actual, cost per unit trends)
6. Action Items (auto-flagged items needing attention)

Each section should:
- Pull data from data/clean/ directory
- Include at least one ggplot2 visualization
- Show key numbers in callout boxes
- Compare current month vs previous month and vs target"

{
  "permissions": {
    "allow": [
      "Bash(Rscript *)",
      "Bash(quarto render *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(npm run test)",
      "Read",
      "Edit"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  }
}

# Add an HTTP MCP server (recommended)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Add a local stdio MCP server
claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

# Add PostgreSQL for business database queries
claude mcp add --transport stdio postgres \
  -- npx -y @anthropic-ai/mcp-postgres \
  "postgresql://user:pass@localhost:5432/business_data"

# List active servers
claude mcp list

# Verify connections
/mcp

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "Rscript -e 'styler::style_file(\"$TOOL_INPUT_FILE_PATH\")'"
      }]
    }],
    "Notification": [{
      "hooks": [{
        "type": "command",
        "command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
      }]
    }]
  }
}

# File: .claude/skills/sc-dashboard/SKILL.md
---
name: biz-dashboard
description: Creates a business KPI dashboard from CSV data
allowed-tools: Read, Write, Bash
argument-hint: <path-to-csv>
---

Create a self-contained HTML dashboard from the data at $ARGUMENTS.

Steps:
1. Read and analyze the CSV structure
2. Identify numeric columns suitable for KPIs
3. Create an interactive HTML dashboard with Chart.js
4. Include: summary cards, trend charts, comparison tables
5. Apply professional dark-sidebar theme
6. Save as dashboards/$(basename $ARGUMENTS .csv)-dashboard.html

# File: .claude/agents/data-validator.md
---
name: data-validator
description: Validates business data files for quality issues
tools: Read, Bash, Glob, Grep
model: sonnet
maxTurns: 10
---

You are a data quality validator for business data.
When given a file path, check for:
- Missing values in required columns
- Date format consistency
- Negative quantities or prices
- Duplicate records
- Values outside expected ranges
Report findings as a structured summary.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

# Start Claude in an isolated worktree
claude -w feature-arima-forecast

# This creates a separate copy of your repo
# Changes in the worktree don't affect your main branch
# Perfect for experiments, parallel features, or risky refactors

# Check current session cost
/cost

# Run with verbose output to see token counts
claude --verbose

# Check context utilization
/context

# Step 1: Setup (one-time)
claude /init
# Edit the generated CLAUDE.md with conventions, data locations, KPI definitions

# Step 2: Explore (Plan Mode -- Shift+Tab)
# "Read the CSV files in data/raw/ and describe schemas, date ranges,
#  data quality issues. Recommend a cleaning strategy."

# Step 3: Pipeline (/clear first!)
/clear
# "Create R/etl_pipeline.R that cleans and joins the raw data files.
#  Validate: no nulls in required columns, dates are valid, amounts > 0.
#  Output to data/clean/business_master.csv"

# Step 4: Analyze (/clear first!)
/clear
# "Using @data/clean/business_master.csv, create R/calculate_kpis.R:
#  - Revenue and margin by segment (last 6 months)
#  - Customer retention rate by cohort
#  - Revenue forecast (ETS) for top segments, 12-month horizon
#  - Goal attainment by team
#  Run the script and verify outputs."

# Step 5: Visualize (/clear first!)
/clear
# "Create a self-contained HTML dashboard from @data/output/kpi_summary.csv
#  and @data/output/forecasts.csv. Include: KPI cards, trend charts,
#  team scorecard table, forecast charts with prediction intervals.
#  Professional theme, responsive. Save as dashboards/biz-dashboard.html"

# Step 6: Deploy
/clear
# "Create a commit with all new files. Message should describe the
#  business analytics pipeline and dashboard."