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

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. 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), 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. The model returns a JSON array where each entry contains scoring metrics plus the optional "trap" property.

// 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) 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:

// 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:

// 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.

// 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: Contains the core scoreIdeas() function and filtering logic at lines 381-384
• src/types.ts: Defines the Score interface with the optional trap property
• src/llm.ts: Provides the callLLM() wrapper used for critic evaluations
• 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, 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, 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 support this functionality by defining the optional trap field in the Score interface.

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