car-value-dashboard

Car Value Dashboard -- Buyer Intelligence

Build or update an interactive HTML dashboard that analyses car listings to help make informed purchase decisions. Uses multivariate regression to score value, identify negotiation opportunities, and visualise depreciation curves. Fully config-driven from a car profile.

When to Use

• User asks to update or rebuild the depreciation/value dashboard
• User asks for depreciation analysis on their tracked car
• User wants to understand how age, mileage, or options affect values
• After running the car-search skill, to visualise the collected data

Prerequisites

1. An active car profile in ${CLAUDE_PLUGIN_DATA}/profiles/ (created via the setup-car-profile skill)
2. A CSV data file produced by the car-search skill, in the user's workspace at {profile_name}-searches/

If multiple profiles exist, ask which car to build the dashboard for.

Architecture

The dashboard is generated by a Python builder script at ${CLAUDE_PLUGIN_ROOT}/scripts/build_dashboard.py that:

1. Loads the car profile JSON for configuration
2. Loads the CSV data file
3. Runs multivariate OLS regression using config-driven features
4. Computes value scores, spec premiums, and depreciation curve polynomials
5. Pre-serialises all derived data as JSON
6. Writes a self-contained HTML file with Chart.js and embedded data

The script is fully config-driven via CLI arguments - do not copy, edit, or regenerate it per profile. Invoke it in place from the plugin via ${CLAUDE_PLUGIN_ROOT}/scripts/build_dashboard.py and let the profile JSON drive everything.

Data Sources

Car profile (user data, read-write, persists across updates)

${CLAUDE_PLUGIN_DATA}/profiles/{profile_name}.json

