---
title: "Track hit rate"
lesson_id: "04"
---

# Track hit rate

- **Lesson ID:** 04
- **Goal:** Count hits, misses, stale rows, and undos so the threshold can be defended.
- **Human lesson:** [04-track-hit-rate.html](04-track-hit-rate.html)

## Prerequisites

- Lesson 03 lookup function.

## Inputs, outputs, and artifacts

- **Inputs:** Lookup results and optional user undo.
- **Outputs:** Hit rate, wrong-hit rate, and on-device log lines.

## Agent build steps

1. Count lookups, hits, misses, stale, and undos.
2. Define hit rate as hits / lookups.
3. Define wrong-hit rate as undos / hits.
4. Keep question text on the device.
5. Raise the threshold when undos rise.

## Constraints

No analytics upload of questions. No em dashes.

## Key concepts

- Hit rate is hits divided by lookups. Also track wrong hits via undos and retries.
- Log threshold, best score, decision, and reason on every lookup.
- High hit rate plus a rising undo rate means raise the threshold.
- Ship a debug screen with hit rate, undo rate, and the last ten scores.

## Takeaways

- Hit rate alone is not enough. Watch wrong-hit rate.
- Do not lower the gate until undo rate is known.
- One log line per lookup is enough for a first review.

## Acceptance checks

- Both rates are defined.
- A debug screen is recommended.
- Agent brief link is present.