What Is the Provocation Field in ADHD and How Is It Generated?

The provocation field is a single wildcard question or idea that the ADHD engine selects from its generated frames to spark creative thinking, chosen specifically for having the lowest total score but highest novelty among asterisk-marked candidates.

In the UditAkhourii/adhd open-source engine, the provocation field appears as a string in the RunResult type and serves as the final output of the creative exploration process. This field contains a deliberately challenging prompt intended to push thinking beyond conventional solutions. Understanding how this value is derived from the engine's internal scoring algorithms is essential for developers integrating ADHD into creative workflows.

What the Provocation Field Represents

According to the type definitions in src/types.ts (lines 35-36), the provocation is documented as:

provocation: string; // single wild‑card question/idea

This provocation represents the ultimate "wild card" output of the engine—a free-form, open-ended question explicitly designed to spark further divergent thinking. Unlike other ideas in the result set that might represent viable solutions, the provocation intentionally targets the edge cases of the problem space. The field is always a string value and appears as the last component rendered in the textual output.

How the Provocation Is Generated in the ADHD Engine

The generation logic resides in src/engine.ts (lines 410-418), where the engine implements a selection strategy described in the source comments as:

"One provocation = a wild‑tagged frame's lowest‑scoring‑but‑highest‑novelty leaf"

This means the algorithm follows a two-phase filtering process after the deepening phase completes.

Filtering Wildcard Candidates

During execution, the ADHD engine generates multiple frames (branches of ideas). Some ideas within these frames are marked with an asterisk (*) to indicate they are wildcard leaves—concepts that deviate significantly from mainstream solutions. The engine first collects all ideas containing the wildcard character from across all branches in the run result.

Selection by Score and Novelty

From the filtered wildcard candidates, the engine applies a dual-criteria sort:

1. Lowest total score: Ideas are sorted by their score.total value in ascending order, prioritizing concepts that scored poorly on readiness or viability metrics.
2. Highest novelty: For ideas with identical scores, the algorithm selects based on score.novelty in descending order, favoring the most unexpected or unconventional concepts.

The text content of the idea ranking first after this sort becomes the provocation string returned in the final RunResult.

Rendering the Provocation Output

The textual representation of the provocation is handled in src/render.ts (lines 85-87), where the renderer formats this value as the final section of the output. The implementation displays the provocation with distinct visual styling—in the reference implementation, using yellow coloring—to distinguish it from the main solution branches and emphasize its role as a creative challenge rather than a definitive answer.

Practical Code Examples

Accessing the Provocation After a Run

When integrating the ADHD engine into your application, access the provocation directly from the RunResult object:

import { run } from "./src/engine";
import { renderText } from "./src/render";

async function exploreProblem() {
  const result = await run({
    problem: "How can we reduce onboarding friction for new developers?"
  });

  // Direct access to the provocation field
  console.log("Provocation:", result.provocation);
  // Example output: "What if the onboarding experience were completely voice‑driven?"

  // Full formatted output including the provocation section
  console.log(renderText(result));
}
exploreProblem();

Reproducing the Selection Logic

To understand or customize the provocation selection, examine the algorithm implemented in the engine:

import type { Idea, RunResult } from "./src/types";

/**
 * Implements the provocation selection logic from src/engine.ts.
 * Selects the wildcard idea with lowest total score but highest novelty.
 */
function selectProvocation(ideas: Idea[]): string {
  // Filter for wildcard-marked ideas
  const wildcardIdeas = ideas.filter(i => i.text.includes("*"));
  
  // Sort: lowest score first, then highest novelty
  wildcardIdeas.sort((a, b) => {
    const scoreA = a.score?.total ?? 0;
    const scoreB = b.score?.total ?? 0;
    
    if (scoreA !== scoreB) {
      return scoreA - scoreB; // Ascending by total score
    }
    return (b.score?.novelty ?? 0) - (a.score?.novelty ?? 0); // Descending by novelty
  });
  
  return wildcardIdeas[0]?.text ?? "";
}

// Usage with a RunResult
function extractProvocation(result: RunResult): string {
  const allIdeas = result.branches.flatMap(branch => branch.ideas);
  return selectProvocation(allIdeas);
}

Summary

• The provocation field in src/types.ts defines a string containing a single wildcard question or idea intended to provoke creative thinking.
• Generation occurs in src/engine.ts by filtering ideas marked with asterisks and selecting the candidate with the lowest total score but highest novelty.
• The field is rendered as the final section of output in src/render.ts, typically with distinct visual formatting to emphasize its challenging nature.
• Developers can access result.provocation directly from the RunResult object or analyze the selection logic using the score-based sorting algorithm implemented in the engine.

Frequently Asked Questions

What makes an idea eligible to become a provocation?

Only ideas explicitly tagged with a wildcard character (*) in their text are eligible for provocation selection. The engine filters the complete set of generated ideas across all branches to isolate these wildcard-marked candidates before applying the scoring-based selection algorithm described in src/engine.ts.

Why does the ADHD engine select the lowest-scoring idea for the provocation?

The engine deliberately chooses the lowest-scoring candidate because low scores indicate ideas that are least "ready-to-ship" or viable under conventional metrics. According to the implementation logic, these underperforming concepts often contain the most radical departures from standard solutions, making them ideal for provoking new lines of thought rather than providing safe answers.

How can I customize the provocation selection logic?

To modify selection behavior, fork the repository and adjust the sorting logic in src/engine.ts around lines 410-418. You could implement alternative weighting schemes that balance score and novelty differently, or add additional filtering criteria such as idea length or specific keyword presence, while maintaining the requirement to select from wildcard-tagged ideas.

Is the provocation field always populated in the RunResult?

While the type definition in src/types.ts defines provocation as a required string field, the engine's selection logic assumes at least one wildcard candidate exists in the idea set. If no ideas contain the asterisk marker, the current implementation would need to handle this edge case, though typical ADHD runs generate multiple wildcard-tagged frames during the deepening phase.

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