coracle-rust/.agents/skills/research-chapter/SKILL.md

name, description

name	description
research-chapter	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:

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