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

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, 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, 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.

// 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.

// 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—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 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.

// 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 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 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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}