@nurix/etna 0.1.3 → 0.2.1

package/data/harnesses/code/scripts/build-ownership-index.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# scripts/build-ownership-index.sh - Generate docs/OWNERSHIP_INDEX.md from feature doc frontmatter
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+OUTPUT="$REPO_ROOT/docs/OWNERSHIP_INDEX.md"
+FEATURES_DIR="$REPO_ROOT/docs/features"
+TMP_OWNS=$(mktemp)
+TMP_DEPS=$(mktemp)
+TMP_DIRS=$(mktemp)
+trap 'rm -f "$TMP_OWNS" "$TMP_DEPS" "$TMP_DIRS"' EXIT
+
+# Extract YAML frontmatter list field values from a markdown file
+extract_field() {
+    local file="$1" field="$2"
+    awk -v field="$field" '
+        /^---$/ { fm++; next }
+        fm == 1 && $0 ~ "^"field":" {
+            in_field = 1
+            sub("^"field":[ ]*", "")
+            if ($0 != "" && $0 !~ /^\[/) { print $0; in_field = 0 }
+            next
+        }
+        fm == 1 && in_field && /^  +- / {
+            sub("^  +- ", "")
+            gsub(/^[ \t]+|[ \t]+$/, "")
+            print
+            next
+        }
+        fm == 1 && in_field && /^[a-z]/ { in_field = 0 }
+        fm == 1 && in_field && /^---$/ { in_field = 0 }
+        fm >= 2 { exit }
+    ' "$file"
+}
+
+# Collect ownership and dependency data from all feature docs
+find "$FEATURES_DIR" -name "*.md" ! -name "README.md" -print0 | sort -z | while IFS= read -r -d '' file; do
+    rel_path="${file#$REPO_ROOT/}"
+
+    extract_field "$file" "owns" | while IFS= read -r pattern; do
+        [ -z "$pattern" ] && continue
+        printf '%s\t%s\n' "$pattern" "$rel_path" >> "$TMP_OWNS"
+    done
+
+    deps=$(extract_field "$file" "depends_on" | tr '\n' ', ' | sed 's/,$//' | sed 's/, $//')
+    if [ -n "$deps" ]; then
+        printf '%s\t%s\n' "$rel_path" "$deps" >> "$TMP_DEPS"
+    fi
+done
+
+# Collect owned directory prefixes for unowned path detection
+sed 's|/\*\*$||; s|/\*$||; s|/[^/]*$||' "$TMP_OWNS" | awk -F'\t' '{ print $1 }' | sort -u > "$TMP_DIRS"
+
+# Find unowned src/ directories
+unowned=""
+if [ -d "$REPO_ROOT/src" ]; then
+    for dir in "$REPO_ROOT"/src/*/; do
+        [ -d "$dir" ] || continue
+        rel_dir="${dir#$REPO_ROOT/}"
+        rel_dir="${rel_dir%/}"
+        is_owned=0
+        while IFS= read -r owned; do
+            case "$rel_dir" in
+                "$owned"*) is_owned=1; break ;;
+            esac
+            case "$owned" in
+                "$rel_dir"*) is_owned=1; break ;;
+            esac
+        done < "$TMP_DIRS"
+        if [ "$is_owned" -eq 0 ]; then
+            unowned="${unowned}- \`${rel_dir}\`
+"
+        fi
+    done
+fi
+
+# Generate output
+cat > "$OUTPUT" << 'HEADER'
+# Ownership Index
+
+> **Generated file** — do not edit manually.
+> Regenerate with: `bash scripts/build-ownership-index.sh`
+
+Machine-readable lookup table generated from feature doc frontmatter.
+
+---
+
+## By Code Path
+
+| Code Path | Owning Doc |
+|---|---|
+HEADER
+
+sort "$TMP_OWNS" | while IFS=$'\t' read -r pattern doc; do
+    echo "| \`$pattern\` | \`$doc\` |" >> "$OUTPUT"
+done
+
+cat >> "$OUTPUT" << 'SECTION'
+
+---
+
+## Unowned Paths
+
+Top-level `src/` directories with no owning feature doc:
+
+SECTION
+
+if [ -z "$unowned" ]; then
+    echo "_All top-level src/ directories have owners._" >> "$OUTPUT"
+else
+    printf '%s' "$unowned" >> "$OUTPUT"
+fi
+
+cat >> "$OUTPUT" << 'SECTION'
+
+---
+
+## Dependency Graph
+
+Feature docs and their declared `depends_on` relationships:
+
+| Feature Doc | Depends On |
+|---|---|
+SECTION
+
+if [ -s "$TMP_DEPS" ]; then
+    sort "$TMP_DEPS" | while IFS=$'\t' read -r doc deps; do
+        echo "| \`$doc\` | $deps |" >> "$OUTPUT"
+    done
+fi
+
+echo "" >> "$OUTPUT"
+echo "---" >> "$OUTPUT"
+echo "" >> "$OUTPUT"
+echo "_Generated: $(date -u '+%Y-%m-%d %H:%M UTC')_" >> "$OUTPUT"
+
+echo "Generated $OUTPUT"

package/data/harnesses/code/scripts/check-doc-drift.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# scripts/check-doc-drift.sh - Detect potentially stale docs based on recent code changes
+
+set -euo pipefail
+
+DAYS="${1:-14}"
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+FEATURES_DIR="$REPO_ROOT/docs/features"
+TMP_OWNS=$(mktemp)
+TMP_STALE=$(mktemp)
+TMP_UNOWNED=$(mktemp)
+trap 'rm -f "$TMP_OWNS" "$TMP_STALE" "$TMP_UNOWNED"' EXIT
+
+echo "Checking for doc drift over the last $DAYS days..."
+echo ""
+
+# Extract owns patterns from a markdown file
+extract_owns() {
+    local file="$1"
+    awk '
+        /^---$/ { fm++; next }
+        fm == 1 && /^owns:/ { in_owns = 1; next }
+        fm == 1 && in_owns && /^  +- / {
+            sub("^  +- ", "")
+            gsub(/^[ \t]+|[ \t]+$/, "")
+            print
+            next
+        }
+        fm == 1 && in_owns && /^[a-z]/ { exit }
+        fm >= 2 { exit }
+    ' "$file"
+}
+
+# Get recently changed files
+changed_files=$(cd "$REPO_ROOT" && git log --since="$DAYS days ago" --name-only --pretty=format:"" | sort -u | grep -v '^$' || true)
+
+if [ -z "$changed_files" ]; then
+    echo "No files changed in the last $DAYS days."
+    exit 0
+fi
+
+changed_count=$(echo "$changed_files" | wc -l | tr -d ' ')
+echo "Found $changed_count changed files in the last $DAYS days."
+echo ""
+
+# Build ownership map: pattern\tdoc
+find "$FEATURES_DIR" -name "*.md" ! -name "README.md" -print0 | sort -z | while IFS= read -r -d '' file; do
+    rel_path="${file#$REPO_ROOT/}"
+    extract_owns "$file" | while IFS= read -r pattern; do
+        [ -z "$pattern" ] && continue
+        printf '%s\t%s\n' "$pattern" "$rel_path" >> "$TMP_OWNS"
+    done
+done
+
+# Check each changed file against ownership
+echo "$changed_files" | while IFS= read -r changed_file; do
+    [ -z "$changed_file" ] && continue
+    # Skip non-source files
+    case "$changed_file" in
+        docs/*|.claude/*|.github/*|node_modules/*|package*.json|*.lock*|*.config*) continue ;;
+    esac
+
+    found_owner=0
+    while IFS=$'\t' read -r pattern doc; do
+        prefix="${pattern%%\*\**}"
+        prefix="${prefix%%\**}"
+        case "$changed_file" in
+            ${prefix}*)
+                found_owner=1
+                # Check if the doc was also modified recently
+                if ! echo "$changed_files" | grep -q "^${doc}$"; then
+                    printf '%s\t%s\n' "$doc" "$changed_file" >> "$TMP_STALE"
+                fi
+                break
+                ;;
+        esac
+    done < "$TMP_OWNS"
+
+    if [ "$found_owner" -eq 0 ]; then
+        case "$changed_file" in
+            src/*|app/*|packages/*) echo "$changed_file" >> "$TMP_UNOWNED" ;;
+        esac
+    fi
+done
+
+# Report stale docs
+if [ -s "$TMP_STALE" ]; then
+    echo "## Potentially Stale Docs"
+    echo ""
+    echo "These docs own code that changed recently, but the docs themselves were not updated:"
+    echo ""
+    current_doc=""
+    sort "$TMP_STALE" | while IFS=$'\t' read -r doc file; do
+        if [ "$doc" != "$current_doc" ]; then
+            [ -n "$current_doc" ] && echo ""
+            echo "**$doc**"
+            current_doc="$doc"
+        fi
+        echo "  - $file"
+    done
+    echo ""
+else
+    echo "## No Stale Docs Detected"
+    echo ""
+    echo "All docs whose owned code changed were also updated."
+fi
+
+echo ""
+
+# Report unowned files
+if [ -s "$TMP_UNOWNED" ]; then
+    unowned_count=$(wc -l < "$TMP_UNOWNED" | tr -d ' ')
+    echo "## Unowned Changed Files ($unowned_count)"
+    echo ""
+    echo "These changed source files have no owning feature doc:"
+    echo ""
+    sort -u "$TMP_UNOWNED" | head -30 | while IFS= read -r file; do
+        echo "- $file"
+    done
+    if [ "$unowned_count" -gt 30 ]; then
+        echo "- ... and $((unowned_count - 30)) more"
+    fi
+else
+    echo "## No Unowned Changed Files"
+fi

package/data/harnesses/code/skills/documentation/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: documentation
+description: Create and maintain technical documentation. Use when the user asks to (1) baseline, audit, or reorganize docs — enforces an opinionated 6-folder structure (architecture, features, operations, history, memory, tests) with ownership frontmatter and scaffold files, (2) document a feature or module, (3) create or update a changelog entry, (4) document data flows or Redux state, (5) add to protected files, (6) create or update guardrails (cascading failure boundaries), (7) record an architecture decision (ADR), (8) create or update the project root README, (9) create or update a plan, or (10) co-author any technical doc. Triggers on "document this", "create docs", "update changelog", "baseline docs", "audit docs", "add to protected files", "guardrails", "ADR", "architecture decision", "root README", "plan".
+---
+
+# Technical Documentation Skill
+
+Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments. Breaking changes belong in changelogs only, not module docs.
+
+**No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (routing, ownership index, memory files, frontmatter `depends_on`, cross-doc links) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
+
+---
+
+## Decision Tree
+
+```
+User request
+    │
+    ├─ "Baseline/audit docs" ──────────▶ Baseline Audit (below)
+    │
+    ├─ "Document feature/module" ──────▶ Module Template
+    │
+    ├─ "Create/update changelog" ──────▶ Changelog Template
+    │
+    ├─ "Document data flow" ───────────▶ Module Template (Architecture section)
+    │
+    ├─ "Document Redux/state" ─────────▶ Module Template (State section)
+    │
+    ├─ "Add to protected files" ───────▶ Protected Files Template
+    │
+    ├─ "Create/update guardrails" ─────▶ Guardrails Template
+    │
+    ├─ "Record architecture decision" ─▶ ADR Template
+    │
+    ├─ "Create/update root README" ────▶ Project Root README Template
+    │
+    ├─ "Create/update plan" ───────────▶ Plan Template
+    │
+    ├─ "Update existing doc" ──────────▶ Preserve existing structure
+    │
+    └─ No template matches ────────────▶ Co-Authoring Workflow (below)
+```
+
+---
+
+## Baseline Audit
+
+When asked to "baseline", "audit", or "review" docs, enforce the canonical 6-folder documentation structure. This is an opinionated reorganization — the target structure is non-negotiable.
+
+### Target Structure
+
+```
+docs/
+├── README.md              # Documentation root — quick links table, section index
+├── structure.md           # Authority map, folder rules, health log
+├── CODEBASE_MAP.md        # Auto-generated directory map (optional)
+├── faq.md                 # Common issues (optional)
+├── architecture/          # System-wide decisions, patterns, technical references
+│   ├── adr/               # Architecture Decision Records (numbered, immutable)
+│   └── core/              # Core module internals (auth, state, routing)
+├── features/              # Living feature specs with ownership frontmatter
+│   └── {feature}/         # Subfolder for deep features (e.g., editor/)
+├── operations/            # Setup, development, deployment, CI/CD
+│   └── guardrails.md      # Cascading failure boundaries (cross-module contracts)
+├── history/               # Frozen/append-only records
+│   ├── CHANGELOG.md       # Master changelog index
+│   ├── changelog/         # Individual changelog entries
+│   ├── plans/             # Historical implementation plans (Status field required)
+│   └── backlog.md         # Tracked work items by priority (P0-P3)
+├── memory/                # Agent memory files
+└── tests/                 # Test plans and automation docs (optional)
+```
+
+### Workflow
+
+**Step 1: Inventory existing docs**
+
+Glob all markdown files in the repo. Categorize each file:
+
+| Category | Matches | Target |
+|----------|---------|--------|
+| Architecture | System design, patterns, config, API specs, tech decisions | `docs/architecture/` |
+| Features | How a feature works, user-facing behavior, data models | `docs/features/` |
+| Operations | Setup, dev workflow, deployment, CI/CD, runbooks | `docs/operations/` |
+| Plans | Implementation plans, proposals, RFCs | `docs/history/plans/` |
+| Changelogs | Change records, release notes | `docs/history/changelog/` |
+| Backlogs/Tasks | Work items, TODOs, tech debt | Merge into `docs/history/backlog.md` |
+| Stale/Deprecated | Self-marked deprecated, fully superseded, empty docs | Delete |
+| Root docs | `README.md`, `CLAUDE.md`, `AGENTS.md` | Stay in root |
+
+**Step 2: Detect duplicates and overlaps**
+
+For each topic, identify all files covering it. Keep the most complete version as canonical. Extract unique content from others before deleting.
+
+**Step 3: Present reorganization plan**
+
+Present a table to the user:
+
+```
+| File | Action | From | To | Reason |
+```
+
+Actions: `Move`, `Merge into {target}`, `Delete`, `Keep`, `Create`
+
+Ask: "Approve this plan? I'll execute all moves, merges, and deletions."
+
+**Step 4: Execute reorganization**
+
+After approval:
+
+1. Create the full folder structure:
+   - `docs/architecture/`
+   - `docs/features/`
+   - `docs/operations/`
+   - `docs/history/plans/`
+   - `docs/history/changelog/`
+   - `docs/memory/`
+   - `docs/tests/` (if test docs exist)
+2. Move files per the plan
+3. Merge content where specified (extract unique content, append to target)
+4. Delete stale/superseded files
+5. Add `Status: Complete | In Progress | Draft | Abandoned` to all plan files
+6. Add YAML frontmatter to feature docs (see Frontmatter Derivation below)
+7. Merge scattered backlog/task files into `docs/history/backlog.md`
+8. Scaffold standard files if missing:
+   - `docs/README.md` — from template (see `references/templates.md`)
+   - `docs/structure.md` — from template (see `references/templates.md`)
+   - `docs/operations/guardrails.md` — cascading failure boundaries (see `references/templates.md` for what to include/exclude)
+   - `docs/history/CHANGELOG.md` — master changelog index (header + table linking to entries)
+   - `docs/history/backlog.md` — work items by priority (P0-P3 sections, empty if nothing to merge)
+   - `docs/memory/index.md` — agent memory index (empty scaffold with section headers)
+   - `docs/memory/main.md` — main agent project memory (empty header + date marker)
+   - `docs/OWNERSHIP_INDEX.md` — generated table of feature doc ownership. Build it now from the frontmatter you derived in Step 6 (same shape the maintenance agent regenerates each run — see `references/templates.md`)
+   - `README.md` (repo root) — from §11 in `references/templates.md`, filled with concrete details from the repo (real package manager from the lockfile, real scripts, real layout). **Never overwrite an existing root README** — if one is present, leave it untouched.
+9. Fix all internal links broken by moves
+10. Record baseline in `docs/memory/index.md` with today's date (see template)
+
+**Step 5: Verify**
+
+1. Confirm all standard files exist: `docs/README.md`, `docs/structure.md`, `docs/operations/guardrails.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, `docs/OWNERSHIP_INDEX.md`, `README.md` (repo root — must exist; either pre-existing untouched or freshly scaffolded)
+2. Confirm no dead links in `docs/README.md`
+3. Confirm every plan file has a `Status:` field
+4. Confirm feature docs have ownership frontmatter
+5. Confirm `docs/OWNERSHIP_INDEX.md` rows match the frontmatter on disk (no orphans, no missing entries)
+6. Confirm no docs remain outside the 6-folder structure (except `README.md`, `structure.md`, `CODEBASE_MAP.md`, `faq.md`)
+7. Confirm duplicates are eliminated — each topic has one canonical source
+
+### Rules
+
+- The 6-folder structure is mandatory. No `docs/guides/`, `docs/core/`, `docs/editor/`, `docs/pt/`, or any other top-level folder
+- Guides about how-to-run → `operations/`. Guides about a feature → `features/`
+- Core module docs → `docs/architecture/core/`. Editor module docs → `docs/features/editor/`
+- Only `CLAUDE.md`, `AGENTS.md`, and `README.md` are allowed in the repository root (not inside `docs/`)
+- Root-level `README.md` is for humans. `docs/README.md` is the agent/doc entry point
+- One canonical source per topic — link, don't copy
+- **No redirect docs** — when moving a file, delete the original and fix all references. Never leave a "Moved to X" stub.
+- For 10+ files, use parallel sub-agents (5-8 files each)
+
+### Naming & Lifecycle
+
+- Features: `kebab-case.md` — living reference, status `Active`
+- Plans: `YYYY-MM-DD-kebab-case.md` — frozen after `Complete` or `Abandoned`
+- Changelogs: `YYYY-MM-DD-kebab-case.md` — append-only
+- Memory: `{agent-name}.md` — agent-maintained
+
+---
+
+## Frontmatter Derivation
+
+When creating or updating a feature doc in `docs/features/`, generate `owns`, `touches`, `depends_on` frontmatter from the source code the doc describes.
+
+### When to run
+
+- **Baseline audit Step 6** — for every feature doc missing frontmatter
+- **New feature doc** — when creating a doc via the Module Documentation template
+- **Doc update** — when updating an existing feature doc and the frontmatter is missing or the documented scope changed
+
+### How to derive values
+
+**1. Identify `owns` patterns**
+
+Read the feature doc's content. Extract every source file path referenced in the doc (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping other features.
+
+| Doc references | `owns` pattern |
+|---|---|
+| Multiple files under one directory | `src/feature/**` |
+| Specific files in a shared directory | List each file explicitly |
+| A single entry-point file | The exact file path |
+
+Verify patterns match real files — glob each pattern against the codebase. Remove any that match nothing.
+
+**2. Identify `touches` patterns**
+
+From the same source files the doc describes, find imports and calls to code outside the `owns` scope. These are files the feature uses but doesn't own.
+
+Common `touches` candidates:
+- Shared Redux slices the feature reads/writes
+- Utility functions from other modules
+- Shared hooks the feature calls
+- API route files the feature's frontend calls
+
+Keep `touches` to direct dependencies only — not transitive ones.
+
+**3. Identify `depends_on` docs**
+
+Check for explicit cross-references to other docs in `docs/features/` or `docs/architecture/`. Also check if the feature's `touches` paths are `owns`-ed by another feature doc — that doc is a dependency.
+
+### Rules
+
+- Every feature doc must have all three fields, even if empty (`depends_on: []`)
+- Use glob patterns for directories, explicit paths for individual files
+- Don't list paths that don't exist in the codebase
+- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec gets its own frontmatter — don't duplicate ownership across siblings
+- For baseline audits with 10+ files needing frontmatter, use parallel sub-agents to read and analyze the source files
+
+---
+
+## Co-Authoring Workflow
+
+For docs that don't match templates:
+
+**Stage 1: Context Gathering**
+- Ask: Audience? Purpose? Existing format?
+- Have user dump all context, then ask 5-10 clarifying questions
+
+**Stage 2: Structure & Draft**
+- Propose section structure, draft section by section
+- User indicates changes (don't edit directly — learn their style)
+
+---
+
+## Resources
+
+| File | Use For |
+|------|---------|
+| `references/templates.md` | docs/README.md, structure.md, frontmatter, scaffolds (CHANGELOG, backlog, memory, OWNERSHIP_INDEX), guardrails, feature, changelog, plan, protected files, ADR, project root README templates |
+| `references/style-guide.md` | Writing rules, formatting conventions |
+| `references/examples.md` | Good vs bad documentation examples |

package/data/harnesses/code/skills/documentation/references/examples.md

@@ -0,0 +1,193 @@
+# Documentation Examples
+
+Good vs bad examples showing the key differences.
+
+---
+
+## Example 1: Function Documentation
+
+### ❌ Bad: Full Implementation
+
+```markdown
+### mergeData
+
+function mergeData(server, local, changes) {
+const result = {};
+const serverMap = new Map(server.map((i) => [i.id, i]));
+// ... 30 more lines
+return result;
+}
+```
+
+**Problems:** Will become obsolete, focuses on HOW not WHAT.
+
+### ✅ Good: Contract Only
+
+```markdown
+### `mergeData(serverData, localData, changes)`
+
+**Goal:** Merge server data with local changes
+**Input:**
+
+-   `serverData` (array) - Fresh from API
+-   `localData` (array) - Current state
+-   `changes` (object) - `{ added, updated, removed }`
+    **Output:** `{ merged: array, conflicts: array }`
+
+**Merge Rules:**
+
+-   Server wins for conflicts
+-   Local additions preserved
+-   Local removals marked as intent
+```
+
+---
+
+## Example 2: State Documentation
+
+### ❌ Bad: State Everywhere
+
+```markdown
+## Component State
+
+const [items, setItems] = useState([]);
+
+## Hook State
+
+{ data: items, isLoading: loading, error: null }
+
+## Redux State
+
+{ items: [], loading: false, error: null }
+```
+
+**Problems:** Documents transient state, repeats shapes.
+
+### ✅ Good: Persistence Points Only
+
+```markdown
+## State
+
+**Frontend (at persistence):**
+{
+"data": [],
+"changes": { "added": [], "updated": [], "removed": [] }
+// "cache": {} // UNUSED: Deprecated
+}
+
+**Storage:** localStorage `app_state`
+
+**Backend:**
+model Item {
+id String @id
+data Json
+}
+```
+
+---
+
+## Example 3: Changelog
+
+### ❌ Bad: Vague
+
+```markdown
+# 2025-01-05 - Updates
+
+## Changes
+
+-   Updated editor
+-   Fixed bugs
+-   Improved performance
+
+## Files
+
+-   Various files in src/
+```
+
+### ✅ Good: Function-Level Detail
+
+```markdown
+# 2025-01-05 - Version-Based Merge
+
+## Summary
+
+Replaced change-tracking merge with version-based conflict resolution.
+
+## Changes
+
+### Added
+
+-   `mergeAndDerive(server, local, versionsMatch, type)` in `src/utils/merge.js`
+    -   Purpose: Single-pass merge with change detection
+    -   Returns: `{ merged, changes }`
+
+### Modified
+
+-   `useDataSync()` in `src/hooks/useDataSync.js`
+    -   Changed: Now compares versions before merge
+
+### Removed
+
+-   `deriveChanges()` from `src/utils/derive.js`
+    -   Replaced by: Logic in `mergeAndDerive()`
+
+## Breaking Changes
+
+⚠️ **Merge behavior changed**
+
+-   Old: Local changes always preserved
+-   New: Local preserved only if versions match
+
+## Files Changed
+
+-   `src/hooks/useDataSync.js`
+-   `src/utils/merge.js`
+-   `src/utils/derive.js` (deleted)
+```
+
+---
+
+## Example 4: Data Flow
+
+### ❌ Bad: Prose Description
+
+```markdown
+When the page loads, the useAppInit hook calls the syncData function.
+This function first fetches data from the server using the API. Then
+it gets the local data from Redux. After that, it compares versions...
+```
+
+### ✅ Good: Diagram + Key Points
+
+```markdown
+## Data Flow
+
+┌─────────────────────────────────────────┐
+│ DATA SYNC │
+├─────────────────────────────────────────┤
+│ │
+│ ┌──────┐ ┌──────┐ ┌──────┐ │
+│ │Server│────▶│Merge │────▶│Redux │ │
+│ │ API │ │ │ │Store │ │
+│ └──────┘ └──────┘ └──────┘ │
+│ │ │
+│ ▼ │
+│ Version Check │
+│ │
+└─────────────────────────────────────────┘
+
+**Trigger:** `useAppInit()` on page load
+**Version Rule:** Match → local wins, Mismatch → server wins
+```
+
+---
+
+## Quick Comparison
+
+| Aspect     | Bad                  | Good                        |
+| ---------- | -------------------- | --------------------------- |
+| Code       | Full implementations | Signatures + contracts      |
+| State      | Every occurrence     | Persistence points only     |
+| Flows      | Prose paragraphs     | ASCII diagrams              |
+| Changelogs | "Updated X"          | Function names + migrations |
+| Length     | 100+ lines           | 20-40 lines                 |