PR Documentation

One of the most powerful uses of deciduous is generating PR documentation directly from your decision graph.

The Problem

Writing good PR descriptions is tedious. You have to:

• Summarize what changed
• Explain why those changes were made
• Mention what alternatives were considered
• Provide enough context for reviewers

If you've been logging decisions to the graph, this information already exists. Why write it again?

Generating a Writeup

The deciduous writeup command generates PR documentation from your graph:

$ deciduous writeup -t "Add Rate Limiting" --nodes 47-52
## Summary

- **Goal:** Add rate limiting to protect API endpoints from abuse
- **Approach chosen:** Redis-based sliding window rate limiter
- **Rationale:** Redis already in stack, need to scale across instances

### Decision Flow

1. **Goal #47:** Add rate limiting to API
   - Confidence: 90%
   - Prompt: "User asked: Add rate limiting to the API endpoints"

2. **Decision #48:** Choose rate limiting strategy
   - Confidence: 75%

3. **Options considered:**
   - **#49 Redis-based with sliding window** (chosen)
     - Rationale: Scales across instances, persistent
   - **#50 In-memory with token bucket** (rejected)
     - Rationale: Simpler, but single-instance only

4. **Action #51:** Implementing Redis rate limiter
   - Rationale for choice: Redis already in stack, needs horizontal scaling

5. **Outcome #52:** Rate limiting working, 429s returned correctly
   - Linked commit: abc123

## Test Plan

- [ ] Verify rate limits apply correctly
- [ ] Test 429 responses when limit exceeded
- [ ] Confirm limits reset after window expires

Adding Visualizations

Generate a graph visualization to include in the PR:

# Generate PNG with auto branch-specific filename
$ deciduous dot --auto --png --nodes 47-52
Generated docs/decision-graph-feature-rate-limiting.dot
Generated docs/decision-graph-feature-rate-limiting.png (via graphviz)

The --auto flag creates branch-specific filenames, preventing merge conflicts when multiple PRs have graphs.

The Full PR Workflow

# 1. Generate the visualization
$ deciduous dot --auto --png --nodes 47-52

# 2. Commit the graph files
$ git add docs/decision-graph-*.png docs/decision-graph-*.dot
$ git commit -m "docs: add decision graph for rate limiting"

# 3. Push
$ git push

# 4. Create PR with generated writeup
$ gh pr create --title "Add Rate Limiting" \
    --body "$(deciduous writeup --auto -t 'Add Rate Limiting' --nodes 47-52)"

Writeup Options

Real PR Examples

See deciduous PRs with decision graphs included:

• #11: Type Unification — 14 tracked decisions
• #3: Multi-User Graph Sync — jj-inspired patch model
• #9: TEA Architecture Refactor — Elm Architecture refactor

Updating Existing PRs

To update a PR body with new writeup content:

$ gh pr edit 123 --body "$(deciduous writeup --auto -t 'My PR' --nodes 47-52)"