document

Document

Comprehensive documentation that shakes the tree to understand everything.

This skill generates in-depth documentation for a file or directory, focusing on:

• Human readability while covering ALL surface area
• Linking to tests as working examples
• Refining tests to look more real-world if needed
• Integration with the deciduous decision graph

---

Step 1: Create Documentation Goal Node

Before documenting, log what you're about to do:

deciduous add goal "Document $ARGUMENTS" -c 90 --prompt-stdin << 'EOF'
[User's verbatim documentation request]
EOF

Store the goal ID for linking later.

---

Step 2: Understand the Target

For a File

1. Read the file completely

   • Understand every function, class, type, and export
   • Note all imports and dependencies
   • Identify the file's role in the larger system

2. Find tests for this file

   • Look for test files with similar names
   • Search for imports/references in test directories
   • These will become working examples in the docs

3. Trace callers/callees

   • Who calls this file?
   • What does this file call?
   • Map the dependency graph

For a Directory

1. Map the structure

   • List all files and their purposes
   • Identify the public API (index/mod files)
   • Find the entry point

2. Understand relationships

   • How do files in this directory interact?
   • What's the data flow?

3. Find related tests

   • Test directories that cover this code
   • Integration tests that exercise the whole module

---

Step 3: Document Each Component

For each file/component, document:

3.1 Purpose

• One sentence: what does this do?
• Why does it exist? (The "why" is more important than the "what")

3.2 API Surface

For every public function/method/class:

### `function_name(param1: Type, param2: Type) -> ReturnType`

**Purpose:** What this does and why you'd call it.

**Parameters:**
- `param1` - Description and valid values
- `param2` - Description and valid values

**Returns:** What the return value means

**Throws/Errors:** What can go wrong

**Example:**
```code
// From: tests/example_test.rs:42
let result = function_name("input", 42);
assert_eq!(result, expected);

Related: Links to related functions