---
name: write-chapter
description: Write a book chapter from its plan with tangled Rust code
---

# Write Chapter

You are writing a chapter of a literate programming book about nostr. The chapter name
is provided as an argument: `$ARGUMENTS`.

## Step 1: Read the Plan

Read the chapter plan at `./book/plan/$ARGUMENTS.md`. This contains the outline, API
design, code organization, dependencies, and narrative notes developed with the user.

If the plan file does not exist, tell the user to run `/plan-chapter $ARGUMENTS` first
and stop.

Also read:
- `./book/SUMMARY.md` to understand the book structure and where this chapter fits
- Any existing chapters referenced in the plan to ensure continuity
- The existing code in any crate `src/` directories that this chapter will extend (these
  are generated by tangle, but reading them shows the current state)

## Step 2: Write the Chapter

Create or update the chapter markdown file in `./book/`. Follow these conventions:

- **Voice**: Write as though documenting a library, not teaching a class. Do not refer
  to the book as a "teaching resource", "tutorial", "pedagogical", or similar — and
  don't justify design decisions on the grounds that the reader is learning. The prose
  should stand on its own merits as technical writing about the library.
- **Literate style**: The prose is the primary artifact. Code blocks are woven into the
  narrative, not dumped in bulk.
- **Code blocks** that should be tangled use the annotation format:
  ````
  ```rust {file=crate-name/src/path.rs}
  ```
  ````
- Multiple code blocks can target the same file — they are concatenated in document order.
- Code blocks without `{file=...}` are illustrative (examples, JSON, shell commands).
- Explain *why* before showing *what*. A reader should understand the motivation before
  seeing the implementation.
- Keep code blocks focused — one concept per block where possible.
- Ensure all `use` statements and module declarations are included in tangled blocks.
- **Tests are hand-written, not tangled, and do not appear in the chapter.** Do not put
  test code in chapter markdown, do not emit `{file=crate-name/tests/…}` blocks, and do
  not add a "Tests" section to the narrative. Tangle owns `src/` and overwrites it every
  build, so tests must live *outside* `src/` to survive. Integration tests go in
  `crate-name/tests/<topic>.rs` as normal, hand-edited Rust files alongside `src/`. Write
  or update the test file directly with the Edit or Write tool as part of the same task,
  and run `cargo test -p <crate>` alongside `just all` to verify.
- Update `./book/SUMMARY.md` if adding a new chapter.
- Update any `Cargo.toml` files if new dependencies are needed.

## Step 3: Validate

Run `just all` to verify that:
1. The tangle step extracts valid Rust source files
2. The Rust code compiles successfully
3. The mdBook build succeeds

If the build fails, read the error output, fix the issue in the chapter markdown (not
in generated `src/` files), and run `just all` again. Repeat until the build passes.

## Step 4: Report

Tell the user the chapter is written and building. Summarize:
- What sections were written
- What types/functions were implemented
- Any deviations from the plan and why
- Any open items or things to revisit