# What Does the Wildcard Frame Selection Guarantee in Each ADHD Run?

> Discover how wildcard frame selection guarantees each ADHD run incorporates creative prompts, ensuring diversity and stimulating new ideas in your generations.

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

---

**The wildcard frame selection guarantee ensures that every ADHD run includes at least one frame tagged with `wild`, forcing divergent, creativity-stimulating prompts into the generation pipeline regardless of mode constraints.**

The ADHD project (UditAkhourii/adhd) generates creative prompts through a curated frame selection system. According to the source code in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts), the `selectFrames` function enforces a strict **wildcard frame selection guarantee** that prevents over-constrained outputs by mandating the inclusion of unpredictable, provocative frames in every execution.

## How Wildcard Frame Selection Works

The selection algorithm operates in two phases: mode-based filtering and wildcard injection.

### Mode-Based Biasing

When `codeMode` is enabled, the frame pool is pre-filtered to include only entries tagged with `code` or `design`. This narrows the candidate set to technically relevant prompts. However, this filtering alone would risk producing homogeneous, predictable outputs.

### The Wildcard Guarantee Implementation

Regardless of the filtered pool size, the algorithm explicitly guarantees diversity through forced wildcard inclusion. As documented in the comment at lines 34-36 of [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts):

> "but always include at least one wildcard so divergence stays weird."

The implementation accomplishes this through three specific steps at lines 40-47:

1. **Isolation** – The function pulls a random frame tagged with `wild` (`wildPick`) from the complete, unfiltered `FRAMES` array.
2. **Injection** – This `wildPick` is appended to the `picked` array if not already present.
3. **Truncation** – The final array is sliced to the requested size, preserving the wildcard even when limiting total output.

This logic ensures that **every ADHD run contains at least one "wild"-tagged frame**, maintaining creative divergence even when the user requests code-specific frames.

## Implementation Details in selectFrames

The guarantee is hardcoded in the selection logic. When you call `selectFrames(n)`, the function first considers mode constraints, then unconditionally reserves a slot for divergence.

```ts
import { selectFrames } from "./frames";

// Request 3 frames in code-focused mode
const threeFrames = selectFrames(3);
// Always contains at least one frame with the "wild" tag
console.log(threeFrames.map(f => f.tags.includes("wild")));

// Request 2 frames with codeMode disabled
const twoAnyFrames = selectFrames(2, false);
// Wildcard guarantee still enforced
console.log(twoAnyFrames.some(f => f.tags.includes("wild"))); // true

```

In both examples, the resulting arrays will contain at least one frame whose `tags` property includes `"wild"` (such as `ten-year-old`, `biology`, or `speedrunner`).

## Impact on Generated Output

The guaranteed wildcard frame serves as a **creative provocation** within the pipeline. In [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) (lines 10-18), the engine extracts this specific wildcard frame to fuel "what if" scenarios that break conventional thinking patterns. By mandating this inclusion, the system prevents runs from becoming too narrow or deterministic, ensuring that even code-generation tasks receive an unexpected, divergent angle.

## Summary

- **`selectFrames` in [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts)** enforces unconditional inclusion of at least one `wild`-tagged frame.
- The guarantee persists **regardless of `codeMode` status**, applying to both filtered and unfiltered pools.
- Wildcard frames are **pulled from the full corpus** before any truncation occurs, ensuring they survive the final slice operation.
- This mechanism **fuels creative divergence** by injecting provocation into otherwise constrained generation runs.

## Frequently Asked Questions

### What is a wildcard frame in ADHD?

A wildcard frame is any prompt template in the `FRAMES` array that includes the string `"wild"` in its `tags` property. These frames introduce unexpected constraints or perspectives—such as viewing a problem through the lens of a "ten-year-old" or a "speedrunner"—to stimulate divergent thinking in the generation process.

### Does the wildcard guarantee apply when codeMode is disabled?

Yes. The guarantee is **unconditional**. Whether `codeMode` is `true` or `false`, the `selectFrames` function always executes the wildcard injection logic at lines 40-47 of [`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts), ensuring at least one divergent frame appears in every run.

### How does the wildcard frame affect the final output?

The wildcard frame extracted during selection is used in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) as a **provocation variable**. It forces the generation engine to reconsider the prompt from an unusual angle, often producing novel solutions that wouldn't emerge from standard code or design frames alone.

### Where is the wildcard selection logic implemented?

The core logic resides in **[`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts)** within the `selectFrames` function, specifically lines 34-47. This section handles both the mode filtering and the mandatory wildcard injection that defines the guarantee.