Best Practices for Using UditAkhourii/adhd: A Complete Guide to Divergent-Convergent LLM Reasoning

The best practices for using UditAkhourii/adhd involve selecting the optimal invocation mode (CLI, library, or skill), tuning RunOptions such as framesPerRun (5–7) and topK (2–3), strategically mixing wild and domain-specific frames from src/frames.ts, and separating your generation model from your critic model to balance cost and quality.

UditAkhourii/adhd is a TypeScript library and CLI tool that implements a divergent-then-convergent reasoning loop for LLM-driven agents. Following the best practices for using UditAkhourii/adhd ensures you maximize creative breadth during ideation while maintaining structured, actionable outputs through its rigorous two-phase architecture defined in src/engine.ts.

Understand the Core Divergent-Convergent Architecture

ADHD splits reasoning into two distinct phases orchestrated by src/engine.ts. Understanding this split is fundamental to configuring the tool effectively.

Divergence spawns N isolated frames, each generating ideas without visibility into the others. This parallel generation prevents convergence on the "obvious" solution too early. Convergence scores, clusters, prunes, and deepens the most promising ideas based on viability and novelty.

The frame definitions powering the divergence phase live in src/frames.ts, while human-readable output formatting is handled by src/render.ts. The type definitions governing the entire flow are declared in src/types.ts.

Choose the Right Invocation Mode

UditAkhourii/adhd supports three distinct execution contexts. Selecting the correct mode depends on your integration requirements:

• CLI Mode (adhd command): Best for quick interactive exploration and terminal-based prototyping. Example: adhd "design a rate-limiter".
• Library Mode (Node.js/TypeScript): Ideal for embedding ADHD into existing tools, custom orchestration, or automated pipelines. Import { run, renderText } from adhd-agent to receive a typed RunResult for downstream processing.
• Skill Mode (Claude Code, Codex, etc.): Use when you want an AI agent to invoke ADHD automatically from chat or IDE contexts via the /adhd command.

For automated scripts, prefer the library API because it provides structured data you can manipulate programmatically rather than just rendered text.

Tune RunOptions for Optimal Results

The run() function accepts a RunOptions object (defined in src/types.ts). Adjusting these parameters directly impacts output quality and token costs:

• framesPerRun: Set to 5–7 (default is 5). More frames increase diversity but multiply LLM calls.
• ideasPerFrame: Use 6–10 (default is 6) to give each frame sufficient material for meaningful scoring.
• topK: Limit to 2–3 (default is 3) to restrict deepening to only the most promising ideas, keeping runtime reasonable.
• concurrency: Adjust between 4–8 (default is 4) based on your API rate limits; higher values accelerate the divergent phase.
• stripAnchors: Keep true (default) to remove accidental implementation anchors that bias frames.
• codeMode: Enable true for software problems to bias frame selection toward code-oriented lenses; disable for pure design tasks.
• model and criticModel: Use the same model for generation, but optionally specify a stronger or cheaper model for scoring. The engine separates generator from critic to decorrelate errors (see lines 27–30 of src/engine.ts).

import { run } from "adhd-agent";

await run({
  problem: "How can we make our CI pipeline faster?",
  framesPerRun: 6,
  ideasPerFrame: 8,
  topK: 2,
  concurrency: 6,
  codeMode: true,
});

Leverage Frames Strategically

Frames are the creative lenses driving divergence. They are defined in the FRAMES array in src/frames.ts.

Mix wild and domain-specific frames. The selector automatically injects at least one "wild" frame (see lines 44–46 of src/frames.ts) to ensure unconventional angles.

Add custom frames for specialized domain knowledge. Create a Frame object with id, label, prompt, and tags, then inject it into the selection pool:

import { run, FRAMES, selectFrames } from "adhd-agent";
import type { Frame } from "adhd-agent";

const myFrame: Frame = {
  id: "edge-computing",
  label: "Edge-Computing Specialist",
  prompt: "Treat the problem as if it must run on constrained edge devices with intermittent connectivity.",
  tags: ["code", "design"],
};

const chosen = selectFrames(5, true);
chosen.push(myFrame);

