One concept per day, grounded in your repo

When `.codebase-coffee.md` is missing, every concept is already marked served, or the last scan is more than 30 days old, the skill announces a one-minute scan and builds a fresh curriculum.

The scan looks at repo structure, key modules, recent git history, and the places new hires usually ask humans about: error handling conventions, auth boundaries, architectural seams, and non-obvious helpers whose behavior is not clear from the call site.

It writes 20–30 ranked concepts to `.codebase-coffee.md` with file pointers and checkboxes. That file lives at your repo root and tracks what you have already had coffee on. On first creation, the skill may offer once to add it to `.gitignore` because the curriculum is personal.

On a normal day, the skill reads your curriculum, picks the highest-priority unserved concept (or matches a topic you named), reads only the two to four files that concept points to, and delivers the brief.

The contract is strict: under 100 words, no headers or bullet lists, no preamble. Order is pattern, why it exists, where it lives (one or two file:line references), one gotcha, then exactly "Go deeper?"

After the brief goes out, the skill checks the concept off with today's date and updates `last_served`. One concept per day unless you ask for another.

Before serving today's planned concept, the skill checks git history since your last served date. If someone else's commits introduced a notable new pattern or meaningful refactor, it may brief that instead and open with "New since last time:"

Queue-jump keeps coffee aligned with what changed, not only what was on the list when you first scanned. New topics get a curriculum line before they are marked served, so they receive the same repeat protection as everything else.

The skill does not rescan while unserved concepts remain and the last scan is under 30 days old—daily picks come from the existing list unless a teammate change wins.

If you answer yes to "Go deeper?", you get a short walkthrough: how the code works, why it is shaped that way, how it connects to neighbors, and where you can verify behavior yourself. It is a tour, not a review audit.

Walkthroughs append `| deep` to the concept line in `.codebase-coffee.md` so you have a record of which topics you explored beyond the daily brief.

Most days you will not need the walkthrough. The default is enough to stay oriented without turning literacy into another documentation project.

Imagine a backend service where meter readings must not double-count. Coffee might sound like this:

Meter dedupe uses an idempotent insert: `MeterReading` rows carry a source id, and a unique constraint on `(meter_id, source_id)` makes replays no-ops. That lives in `backend/meters/models.py` and the ingest path in `backend/meters/services.py:42`. Gotcha: the constraint fires on partial retries too, so callers must treat `IntegrityError` as success when the row already exists. Go deeper?

That is the whole product: one sharp paragraph tied to real files in your repo. Install from GitHub or read [install steps](/codebase-coffee/install) for your agent.