---
name: research-first-workflow
description: Always create a research/technical analysis document before planning. Use ADRs as immutable architectural truth. Document hierarchy: ADR → Architecture → Research → Plan → Code.
version: 1.0.0
metadata:
  filePattern: "**/*.md"
priority: 85
---

# Research-First Workflow

## The Rule
**Never jump straight to implementation.** Create a research document first.
One focused file for the LLM to read beats scanning 50 codebase files.

## Document Hierarchy

```
ADR (immutable, authoritative truth)
  ↓ informs
Architectural Document (stable reference, rarely changes)
  ↓ informs
Research / Technical Analysis (per-feature, reference artifact)
  ↓ informs
Implementation Plan (per-task, ephemeral — discard after use)
  ↓ executes
Code
```

## Research Document Template

```markdown
# Research: [Feature/Problem Name]

## Problem Statement
[What are we solving and why]

## Constraints
[Tech stack, team size, timeline, compliance requirements]

## Options Considered
| Option | Confidence | Risk | Effort | Soundness |
|--------|-----------|------|--------|-----------|
| ...    | High/Med/Low | High/Med/Low | S/M/L | ✅/⚠️/❌ |

## Recommended Approach
[Which option and why]

## Open Questions
[What must be answered before implementation]

## Related ADRs
[Links to relevant architectural decisions]
```

## ADR (Architectural Decision Record)

### Structure
```markdown
# ADR-[number]: [Title]

## Status
proposed | accepted | deprecated | superseded by ADR-[N]

## Context
[What problem prompted this decision]

## Decision
[What was decided]

## Consequences
[Trade-offs, implications, what becomes easier/harder]
```

### ADR Rules
- **NEVER edit** an existing ADR — it is an immutable record
- To change a decision: create a new ADR that supersedes the old one
- New engineers read ADRs FIRST — they replace verbal onboarding
- All agents MUST check `adr/*.md` before proposing architectural changes
- If an ADR conflicts with a proposed implementation → surface the conflict, don't ignore it

## When to Create Each Document

| Trigger | Create |
|---------|--------|
| Starting a new feature | Research doc |
| Making an architectural decision | ADR |
| Repeated verbal explanations of a decision | ADR (encode it once) |
| LLM reading too many files to understand the codebase | Research doc |
| New engineer joining the team | Point them to `adr/` first |
| Implementation plan growing beyond 1 page | Split into sub-plans |

## Anti-Patterns
- ❌ Jumping from ticket → code with no research doc
- ❌ Editing ADRs to update decisions (create a superseding one)
- ❌ Keeping implementation plans after execution (they are ephemeral)
- ❌ Mixing architectural docs with implementation plans (different lifespans)
- ❌ Skipping ADR for "small" decisions (small decisions become big regrets)