await run({
  problem: "Optimize data sync for offline-first web apps",
  framesPerRun: chosen.length,
});

Keep prompts concise. Limit each frame's prompt to a single sentence to stay within token limits and maximize clarity.

Interpret RunResult Data Structures

run() returns a RunResult containing structured data fields. According to the src/types.ts definitions, interpret these key properties:

• branches: Raw ideas generated per frame. Use for diagnostics or custom clustering.
• clusters: Grouped ideas by underlying thematic angle.
• shortlist: Top-ranked viable ideas excluding traps. These are your primary implementation candidates.
• nonObviousPick: The highest-novelty viable idea—often the "aha!" suggestion.
• traps: Ideas flagged with hidden costs or risks. Review these before committing resources.
• deepened: Detailed action plans for the top-K ideas, turning concepts into specifications.
• provocation: A wild "what-if" question designed to keep brainstorming sessions alive.

Use renderText() from src/render.ts to format these fields for human consumption in terminal outputs. When integrating programmatically, skip rendering and process the structured data directly.

Control Costs and Performance

Because ADHD initiates multiple LLM calls per run, manage token usage through these strategies:

• Set explicit limits via ideasPerFrame, framesPerRun, and topK to cap maximum call volume.
• Use tiered models—deploy cheaper models (like gpt-4o-mini) for the divergent generation phase and reserve larger models (like gpt-4o) for the critic/scoring phase when you need higher fidelity.
• Cache results by storing the RunResult JSON when running identical problems repeatedly.

The separation of model and criticModel in src/engine.ts specifically supports this cost-optimization pattern.

Extend with Custom Frames and Testing

When adding custom frames or modifying default behaviors, validate your changes against the provided test suite:

npm test

The repository includes minimal tests in tests/llm.test.ts that verify JSON schemas (DivergeRowSchema, ScoreRowSchema, etc.) parse correctly. Ensure your custom frames conform to the expected type structures defined in src/types.ts to prevent runtime validation errors.

Summary

• Select the right mode: Use CLI for exploration, the library API for automation, and Skill mode for AI-assisted workflows.
• Tune divergence parameters: Configure framesPerRun (5–7), ideasPerFrame (6–10), and topK (2–3) to balance creativity against cost.
• Mix frame types: Combine built-in wild frames with custom domain-specific frames from src/frames.ts.
• Separate model concerns: Use cheaper models for generation and stronger models for criticism via model and criticModel options.
• Process structured results: Work directly with RunResult fields like shortlist, nonObviousPick, and traps rather than just rendered text.
• Validate changes: Run npm test to ensure schema compliance when extending frame definitions.

Frequently Asked Questions

What is the optimal framesPerRun setting for UditAkhourii/adhd?

The recommended range is 5–7 frames (default is 5). This count provides sufficient diversity across different cognitive angles without incurring excessive API costs. Values below 5 may limit creative breadth, while values above 7 risk diminishing returns relative to token spend, especially given that the engine automatically includes at least one "wild" frame to ensure unconventional thinking.

How do I add custom frames to the ADHD library?

Define a new Frame object with id, label, prompt, and tags properties, then inject it into the frame selection pool. Import the FRAMES array and selectFrames function from adhd-agent, create your custom frame conforming to the Frame type in src/types.ts, and push it into the selected frames array before passing to run(). Keep the prompt concise—ideally one sentence—to stay within token limits.

Can I use different models for generation and criticism in ADHD?

Yes. The RunOptions interface in src/types.ts exposes both model and criticModel parameters. Set model for the divergent generation phase and criticModel for the scoring/convergence phase. This separation, implemented in src/engine.ts (lines 27–30), allows you to use cost-effective models for ideation while employing stronger models for critical evaluation, optimizing both performance and budget.

How do I interpret the traps and nonObviousPick fields in RunResult?

The traps array contains ideas flagged by the critic as having hidden costs, implementation risks, or technical debt—review these before committing engineering resources. The nonObviousPick field contains the highest-novelty idea that still passed viability scoring, representing the most unconventional yet actionable solution. According to src/engine.ts, this field surfaces the "aha!" insight that divergent thinking is designed to uncover, distinct from the more conservative shortlist candidates.

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