Workflow - Creating and Updating Notes

This document describes the correct workflow for creating and updating notes to avoid incomplete documents and broken links.

Plan the Structure First

Before writing any content for a new topic area, sketch the parent/child split. The natural instinct is to put everything in one note first and split it later. This is the megadoc trap — splitting a finished megadoc is harder than writing focused notes from the start, and the split rarely happens cleanly after the fact.

Ask: what are the distinct questions a reader might want to answer? Each answer is a note. A note that answers three different questions should be three notes. This matters for LLMs too: a focused 20-block note loaded on demand costs far less context window than a 100-block megadoc loaded because one fact in it was needed.

Creating Child Notes with Links

CORRECT ORDER: Create children first, then update parent

When you need to create multiple related notes:

1. Create all child notes first using notes load -d with complete content

2. THEN update the parent page to add links to the children

3. Verify all links resolve correctly

Why This Order?

• Avoids uploading incomplete parent documents with empty sections

• Child notes exist before being referenced

• Clear sequential workflow - no partial states

• Easier to verify completeness before linking

Example: Documenting a New Feature

Suppose you want to document a new feature with three aspects: design, implementation, and testing.

Step 1: Create child notes with full content

# Create ~/tmp/design.json with complete content
notes load -d project/feature-design ~/tmp/design.json

# Create ~/tmp/implementation.json with complete content
notes load -d project/feature-implementation ~/tmp/implementation.json

# Create ~/tmp/testing.json with complete content
notes load -d project/feature-testing ~/tmp/testing.json

Step 2: Read parent to preserve existing content

notes read project

Step 3: Update parent with links to children

# Create ~/tmp/project-updated.json
# Preserve all existing content and metadata
# Add new section with links to the three child notes
notes load -d project ~/tmp/project-updated.json

WRONG: Don't Upload Partial Documents

DO NOT do this:

❌ Upload parent with links to children that don't exist yet

❌ Upload parent with placeholder sections like "TODO: add content"

❌ Upload parent, then realize you need to add children, then update again

Why Not Hanging Links?

While JSONHTL permits links to non-existent documents, uploading a parent with hanging links creates confusion:

• Readers see broken links and think content is missing

• Harder to track what's complete vs incomplete

• Creates intermediate incomplete state

Updating Existing Notes

When modifying an existing note:

1. notes read <key> to get current content

2. Create updated JSON file preserving:

• All existing links to children

• Metadata: title, version (increment it), created, tags

• Add updated: YYYY-MM-DD field

3. notes load -d <key> /tmp/updated.json

4. Verify update with notes read <key>

Quick Reference

Creating linked notes:

1. Create all children (complete content)

2. Read parent

3. Update parent to link children

Updating existing note:

1. Read current version

2. Preserve metadata and links

3. Increment version, add updated date

4. Upload new version

See also: Avoiding Orphaned Notes

Temp File Convention

Always use ~/tmp/ (i.e. $HOME/tmp/) for scratch files, not /tmp/. This avoids permission issues on multi-user systems and keeps scratch files in a predictable personal location. Create the directory if needed: mkdir -p ~/tmp.