CSV data file (project artefact, in the user's workspace)

{profile_name}-searches/{profile_name}-all-listings-{YYYY-MM-DD}.csv

Listing IDs and price changes

These are maintained as dictionaries in the Python builder, keyed by composite key {price}_{location}. These are manually updated each search session. The builder script should include placeholder dictionaries that the user populates.

Listing ID date encoding

If profile.listing_id_date_encoding.enabled is true, extract dates from AutoTrader listing IDs (first 8 digits = YYYYMMDD) to calculate days on market.

Regression Model

Features (config-driven):

• intercept (always)
• age_months (always)
• mileage (always)
• spec_score (always -- computed from profile.spec_options weights)
• One binary feature per variant tier > 0 (e.g. is_tier_1, is_tier_2)

The variant features are generated dynamically from profile.variants:

for variant in profile["variants"]:
    if variant["tier"] > 0:
        features.append(f"is_tier_{variant['tier']}")

spec_score = sum of (boolean_value * spec_option.weight) for each spec in profile.spec_options.

Method: OLS via normal equations with Gaussian elimination and partial pivoting. No external libraries required.

Output per listing:

• predicted_price -- what the model expects this car to cost
• value_deviation -- actual minus predicted (negative = undervalued)
• value_deviation_pct -- deviation as percentage

Minimum data: Only cars aged >= 6 months are included in the regression to avoid skewing from brand-new stock.

Spec Premium Calculation

For each spec option in profile.spec_options, compare mean regression residual for cars with vs without that option. This isolates the market premium after controlling for age, mileage, and variant.

Requires at least 3 cars with and 3 without the spec for a valid comparison.

Dashboard Charts (5 total)

All chart configurations read variant names, colours, and labels from the profile.

1. Depreciation Curve (FULL WIDTH, TOP)

• Type: Scatter + fitted polynomial (degree 2) trend line per variant
• X-axis: Age in months
• Y-axis: Asking price
• Colours: From profile.variants[].colour
• Annotation: Auto-detects where the curve flattens (rate of loss halves)

2. Deal Score -- Value vs Expected (FULL WIDTH)

• Type: Horizontal bar (lollipop style)
• Data: Each listing's deviation from predicted price
• Colour: Green = undervalued, red = overpriced
• Labels: Location, variant, age, mileage
• Dynamic height: Canvas height adjusts to data count

3. Spec Premium Analysis (HALF WIDTH)

• Type: Horizontal bar
• Data: Average price premium per option (labels from profile.spec_options[].label)

4. Negotiation Radar (HALF WIDTH)

• Type: Scatter (quadrant chart)
• X-axis: Days listed
• Y-axis: % above/below expected price

5. Price vs Mileage (FULL WIDTH)

• Type: Scatter + regression trendline
• Coloured by variant using profile.variants[].colour

Data Table

Sortable table of all used listings. Fixed columns:

Column	Data
Variant	variant name
Age	age_years (1dp)
Price	asking price
Expected	predicted price
Value	deviation tag (green/blue/amber/red)
Mileage	odometer
Dep/yr	depreciation_pa (N/A for < 6 months)
Days	days_on_market
Trend	price_change arrow
Spec	spec labels from profile (highlighted tags for target options)
Location	dealer town (clickable link if URL available)

Default sort: best value first (lowest deviation).

Filters

All charts, KPIs, Market Pulse, and the table respond to filters:

• Variant: "All" + one option per profile.variants[].name
• Generation: "All" + one option per profile.generations[].label
• Max Mileage: "Any" + options from profile.dashboard.mileage_filter_options
• Budget: "Any" + options from profile.dashboard.budget_filter_options
• Value: All / Undervalued only / Overpriced only

Default selections use profile.dashboard.mileage_filter_default and profile.dashboard.budget_filter_default.

Market Pulse Panel

Shows rolling market health metrics:

• Active listings (filtered count)
• Sold/removed since last search
• New arrivals since last search
• Price reductions count and average drop
• Average days on market
• Median asking price

Note: sold/removed and new arrivals are currently hardcoded from manual comparison between search snapshots. Future versions could automate this by diffing CSV archives.

New Price Reference

Read from profile.generations[].new_prices. Used for depreciation calculations. Display in the dashboard for context.

Registration Date Mapping

Read from profile.reg_date_mapping. Used to convert UK reg plate codes to decimal dates for age calculation.

Styling

Read colours from profile.dashboard.theme:

• Page background: theme.bg
• Card background: theme.card_bg
• Card borders: theme.card_border
• Text: theme.text
• Muted text: theme.text_muted
• Variant colours: from profile.variants[].colour
• Highlighted spec tags: purple (#a78bfa) for specs where highlight is true

Font: system sans-serif stack. Responsive grid with mobile breakpoint at 900px. Chart.js 4.4.1 from CDN.

Output Files

The builder script lives in the plugin at ${CLAUDE_PLUGIN_ROOT}/scripts/build_dashboard.py and is never copied into user workspaces. User artefacts are saved to the {profile_name}-searches/ folder in the user's workspace:

1. Dashboard HTML: {profile_name}-dashboard.html -- self-contained, opens in browser
2. Raw data CSV: {profile_name}-all-listings-{YYYY-MM-DD}.csv -- date-stamped archive

Workflow Summary

1. Load the car profile from ${CLAUDE_PLUGIN_DATA}/profiles/{profile_name}.json
2. Check for existing CSV data in the {profile_name}-searches/ folder in the user's workspace
3. If data is stale (>2 days old) or user requests fresh data, run car-search skill first
4. Update LISTING_IDS and PRICE_CHANGES dictionaries in the profile (or a sidecar JSON) if new search data collected
5. Run python3 ${CLAUDE_PLUGIN_ROOT}/scripts/build_dashboard.py --profile "${CLAUDE_PLUGIN_DATA}/profiles/{profile_name}.json" --csv <latest.csv> to regenerate the dashboard
6. Present key findings to the user (R-squared, flattening point, top deals, spec premiums)

Important Notes

• Exclude brand new unregistered stock from regression and table (but include in CSV tagged as is_brand_new_stock)
• Check variant.standard_specs when interpreting spec data
• Use UK English throughout (organisation, colour, analyse, etc.)
• Composite keys (price_location) MUST be used for LISTING_IDS and PRICE_CHANGES to avoid duplicate location collisions
• Dep/yr shows N/A for cars under 6 months old to avoid absurd annualised figures
• The dashboard title comes from profile.dashboard.title