# How the ADR‑HD Engine Generates Provocation from the Wildcard Frame's Highest‑Novelty Idea

> Discover how the ADR-HD engine generates provocation by selecting the highest novelty idea from a wildcard frame and reframing it into a thought-provoking question.

- Repository: [Udit Akhouri/adhd](https://github.com/UditAkhourii/adhd)
- Tags: deep-dive
- Published: 2026-08-19

---

**The ADR‑HD engine generates the provocation by selecting the single idea with the highest `novelty` score from the wildcard frame, then wrapping its text into the reframing question, `What if we took this seriously: ${wildcard.text}?`**

The `UditAkhourii/adhd` repository implements an ADR‑HD engine that runs ideas through divergence, scoring, and clustering phases. At the end of a run, the system surfaces one final provocation generated from the wildcard frame's highest-novelty idea to highlight the most unexpected viable direction. This ensures the user receives a concrete, thought-provoking prompt derived directly from the model's most novel discovery.

## Scoring Ideas to Enable Wildcard Selection

Before the provocation can be built, every candidate `Idea` must carry a quantitative novelty rating. During Phase 1 and Phase 2 of the engine pipeline, the `scoreIdeas` and `clusterIdeas` routines evaluate each idea and attach a `score` object. As defined in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts), this object includes a `novelty` field that ranks the idea's unexpectedness relative to the explored space.

Only ideas that successfully pass through scoring hold a valid `score`; any unscored entries are excluded from wildcard contention. This filtering step guarantees that the eventual provocation draws from a rigorously evaluated pool.

## Selecting the Highest‑Novelty Wildcard in src/engine.ts

The wildcard selection logic lives in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), where the engine collapses the full idea set into a single highest‑novelty candidate. The implementation first filters out ideas missing a `score`, then sorts the remainder by descending `novelty` and takes the first element.

```ts
// src/engine.ts – wildcard selection (approx. lines 410-417)
const wildcard = allIdeas
  .filter((i) => i.score)                     // keep only scored ideas
  .sort((a, b) => b.score!.novelty - a.score!.novelty)[0]; // highest novelty

```

This `wildcard` represents the most novel viable idea uncovered during the session. By pinning the provocation to this specific record, the engine ensures the final prompt is anchored to the insight that is statistically most distinct from the mainstream cluster.

## Constructing the Provocation String

Once the wildcard is isolated, the engine translates it into a human-readable provocation. If a wildcard exists, its text is injected into a template literal that reframes the idea as an inviting question. If the scored set is somehow empty, the engine falls back to a generic placeholder.

```ts
// src/engine.ts – provocation construction
const provocation = wildcard
  ? `What if we took this seriously: ${wildcard.text}`
  : "What's the assumption nobody named yet?";

```

The resulting string is stored on the `RunResult` type—declared in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)—under the `provocation: string` field. This design keeps the generation logic decoupled from presentation, allowing the same provocation to be rendered across multiple output formats.

## Rendering the Provocation in src/render.ts

The terminal renderer in [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) receives the finalized `RunResult` and prints the provocation as part of the closing output. It applies bold formatting to the label and yellow coloring to the question text, making the wildcard insight immediately visible to the user.

```ts
// src/render.ts – terminal output (approx. lines 85-87)
out.push(bold("Provocation"));
out.push("  " + yellow(r.provocation));

```

Because the provocation is already fully formed when it reaches the renderer, [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) does not mutate the string; it only handles visual formatting. This separation of concerns keeps the engine's scoring and selection logic isolated from UI details.

## Summary

- The provocation is always drawn from the single idea with the highest `novelty` score, known as the wildcard frame.
- [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) filters unscored ideas, sorts by descending `novelty`, and selects index `[0]` as the wildcard.
- If a wildcard exists, the engine produces the string `` `What if we took this seriously: ${wildcard.text}` ``; otherwise it emits a generic fallback.
- The final string travels inside `RunResult` to [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts), where it is printed with bold and yellow terminal styling.

## Frequently Asked Questions

### What is the wildcard frame in the ADR‑HD engine?

The wildcard frame is the single `Idea` that achieves the highest `novelty` score after the engine has filtered out all unscored candidates. It represents the most unexpected yet viable direction discovered during the divergence and clustering phases, and it serves as the sole source for the final provocation.

### How is novelty calculated for each idea?

The raw analysis indicates that novelty is assigned during Phase 1 by the `scoreIdeas` routine and refined through `clusterIdeas` in Phase 2. Each evaluated `Idea` receives a `score` object containing a `novelty` numeric field, but the specific algorithmic formula is internal to those scoring functions and not exposed in the provocation generation layer.

### What happens if no ideas receive a novelty score?

If every idea lacks a `score` object—an edge case the analysis describes as unlikely—the engine bypasses wildcard selection and assigns a fallback provocation: `"What's the assumption nobody named yet?"`. This guarantees that the `RunResult` always contains a usable string even when the scoring pipeline yields no rated candidates.

### Where is the provocation displayed to the user?

The provocation is rendered in [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts), where the terminal output builder pulls `r.provocation` from the `RunResult` object. It prints the label in bold and the question itself in yellow, ensuring the wildcard frame's highest-novelty idea stands out as the final takeaway of the session.