Grill with Docs

Tell the expert what you are building and why you need their knowledge. Be explicit: “I am going to ask you questions one at a time. For each answer I'll either follow up or move to the next topic. We are building a glossary and capturing key decisions.”

Start with the most foundational term or concept in the domain. The first question is almost always: “What is the thing this system primarily tracks or manages?”

For every question, include what you believe the answer should be. This does three things: it shows you have engaged with the codebase, it surfaces disagreements immediately rather than at the end, and it cuts the expert's response time.

Question: What is a "Campaign" in this system?

Recommended answer: Based on the code, a Campaign appears to be a
container for one or more ad groups, scoped to a single advertiser
and billing period. Is this correct, and what am I missing?

Domain experts often describe how a thing is used rather than what it is. Push toward formal definitions:

• 'That describes when it's used. What is it?'
• 'If I had to write one sentence on a flashcard defining this term, what would it say?'
• 'Could this term mean something different in another system? How is your meaning distinct?'

After each answer, do one of three things before moving on:

1. Confirm and move: “Got it. Next question is...”
2. Follow up: “When you say X, do you mean Y or Z?”
3. Record a conflict: “That contradicts what I saw in the code at [location]. We should flag this as a decision point.”

Each entry is exactly: the term, a 1-2 sentence definition, and an optional Avoid line listing synonyms the team should not use.

## Campaign

A top-level container for a single advertiser's promotional activity
within one billing period. A Campaign owns one or more AdGroups and
carries the budget ceiling for the period.

_Avoid_: "project", "initiative", "flight" — these are used
informally but have no formal meaning in the system.

## Impression

One delivery of one creative to one device, regardless of whether
the user saw it. Impressions are counted at delivery time, not at
render time.

_Avoid_: "view", "exposure" — these imply user perception, which
is not what we track.

## Conversion

A user action that the advertiser has declared as valuable, recorded
after a click and within the attribution window. The specific action
(purchase, signup, page visit) is Campaign-scoped configuration.

_Avoid_: "goal", "event" — overloaded terms from analytics tools
that mean different things in different contexts.

• Any term that a new engineer would misread on first encounter.
• Any term that means different things in different parts of the codebase.
• Any term where the implementation differs from the plain English meaning.
• Any abbreviation or acronym used in variable names or database columns.
• Any business concept that has no equivalent in standard engineering vocabulary.
• The boundary between similar concepts: when is something an Event vs a Conversion vs an Interaction?

• Process or workflow descriptions — those go in README or runbooks.
• API endpoint documentation — that goes in API docs.
• How-to guides — those go in developer documentation.
• Implementation decisions — those go in ADRs.

When a glossary entry uses another glossary term, link it inline. This makes the glossary self-navigable and surfaces definitional dependencies.

## AdGroup

A named set of [Creatives](#creative) targeting a specific audience
segment within a [Campaign](#campaign). An AdGroup owns its own
budget sub-ceiling and targeting parameters.

# ADR-001: Store prices as integer cents

We store all monetary values as 64-bit integers representing the
amount in the smallest currency unit (cents for USD). This avoids
floating-point rounding errors in financial calculations at the cost
of always requiring unit conversion in display and input layers.

Alternatives considered: decimal(19,4) in Postgres; rejected because
application-level arithmetic on floats was causing silent rounding
discrepancies in tests.

---

# ADR-002: Single Postgres instance, no read replicas

The system currently runs a single primary Postgres instance with no
read replicas. Read traffic is handled by application-level caching
(Redis) rather than database-level replication. This simplifies
deployment and eliminates replication lag as a consistency concern,
at the cost of higher cache invalidation complexity.

---

# ADR-003: Event sourcing for order state

Order lifecycle is modeled as an append-only event log rather than
a mutable state record. This provides a complete audit trail and
enables retroactive projections at the cost of requiring an event
replay step to reconstruct current state in all read paths.

• Long prose explaining the decision history. That goes in a meeting note, not an ADR.
• Decision matrices or comparison tables. One sentence on what was rejected and why is enough.
• Status fields (proposed / accepted / deprecated). These become stale immediately.
• Author and date headers. Git blame provides that.
• Numbered sections with headers (Background, Decision, Consequences). The format is a title and a paragraph.

Search for every glossary term and its Avoid synonyms in the codebase. Flag every location where a banned synonym is used in a variable name, comment, or database column.

# Example: search for banned synonym "view" where "impression" is canonical
grep -r "view_count|total_views|page_view" src/ --include="*.ts"

# For each result, assess: is this a UI framework "view" (acceptable)
# or a metrics "view" meaning "impression" (needs renaming)?

Review README, inline comments, and docstrings for words like: similar, roughly, basically, kind of, usually, typically, should. Each occurrence is a candidate for sharpening.

• 'This function roughly normalizes the input' → what does it actually do?
• 'Users are usually authenticated by this point' → under what conditions would they not be?
• 'This should be called after setup()' → what breaks if it is not?

Look for code that enforces a rule without stating the rule. Add a comment or test asserting the invariant explicitly.

// Before: implicit invariant
if (campaign.budget > 0) {
  processBid(campaign);
}

// After: explicit invariant documented
// Invariant: campaigns with zero budget must not participate in bidding.
// Zero-budget state indicates a paused campaign; see ADR-007.
if (campaign.budget > 0) {
  processBid(campaign);
}

1. 1State the conflict explicitly in the grilling session: 'The glossary says X means Y, but I found Z in the code at [file:line]. Which is correct?'
2. 2Do not resolve the conflict yourself. Surface it to the domain expert.
3. 3If the expert is uncertain, flag the entry as [CONTESTED] in CONTEXT.md and schedule a follow-up.
4. 4Once resolved, update the glossary, then search the codebase for every instance of the losing term.

For each glossary entry, construct at least one scenario that could go either way and ask the expert to classify it.

Term: Conversion
Definition: A user action declared as valuable by the advertiser,
recorded after a click and within the attribution window.

Stress test scenarios:
1. A user clicks an ad, leaves the page, returns directly (not
   through the ad) 3 days later and purchases. Attribution window
   is 7 days. Is this a Conversion?
   → Tests: "after a click" — does the click need to be the
   direct referrer, or just the last tracked touch?

2. The same user clicks the same ad twice. They purchase once.
   How many Conversions are recorded?
   → Tests: deduplication behavior

3. The advertiser later changes the attribution window from 7 to 3
   days. Are past events retroactively reclassified?
   → Tests: mutability of conversion records

If a stress-test scenario requires a decision that is not already documented, run it through the three-gate ADR filter. Many ADRs emerge from stress-testing rather than from the initial interview.

One domain, one CONTEXT.md at the repository root. ADRs live in /docs/decisions/.

/
├── docs/
│   ├── decisions/
│   │   ├── ADR-001-integer-prices.md
│   │   ├── ADR-002-single-postgres.md
│   │   └── ADR-003-event-sourcing.md
├── CONTEXT.md          ← root-level, always loaded
└── src/

Each domain/service/package has its own CONTEXT.md and ADR directory. A root-level CONTEXT.md contains only cross-cutting terms.

/
├── CONTEXT.md              ← cross-cutting terms only
├── packages/
│   ├── billing/
│   │   ├── CONTEXT.md      ← billing-domain terms
│   │   └── docs/decisions/
│   ├── campaigns/
│   │   ├── CONTEXT.md      ← campaigns-domain terms
│   │   └── docs/decisions/
│   └── shared/
│       └── CONTEXT.md      ← shared utility terms