---
name: research-before-decision-guidance
description: Supporting rationale and examples for research-before-decision
enforcement: low
activation: on-demand
---

# research-before-decision — guidance

Authority: `aiwg show rule research-before-decision --body` (kernel). This companion supplies supporting explanation; the complete imperative core is self-contained in that rule.

## Overview

These rules mandate that agents research the codebase, documentation, and available sources before making technical decisions. Blind action without investigation is the single most common user complaint about AI coding assistants.

## Problem Statement

Agents frequently "yolo through" problems:
- Guessing API usage instead of reading docs
- Making technology choices without checking what's already in the codebase
- Retrying failed approaches blindly instead of investigating root cause
- Assuming configuration values instead of reading config files
- Inventing function signatures instead of checking the actual source

This produces whack-a-mole debugging loops where the agent makes a change, it fails, the agent tries something slightly different, it fails again — never stopping to actually understand the problem.

## Examples

### Rule 1: Research Before Technical Decisions

**FORBIDDEN**

```
Agent sees error → immediately tries a fix → fails → tries another fix → fails → ...
Agent needs API call → guesses the endpoint and parameters
Agent needs configuration → assumes default values
Agent picks a library → doesn't check what the project already uses
```

**REQUIRED**

```
Agent sees error → reads error message carefully → searches codebase for context →
reads relevant files → understands the cause → applies targeted fix

Agent needs API call → reads API docs/types/source → constructs correct call

Agent needs configuration → reads config files → uses actual values

Agent picks a library → checks package.json/requirements.txt → uses what exists
```

### Rule 3: The Research-Then-Act Pattern

```
1. IDENTIFY what you need to know
2. SEARCH for that information (grep, glob, read, web search)
3. EXTRACT the relevant facts from search results
4. REASON about the right approach based on evidence
5. ACT with confidence backed by research
6. VERIFY the action succeeded
```

### Rule 4: Re-Research on Failure

**FORBIDDEN**

```
Attempt 1: import { foo } from './utils'     → Error: not found
Attempt 2: import { foo } from '../utils'    → Error: not found
Attempt 3: import { foo } from '../../utils' → Error: not found
```

**REQUIRED**

```
Attempt 1: import { foo } from './utils'     → Error: not found
Research:  grep for "export.*foo" across codebase
Finding:   foo is exported from src/helpers/validation.ts
Fix:       import { foo } from '../helpers/validation'
```

### Rule 5: Read Error Messages Completely

**FORBIDDEN**

```
Error: Cannot find module '@/utils/auth' - Did you mean '@/lib/auth'?
Agent: *ignores the suggestion, tries random paths*
```

**REQUIRED**

```
Error: Cannot find module '@/utils/auth' - Did you mean '@/lib/auth'?
Agent: The error suggests '@/lib/auth'. Let me verify that path exists,
       then use it.
```

### Rule 6: Check Existing Patterns Before Creating New Ones

**FORBIDDEN**

```
Task: Add a new API endpoint
Agent: *writes endpoint from scratch with own conventions*
```

**REQUIRED**

```
Task: Add a new API endpoint
Agent: Let me check existing endpoints to match the project's patterns.
       *reads src/routes/ directory*
       *reads an existing endpoint file*
       *follows the same structure, middleware, error handling patterns*
```

## Detection Patterns

### Signs of Missing Research

| Pattern | Detection | Correct Response |
|---------|-----------|------------------|
| Guessed import path | Module not found errors on first attempt | Search for actual export location |
| Wrong API parameters | Type errors or runtime parameter mismatches | Read function signature/types |
| Assumed config value | Configuration-related failures | Read actual config file |
| Random path attempts | Multiple "file not found" errors in sequence | Glob for actual file location |
| Invented function names | "X is not a function" errors | Read the module's exports |
| Style mismatch | PR review comments about conventions | Read existing code for patterns |

### Whack-a-Mole Detection

If the agent makes 3+ sequential failed attempts at the same category of action without performing a search/read operation in between, this is a whack-a-mole loop. The agent MUST:

1. **Stop** attempting variations
2. **Research** by reading relevant source files, docs, or running diagnostic commands
3. **Understand** the root cause from the research
4. **Then** make a single informed attempt

## Integration with Thought Protocol

The Research thought type triggers this rule:

```
Research: I need to find out how this project handles authentication
          before I add the new auth middleware.

Action: grep for "authenticate" in src/ directory
Action: read src/middleware/auth.ts

Extraction: The project uses JWT with refresh tokens. Middleware is
            registered in src/app.ts. Token validation uses jose library.

Reasoning: I should follow the existing pattern using jose and register
           my new middleware in src/app.ts alongside the existing one.
```

## Integration with Anti-Laziness

Research-before-decision complements anti-laziness:
- Anti-laziness prevents destructive shortcuts (deleting tests, removing features)
- Research-before-decision prevents uninformed action (guessing, assuming, yoloing)

Both address the same root cause: agents taking the path of least resistance instead of doing the work to get it right.

## Integration with TAO Loop

In the Thought-Action-Observation loop:
- **Thought** must include what needs to be researched
- **Action** must include search/read operations before modification operations
- **Observation** must extract facts that inform the next action

A TAO iteration that goes Thought→Edit→Error without any Read/Search/Grep action is a violation of this rule.

## Platform Applicability

This rule applies universally across all AI coding platforms:
- Every supported provider
- Any agent that modifies code or makes technical decisions

Research is not optional. It is the minimum bar for competent assistance.
