---
name: research-chapter
description: Research how reference implementations handle a chapter's topic
---

# Research Chapter

You are researching nostr library implementations to prepare for writing a chapter of a
literate programming book. The chapter name is provided as an argument: `$ARGUMENTS`.

## Step 1: Gather Topic Context

Before doing any research, ask the user to provide a brief summary of what this chapter
should cover. What concepts, data structures, protocols, or functionality should the
research focus on? Wait for their response before proceeding.

## Step 2: Research References

Once you have the topic summary, research the references in `./ref/` in parallel.

### Philosophy Reference

Spawn a sub-agent to read `ref/building-nostr` for content relevant to the chapter topic.
This is not code — it's high-level ideas about what nostr is and how to work with it.
Extract any philosophical framing, design principles, or conceptual guidance that should
inform the chapter's narrative and approach.

### Code References

Spawn **one sub-agent per code reference implementation** to analyze them in parallel.
Each sub-agent should:

1. Search the reference implementation for code relevant to the chapter topic
2. Analyze in depth:
   - What data structures and constructs are used?
   - What programming style or patterns are employed?
   - What are the dependencies (both internal and external)?
   - Is the implementation coupled to other parts of the library, or self-contained?
   - Are there any notable design decisions, trade-offs, or limitations?
3. Return a detailed summary focusing **only on functionality relevant to the chapter topic**
   — ignore unrelated parts of the library

The six code reference implementations to analyze:
- `ref/applesauce` (TypeScript — noStrudel ecosystem)
- `ref/ndk` (TypeScript — Nostr Development Kit)
- `ref/nostr-gadgets` (TypeScript — high-level utilities, JSR)
- `ref/nostr-tools` (TypeScript — low-level tools, minimal deps)
- `ref/rust-nostr` (Rust — full implementation, multiple crates)
- `ref/welshman` (TypeScript — extracted from Coracle client)

## Step 3: Write Research File

Compile all sub-agent results into a single research document and write it to:
`./book/research/$ARGUMENTS.md`

The research file should have this structure:

```markdown
# Research: <Chapter Name>

## Topic Summary

<The topic summary provided by the user in Step 1>

## Philosophy

<Relevant ideas, principles, and framing from ref/building-nostr>

## Reference Implementation Analysis

### applesauce
<detailed findings>

### ndk
<detailed findings>

### nostr-gadgets
<detailed findings>

### nostr-tools
<detailed findings>

### rust-nostr
<detailed findings>

### welshman
<detailed findings>

## Common Patterns

<Cross-cutting observations: what approaches are shared, where do implementations
diverge, what seems to work well>

## Considerations for Our Implementation

<Notes on dependencies, API design choices, and anything relevant to writing a Rust
implementation in a literate programming style>
```

After writing the file, tell the user the research is complete and they can proceed with
`/plan-chapter $ARGUMENTS`.