name	trip-reconstruction
description	Fill gaps between checkpoints using hybrid GPS (70%) + address (30%) template matching with high confidence

Skill 3: Trip Reconstruction (GPS-First Matching)

Purpose: Automatically fill gaps between checkpoints using hybrid GPS (70%) + address (30%) template matching with high-confidence proposals

Activation: Automatic trigger after checkpoint creation shows gap, or manual request: "fill trips", "reconstruct from November 1"

Overview

Trip Reconstruction is Car Log's core innovation - using GPS-first hybrid matching to automatically propose trips based on recurring route templates. When a checkpoint gap is detected (e.g., 820km between refuels), the system matches against saved templates using precise GPS coordinates (70% weight) combined with address similarity (30% weight) to generate high-confidence proposals.

Key Innovation: GPS coordinates are the source of truth, enabling 90%+ confidence matches even when addresses are ambiguous ("Košice" could mean 3 fuel stations, but GPS 48.7164°N, 21.2611°E is exact).

Workflow (7 Steps)

Step 1: Gap Analysis

When a checkpoint is created, automatically analyze the gap to the previous checkpoint:

Distance gap (odometer delta)
Time gap (days between checkpoints)
Start/end locations (GPS + address)
Vehicle context

MCP Tool: car-log-core.analyze_gap(checkpoint1_id, checkpoint2_id)

User Message Pattern:

"Gap Analysis:
• Start: Bratislava (Nov 1, 45,000 km)
• End: Košice (Nov 8, 45,820 km)
• Distance: 820 km
• Duration: 7 days

How would you like to fill this gap?
1. Use my templates (automatic matching)
2. Tell me specific trips
3. I'll do it later"

Step 2: Template Fetching

If user chooses automatic matching, fetch all saved templates for the vehicle.

MCP Tool: car-log-core.list_templates(vehicle_id)

Considerations:

If no templates exist, suggest creating one from gap data
Templates must have GPS coordinates (mandatory for high-confidence matching)
Show template count and brief summary

Step 3: Template Matching (GPS-First Algorithm)

Run hybrid GPS + address matching using the core algorithm:

MCP Tool: trip-reconstructor.match_templates(gap_data, templates, gps_weight=0.7, address_weight=0.3)

GPS-First Scoring Algorithm:

GPS Distance Scoring (70% weight):

< 100m: Score 100 (perfect match - within parking lot variance)
100m-500m: Score 90 (excellent - same building area)
500m-2km: Score 70 (good - same neighborhood)
2km-5km: Score 40 (poor - different area)
5km: Score 0 (no match)

Address Similarity Scoring (30% weight):

Exact match: 100
Substring match: 80 ("Bratislava" in "Bratislava City Center")
City match: 60 (both contain same city name)
Levenshtein similarity: 0-100

Final Confidence Calculation:

confidence = (gps_score * 0.7) + (address_score * 0.3)

Bonus factors (up to +10%):
+ 5% if day-of-week matches template's typical_days
+ 5% if distance matches within 10km

Matching Mode Selection:

MODE_A (GPS-only): Both checkpoints have GPS, no addresses → GPS 100%
MODE_B (Hybrid): Both have GPS + addresses → GPS 70% + Address 30%
MODE_C (Fallback): No GPS, addresses only → Address 100% (low confidence)

Step 4: Proposal Presentation

Present matching results based on confidence tiers:

High Confidence (90-100%):

"Reconstruction Proposal (92% confidence):

✓ Exact GPS match (within 50m)
✓ Day-of-week matches template
✓ Distance matches expected route

Proposal:
2× Warehouse Run (Bratislava ↔ Košice)
• Nov 1-2: Bratislava → Košice (410km)
• Nov 6-7: Košice → Bratislava (410km)

Coverage: 820km / 820km (100%) ✓

This looks very reliable. Accept?"

Medium Confidence (70-89%):

"Reconstruction Proposal (75% confidence):

⚠️ GPS match is approximate (within 1.5km)
✓ City names match (Bratislava, Košice)
⚠️ Days don't match typical pattern

