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

> Master UditAkhourii/adhd with best practices. Optimize invocation, tune RunOptions like framesPerRun and topK, mix frames, and separate models for cost effective LLM reasoning.

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

---

**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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts).

## Understand the Core Divergent-Convergent Architecture

ADHD splits reasoning into two distinct phases orchestrated by [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts), while human-readable output formatting is handled by [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts). The type definitions governing the entire flow are declared in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)).

```typescript
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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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:

```typescript
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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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:

```bash
npm test

```

The repository includes minimal tests in [`tests/llm.test.ts`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/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`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), this field surfaces the "aha!" insight that divergent thinking is designed to uncover, distinct from the more conservative `shortlist` candidates.