How selectFrames Biases Frame Selection for codeMode

When codeMode is enabled, selectFrames filters the candidate pool to only frames tagged with code or design, ensuring engineering-focused prompts while reserving one slot for a wild frame to maintain creative diversity.

The selectFrames function in the UditAkhourii/adhd repository controls which vantage-point prompts (frames) are sent to the LLM. This utility biases selection toward technical contexts when codeMode is active, balancing engineering precision with creative divergence through a tag-based filtering system defined in src/frames.ts.

How selectFrames Implements codeMode Bias

The biasing logic follows a four-step pipeline that prioritizes engineering frames while enforcing diversity guarantees.

Filtering the Candidate Pool by Tags

When codeMode is true (the default), selectFrames narrows the pool to frames whose tags array contains "code" or "design". This excludes general-purpose or non-technical frames from engineering tasks. If codeMode is false, the function uses the full FRAMES array without filtering.

const pool = codeMode
  ? FRAMES.filter((f) => f.tags.includes("code") || f.tags.includes("design"))
  : [...FRAMES];

(see src/frames.ts lines 34‑38)

According to the repository documentation, this behavior ensures that "codeMode (default true) biases selection toward code and design tags" (documentation/frames.md lines 28‑30).

Reserving Slots for Wild Frames

The function separately identifies frames tagged with "wild" to guarantee creative divergence regardless of the codeMode setting. These wild frames are collected into a distinct array before the main selection occurs.

const wild = FRAMES.filter((f) => f.tags.includes("wild"));

(see src/frames.ts line 40)

Documentation notes that "A wild frame always gets one reserved slot per run so divergence stays weird" (documentation/frames.md lines 28‑30).

Randomized Selection and Assembly

The candidate pool undergoes Fisher-Yates shuffling, then selectFrames selects the first n‑1 entries. A random wild frame is then appended if not already present, and the final list is trimmed to exactly n frames.

const shuffled = shuffle(pool);
const picked = shuffled.slice(0, Math.max(1, n - 1));
const wildPick = wild[Math.floor(Math.random() * wild.length)];
if (!picked.find((f) => f.id === wildPick.id)) picked.push(wildPick);
return picked.slice(0, n);

(see src/frames.ts lines 42‑46)

This ensures codeMode steers the selection toward engineering frames while still injecting creative perspective via the mandatory wild slot.

Practical Code Examples

Engineering-Focused Selection (Default codeMode)

When calling selectFrames without specifying codeMode, the function returns frames biased toward code and design contexts:

import { selectFrames } from "./src/frames";

const framesForCode = selectFrames(3);
// => 2 engineering‑biased frames + 1 guaranteed wild frame
console.log(framesForCode.map(f => f.label));
/*
  [
    "Hardware engineer",   // code + wild
    "Competitor trying to break it", // code + design
    "10-year-old"          // wild (guaranteed)
  ]
*/

General Diversity (codeMode Disabled)

Passing false as the second argument removes the tag filter, allowing any frame type:

const framesGeneral = selectFrames(3, false);
// => any three frames, possibly all wild or general
console.log(framesGeneral.map(f => f.label));
/*
  [
    "10-year-old",            // general + wild
    "Game design",           // design + general
    "Ant colony / swarm"     // code + wild
  ]
*/

Summary

• codeMode filters by tags: When enabled, only frames tagged "code" or "design" enter the candidate pool defined in src/frames.ts lines 34‑38.
• Wild frames are mandatory: One slot is always reserved for a frame with the "wild" tag to ensure output diversity.
• Randomization is uniform: The function uses Fisher-Yates shuffling before truncating to n‑1 entries, then appends the wild card.
• Repository location: All selection logic resides in src/frames.ts, with behavioral documentation in documentation/frames.md.

Frequently Asked Questions

What happens when codeMode is set to false in selectFrames?

When codeMode is false, the function bypasses the tag filter and copies the entire FRAMES array into the candidate pool. This allows general-purpose, non-technical, or purely creative frames to be selected alongside engineering frames.

Why does selectFrames always include a wild frame?

The wild frame guarantee ensures the LLM receives at least one creatively divergent or unconventional perspective per run. This prevents the output from becoming too homogeneous when codeMode heavily filters for technical frames.

How does selectFrames randomize the frame selection?

The function implements Fisher-Yates shuffling on the filtered candidate pool before selecting the first n‑1 entries. The wild frame selection uses Math.random() to pick from the isolated wild array, ensuring uniform probability distribution across all valid frames.

Where is the frame tag filtering logic located?

The tag filtering logic resides in src/frames.ts at lines 34‑38. The codeMode boolean determines whether the pool is filtered for "code" and "design" tags or includes all available frames from the FRAMES constant.

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