# How Trap Detection Works in the ADHD Scoring Phase: A Technical Deep Dive

> Discover how trap detection works in the ADHD scoring phase. Learn how a critic LLM identifies risky ideas and filters them while preserving them for user awareness.

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

---

**During the ADHD scoring phase, a critic LLM evaluates each generated idea for hidden costs and returns a structured `trap` field, which the engine uses to filter risky ideas out of the final shortlist while preserving them for user awareness.**

The **UditAkhourii/adhd** repository implements a structured ideation pipeline that separates viable concepts from attractive but risky proposals. During the convergent scoring phase, the system employs a specialized critic prompt to surface hidden pitfalls before they reach the final output.

## The Critic LLM and the SCORE_SYSTEM Prompt

Trap detection begins with explicit prompt engineering in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts). The `SCORE_SYSTEM` constant (lines 80-86) instructs the LLM to adopt a "CONVERGENT mode" mindset and produce dual signals for every idea: a required **strength** assessment and an optional **trap** description.

The prompt specifically directs the model to identify ideas that "look attractive but have a hidden cost," including false economies, scalability issues, or premature abstractions. According to the source code, the trap field must provide "a specific, actionable heads-up" rather than a dismissive verdict.

## How Trap Annotations Are Generated

When `scoreIdeas()` executes (lines 98-100 in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)), it builds a formatted prompt listing each idea with its `id :: text` structure and sends it to the LLM via the wrapper in [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts). The model returns a JSON array where each entry contains scoring metrics plus the optional `"trap"` property.

```typescript
// Conceptual flow from src/engine.ts lines 98-100
const scored = await callLLM({
  system: SCORE_SYSTEM,
  user: buildScorePrompt(ideas),
  schema: scoreSchema
});

```

Each `Score` type (defined in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)) includes the optional `trap?: string` field, allowing the system to capture natural language explanations of detected risks alongside numerical scores.

## Filtering and Exclusion Logic

Once scoring completes, the engine applies a two-stage filtering process to separate risky ideas from viable ones.

### Collecting Flagged Ideas

The engine first isolates ideas containing trap annotations:

```typescript
// From src/engine.ts lines 381-384
const traps = allIdeas.filter((i) => i.score?.trap);

```

This creates the `traps` array containing every idea flagged with hidden costs or structural weaknesses.

### Building the Viable Shortlist

Before ranking finalists, the system explicitly excludes trapped ideas from consideration:

```typescript
// Ranking logic from src/engine.ts lines 381-384
const ranked = allIdeas
  .filter((i) => i.score && !i.score.trap)
  .sort((a, b) => b.score!.total - a.score!.total);

```

This ensures only ideas free of hidden drawbacks proceed to the `shortlist`, while maintaining the trapped ideas in separate storage for transparency.

## Surfacing Traps in the Final Output

The collected traps are not discarded but exposed through the final `RunResult` interface. The engine returns both the ranked shortlist and the `traps` array, allowing users to see which ideas were filtered and why.

```typescript
// Excerpt from RunResult assembly in src/engine.ts
return {
  problem,
  reframe,
  branches,
  clusters,
  shortlist,      // Ideas passing trap detection
  nonObviousPick,
  traps,          // Array of ideas with trap explanations
  deepened,
  provocation,
};

```

This dual-path approach ensures the ADHD engine surfaces actionable risk information without polluting the recommendation set.

## Key Implementation Files

- **[`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)**: Contains the core `scoreIdeas()` function and filtering logic at lines 381-384
- **[`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)**: Defines the `Score` interface with the optional `trap` property
- **[`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts)**: Provides the `callLLM()` wrapper used for critic evaluations
- **[`bench/judge.ts`](https://github.com/UditAkhourii/adhd/blob/main/bench/judge.ts)**: Implements separate "trap_detection" evaluation metrics for benchmarking

## Summary

- **Prompt-driven detection**: The `SCORE_SYSTEM` prompt explicitly requests trap annotations for ideas with hidden costs
- **Structured capture**: Traps populate the optional `trap` field within each idea's `Score` object
- **Automatic filtering**: The ranking algorithm excludes trapped ideas via `!i.score.trap` checks before sorting
- **Transparency**: Flagged ideas remain accessible in the final `RunResult.traps` array for user review

## Frequently Asked Questions

### What triggers the trap detection mechanism in the ADHD engine?

Trap detection activates automatically during the scoring phase when `scoreIdeas()` processes generated concepts. The critic LLM evaluates every idea against the `SCORE_SYSTEM` prompt criteria, which explicitly asks the model to identify false economies, scalability limitations, or premature abstractions that appear attractive but contain hidden costs.

### How does the ADHD scoring phase distinguish between minor weaknesses and critical traps?

The system uses a dual-signal approach where every idea receives a required **strength** assessment, while **trap** annotations remain optional. The prompt instructs the LLM to reserve the trap field specifically for "actionable heads-up" scenarios involving structural risks rather than minor imperfections, ensuring only significant hidden drawbacks trigger exclusion from the shortlist.

### Are trapped ideas permanently discarded by the ADHD system?

No, trapped ideas are separated but preserved. While excluded from the ranked shortlist via the `!i.score.trap` filter in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), these ideas remain stored in the `traps` array and returned within the final `RunResult`. This allows users to review the specific risks identified while maintaining a clean list of viable recommendations.

### Which file contains the main trap detection implementation?

The primary logic resides in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts), specifically within the `scoreIdeas()` function (lines 98-100) for LLM invocation and the filtering operations (lines 381-384) that separate trapped ideas from the final shortlist. Type definitions in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) support this functionality by defining the optional `trap` field in the `Score` interface.