Adr

---
description: Research architectural decisions and write ADRs with evidence
argument-hint: "[topic] — e.g. \"Prisma vs Drizzle\", or [slug] [phase-num] for plan-scoped"
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - AskUserQuestion
  - Task
  - WebSearch
  - WebFetch
  - Bash(ls:*)
  - Bash(mkdir:*)
model: inherit
context: inherit
hooks: {}
user-invocable: true
---

# Orc ADR

Research phase before implementation. Runs 4 parallel agents to find best practices, KOLs, and production code.

<progress>
- [ ] Step 1: Parse input and determine mode
- [ ] Step 2: Extract or formulate research questions
- [ ] Step 2b: Direction signoff (user approves questions)
- [ ] Step 3: Launch 4 parallel research agents
- [ ] Step 4: Synthesize findings into ADR(s)
- [ ] Step 4b: User review gate (approve/revise/skip each ADR)
- [ ] Step 5: Write approved ADRs and return paths
</progress>

<purpose>
Ground implementation decisions in real-world evidence. Find how production systems solve similar problems, who the key experts are, and what patterns work.
</purpose>

<constraints>
**Your role:**
- Formulate research questions from the topic or phase PLAN.md
- Get user signoff on research direction before launching agents
- Launch parallel research agents with focused queries
- Synthesize findings into actionable ADRs
- Get user approval before writing each ADR
- Return ADR paths for implementation reference
</constraints>

