Khumalo & Grain Sales Analysis

Client: Naledi Khumalo, Cape Town furniture workshop Project: Analyze twelve months of sales data to determine channel profitability, product focus, and revenue trends for an eighteen-person artisan furniture workshop.

What you're building

You are profiling Naledi's sales data, computing channel profitability metrics against provided definitions, building four charts that answer her business questions, and writing a narrative with an executive summary, key findings, and recommendation. Every metric you compute has a verification target — your job is to direct AI through the analysis and verify its output against those targets.

Tech stack

Python 3.11+ (Miniconda "analytics" environment)
DuckDB (analytical database for SQL queries)
Jupyter Notebook (analysis environment)
pandas (data manipulation)
matplotlib / seaborn (charts)
Claude Code (AI assistant)
Git / GitHub (version control and delivery)

File structure

materials/
  CLAUDE.md              — This file. Project context and ticket list.
  data-dictionary.md     — Column-by-column documentation of the sales dataset
  analysis-spec.md       — Business questions, chart specs, verification targets, prompt starting points
  metric-definitions.md  — Precise definitions for all computed metrics
  khumalo-sales.csv      — Twelve months of furniture sales data (~845 rows)
  narrative-template.md  — Template for the client-facing analysis narrative

Key material references

analysis-spec.md — Your primary reference. Contains the four business questions, chart specifications for each, verification targets for every computed metric, and prompt starting points for each phase of work.
metric-definitions.md — How to compute each metric. Revenue excludes refunds. Profit margin accounts for retailer commissions. Revenue per workshop-week normalizes by production time.
data-dictionary.md — What each column means. Read this before querying the data. Negative sale_amount values are refunds.

Ticket list

T1: Read the brief, data dictionary, and metric definitions
T2: Load data into DuckDB and profile against data dictionary
T3: Compute all metrics and verify against targets
T4: Build four charts per analysis spec
T5: Draft narrative, review, deliver to client, push to GitHub

Verification targets

See analysis-spec.md Section 4 for all target values. Every computed metric must match. If AI's output does not match a target, the computation is wrong — check it against the metric definition before proceeding.

Commit convention

Prefix commits with ticket ID:

T1: read brief and data dictionary
T2: load and profile sales data in DuckDB
T3: compute channel revenue and verify against targets
T4: build revenue bar chart with descriptive labels
T5: draft executive summary and key findings