Proposal: 2× Warehouse Run (820km total)

This is likely correct, but please verify:
1. Did you drive to Košice on Nov 1?
2. Did you return to Bratislava on Nov 6?

Accept, modify, or reject?"

Low Confidence (<70%):

"No High-Confidence Match Found

I found potential matches, but none are above 70% confidence:
• Warehouse Run (58%) - Distance matches, but GPS is 8km off
• Client Visit (42%) - Wrong direction

Options:
1. Manually describe the trips
2. Create a new template for this route
3. Skip reconstruction for now"

Multiple High-Confidence Matches: Present all options sorted by confidence (descending) and let user choose the best match.

Step 5: User Approval

Request explicit approval before creating trips:

Accept proposal → Proceed to Step 6
Modify proposal → Allow trip adjustments
Reject → Offer manual entry or skip

Always require confirmation - never auto-create trips without approval.

Step 6: Batch Trip Creation

Create all approved trips in a single batch operation with Slovak compliance fields:

MCP Tool: car-log-core.create_trips_batch(trips[])

Required Slovak Compliance Fields:

driver_name: Full name (MANDATORY for Slovak VAT Act 2025)
trip_start_datetime: ISO 8601 format
trip_end_datetime: ISO 8601 format
trip_start_location: Address/label
trip_end_location: Address/label
distance_km: From template or calculated
purpose: "Business" or "Personal"
business_description: Required if Business purpose
reconstruction_method: "template"
template_id: Reference to matched template
confidence_score: Matching confidence

Step 7: Automatic Validation

Immediately after trip creation, run validation checks:

MCP Tools:

validation.validate_checkpoint_pair(checkpoint1_id, checkpoint2_id) - Check distance sum (±10% threshold)
validation.validate_trip(trip_id) - Check each trip's fuel efficiency

Validation Thresholds:

Distance sum: ±10% (odometer delta vs. sum of trip distances)
Fuel consumption: ±15% (expected vs. actual fuel)
Efficiency range: Diesel 5-15 L/100km, Gasoline 6-20 L/100km

User Message Pattern:

"✅ Validation Passed:
• Distance: 820km / 820km (0% variance) ✓
• Fuel: 72.8L / 69.7L (+4.4%, within 15% threshold) ✓
• Efficiency: 8.9 L/100km (Diesel range: 5-15) ✓

Your trips are ready for tax reporting!"

If validation warnings appear (e.g., fuel +25%), show clear explanation but don't block trip creation - allow user to review and adjust.

Related Skills

Auto-triggered after:

Skill 2 (Checkpoint from Receipt) → Gap detection

May trigger:

Skill 4 (Template Creation) → If no templates exist or no match found
Skill 6 (Data Validation) → Automatic validation after trip creation

Success Criteria

GPS matching uses 70% weight, address matching 30% weight
Confidence ≥70% required for automatic proposals
Multiple high-confidence matches presented with user choice
Stateless orchestration (Skill fetches all data, servers are stateless)
Automatic validation runs immediately after trip creation
Natural language proposals ("2× Warehouse Run" not "trip_001, trip_002")
Clear confidence breakdown shown to user
Slovak compliance fields mandatory (driver_name, VIN, etc.)
Coverage percentage calculated (distance covered / total gap)
User always has option to reject or modify proposals

Key Algorithms Reference

GPS Distance Calculation (Haversine):

distance = 2 * R * arcsin(√(sin²(Δφ/2) + cos(φ1) * cos(φ2) * sin²(Δλ/2)))
R = 6371 km (Earth radius)

Confidence Tiers:

90-100%: High (strong recommendation, minimal verification needed)
70-89%: Medium (likely correct, user verification recommended)
<70%: Low (do not show as automatic proposal)

Template Completeness Score: Essential fields (GPS coords): 60% Distance: +10% Typical days: +10% Purpose: +10% Business description: +10%

Implementation Status: Specification complete, implementation pending Estimated Effort: 5 hours Dependencies: car-log-core, trip-reconstructor, geo-routing, validation (all functional)

trip-reconstruction

Install Skill

SKILL.md