<antipatterns>
**Not your role:**
- Implementing code (that's orc-swarm)
- Making final decisions (ADRs are proposals for user review)
- Deep diving on tangents (stay focused on phase scope)

**Avoid:**
- Generic searches ("best practices TypeScript")
- Ignoring contradictory findings
- Creating ADRs without evidence
- Launching more than 4 agents (context limits)
</antipatterns>

## Pattern

```
orc-adr (standalone skill, inherit)
    │
    ├── [parallel] Web Search Agent (general-purpose)
    ├── [parallel] Twitter/X Agent (general-purpose)
    ├── [parallel] GitHub Agent (general-purpose)
    └── [parallel] Docs Agent (general-purpose)
    │
    └── Synthesize → ADR(s)
```

## Input

**If `$ARGUMENTS` provided:** Use as `$TOPIC` directly. If the topic looks like it references a plan phase (mentions a slug that exists in `.claude/plans/`), also load PLAN.md and STATE.md for richer context. Don't enforce a format — just work with what the user gives you.

**If not provided:** AskUserQuestion: "What architectural decision should I research?"

## Process

### Step 1: Parse Input and Load Context

Try to load useful context without being strict about what must exist:

1. **Check for plan context:** If `.claude/plans/` exists and `$TOPIC` references a recognizable slug/phase, read PLAN.md and STATE.md for additional context
2. **Check for existing ADRs:** `ls docs/adr/` to check for existing ADRs on the same topic (dedup)
3. **Topic-only is fine:** If none of the above applies, the topic string alone is enough to research

Extract (from whatever is available):
- Key technical decisions needed
- Technologies involved
- Phase name and goal (if plan context loaded)

### Step 2: Extract or Formulate Research Questions

From whatever context is available (PLAN.md content, or just the topic string), identify 2-4 research questions. Look for:
- Architecture decisions (how to structure X?)
- Library choices (which library for Y?)
- Pattern selections (what pattern for Z?)
- Integration approaches (how to connect A and B?)

**Format questions as:**
```
Q1: How do production systems handle [specific problem]?
Q2: What's the recommended approach for [technical challenge]?
Q3: Who are the key experts on [topic] and what do they recommend?
Q4: What are real examples of [feature] in open source?
```

### Step 2b: Direction Signoff

AskUserQuestion presenting the extracted questions and agent roster:

```
I've formulated these research questions for "$TOPIC":

$QUESTIONS

I'll research these with 4 parallel agents:
1. Web Search — articles, blogs, tutorials
2. Twitter/X — KOLs, trending opinions
3. GitHub — production code examples
4. Official Docs — specs, guides, constraints

Approve or Revise?
```

- **Approve** → proceed to Step 3
- **Revise** → user adjusts questions → re-present until approved

### Step 3: Launch Parallel Research Agents

Launch 4 Task agents in parallel, each with a specific research focus:

**Agent 1: Web Search (general articles, blogs, tutorials)**
```
<Task subagent_type="general-purpose" description="Web research: [topic]">
Your topic: $TOPIC
Your research questions (from Step 2b):
$QUESTIONS

Search the web for best practices on these questions.
Focus on:
- Recent articles (2024-2025)
- Technical blog posts from respected sources
- Conference talks or tutorials

Use WebSearch with queries like:
- "[topic] best practices 2025"
- "[technology] production architecture"
- "[problem] real world solution"

Return:
- 3-5 key insights with sources
- Any consensus or controversy
- Recommended approaches with rationale
</Task>
```

**Agent 2: Twitter/X (KOLs, trending opinions)**
```
<Task subagent_type="general-purpose" description="Twitter research: [topic]">
Your topic: $TOPIC
Your research questions (from Step 2b):
$QUESTIONS

Search Twitter/X for key opinion leaders on this topic.
Focus on:
- Influential developers who work on [technology]
- Recent discussions about [problem]
- Hot takes and contrarian views

Use WebSearch with queries like:
- "site:twitter.com [expert name] [topic]"
- "site:x.com [technology] best practice"
- "[KOL name] opinion [topic]"

Return:
- Key experts and their positions
- Trending approaches or debates
- Any warnings or anti-patterns mentioned
</Task>
```

**Agent 3: GitHub (production code examples)**
```
<Task subagent_type="general-purpose" description="GitHub research: [topic]">
Your topic: $TOPIC
Your research questions (from Step 2b):
$QUESTIONS

Search GitHub for production implementations related to these questions.
Focus on:
- Popular repos (>100 stars) using similar patterns
- How real codebases structure [component]
- Common libraries and their usage patterns

Use WebSearch with queries like:
- "site:github.com [technology] [pattern]"
- "[library] example implementation"
- "[project type] open source [feature]"

Return:
- 2-3 exemplary repos with links
- Code patterns observed
- Libraries/dependencies commonly used
- File structure patterns
</Task>
```

**Agent 4: Official Docs & Specs**
```
<Task subagent_type="general-purpose" description="Docs research: [topic]">
Your topic: $TOPIC
Your research questions (from Step 2b):
$QUESTIONS

Search official documentation for the technologies involved.
Focus on:
- Official recommended patterns
- Migration guides or best practices sections
- Known limitations or gotchas

Use WebFetch for official docs:
- Framework documentation
- Library API references
- Official guides/tutorials

Return:
- Official recommendations
- Documented patterns
- Warnings or constraints
- Version-specific considerations
</Task>
```

### Step 4: Synthesize into ADR(s)

Wait for all 4 agents to complete. Synthesize findings into 1-3 ADRs.

**ADR structure:** (use [templates/ADR.md](templates/ADR.md))

```markdown
# ADR-XXX: [Decision Title]

## Status
Proposed

## Context
[Problem we're solving, derived from PLAN.md]

## Research Findings

### Web Sources
- [insight 1] — [source]
- [insight 2] — [source]

### Expert Opinions (Twitter/X)
- [@expert1]: "[quote or position]"
- [@expert2]: "[contrasting view if any]"

### Production Examples (GitHub)
- [repo1](link): [how they solved it]
- [repo2](link): [alternative approach]

### Official Guidance
- [recommendation from docs]
- [constraints or warnings]

## Decision
[Recommended approach based on evidence]

## Consequences

### Positive
- [benefit 1]
- [benefit 2]

### Negative
- [tradeoff 1]
- [tradeoff 2]

### Trade-offs
- [key tradeoff and why we accept it]

## References
- [link 1]
- [link 2]
```

**Naming convention (Dewey Decimal / MIT course style):**
- Directory: `docs/adr/` (run `mkdir -p docs/adr` on first use)
- Discover subject number: `ls docs/adr/` to find existing categories, or assign new one
  - Categories: `1`=infrastructure, `2`=data, `3`=auth, `4`=api, `5`=frontend, etc.
- Find next sequence: `ls docs/adr/ADR{subject}.*` to find next NNN
- Format: `docs/adr/ADR{subject}.{NNN}-{kebab-case-title}.md`
- Examples: `ADR3.001-session-management.md`, `ADR5.002-component-library.md`

### Step 4b: User Review Gate

For each synthesized ADR, AskUserQuestion presenting the full ADR content:

```
Here's the proposed ADR:

$ADR_CONTENT

Write, Revise, or Skip?
```

- **Write** → approve this ADR for writing to disk
- **Revise** → ask what to change, apply edits, re-present until approved
- **Skip** → don't write this ADR, move to next

### Step 5: Write Approved ADRs and Return Paths

Only write ADRs approved ("Write") in Step 4b.

If all ADRs skipped:
```
RESEARCH COMPLETE — no ADRs written
Questions researched: $questions-count

Key findings:
- [finding 1]
- [finding 2]
- [finding 3]
```

Otherwise, report completion with **comma-separated paths (no spaces)**:

```
RESEARCH COMPLETE
Questions researched: $questions-count

ADRs: docs/adr/ADR{subject}.{NNN}-title.md,docs/adr/ADR{subject}.{NNN}-title.md

Key findings:
- [finding 1]
- [finding 2]
- [finding 3]

Ready for implementation.
```

**Critical:** The `ADRs:` line must be comma-separated with NO SPACES between paths. This allows orc-swarm to parse it as a single token.

## File Ownership

| File | Access | Purpose |
|------|--------|---------|
| PLAN.md | Read only (orc mode only) | Extract research questions when plan context available |
| STATE.md | Read only (orc mode only) | Understand codebase context when plan context available |
| docs/adr/ADR*.md | Write | Create new ADRs (only after user approval) |

## Research Query Templates

### For AI/LLM Integration
- "LLM agent architecture production 2025"
- "AI character simulation state management"
- "Claude API structured output patterns"

### For Web UI
- "real-time web updates websocket vs SSE 2025"
- "React canvas game rendering patterns"
- "speech bubble UI component design"

### For Backend
- "node.js tick loop game server patterns"
- "express real-time simulation architecture"
- "in-memory state management patterns"

## Completion Criteria

- [ ] Research questions formulated and user-approved (Step 2b)
- [ ] 4 parallel agents launched and completed
- [ ] Findings synthesized (no contradictions ignored)
- [ ] Each ADR presented for user review (Step 4b)
- [ ] Only approved ADRs written to disk
- [ ] ADR paths returned (or "no ADRs written" if all skipped)

## Skip Conditions

You may skip research if:
- PLAN.md explicitly says "no research needed"
- ADRs already exist covering the phase topic
- User passes `--skip-research` flag

In skip case, return:
```
RESEARCH SKIPPED
Reason: [reason]
Existing ADRs: [list if any]
```