┌─────────────────────────────────────────────────────────────┐
│                      User Interface                         │
│  goto, bookmark, recent, back, goto list, goto benchmark   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Core Navigation                          │
│  goto-function.sh - Main routing and path resolution        │
└─────────────────────────────────────────────────────────────┘
                            │
          ┌─────────────────┼─────────────────┐
          ▼                 ▼                 ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
│  Cache System    │ │  Bookmarks   │ │  History         │
│  cache-index.sh  │ │  bookmark-   │ │  history-        │
│                  │ │  command.sh  │ │  tracking.sh     │
│  O(1) lookup     │ │              │ │                  │
│  Auto-refresh    │ │  Add/Remove  │ │  Track visits    │
└──────────────────┘ └──────────────┘ └──────────────────┘

goto.sh (loader)
  ├── history-tracking.sh (no dependencies)
  ├── back-command.sh (depends on: history-tracking.sh)
  ├── recent-command.sh (depends on: history-tracking.sh)
  ├── bookmark-command.sh (no dependencies)
  ├── cache-index.sh (no dependencies)
  ├── list-command.sh (depends on: bookmark-command.sh)
  ├── benchmark-command.sh (depends on: cache-index.sh)
  ├── benchmark-workspace.sh (no dependencies)
  └── goto-function.sh (depends on: all above)

Feature: [Name]
Problem: [User pain point]
Interface: [Commands/flags]
Performance: [Target metrics]
Dependencies: [Module dependencies]
Tests: [Test scenarios]
Docs: [API.md, README.md sections]

Feature: Recent Directories Command
Problem: Users can't quickly revisit recently navigated directories
Interface: goto recent [n]
Performance: <10ms for history retrieval
Dependencies: history-tracking.sh
Tests:
  - List recent directories
  - Handle empty history
  - Limit to N entries
  - Navigate to recent directory by number
Docs: Add to API.md and README.md

#!/bin/bash

case "$subcommand" in
    list)
        # Implementation
        ;;
    add)
        # Implementation
        ;;
    --help|-h|help|"")
        echo "goto module - [Description]"
        echo ""
        echo "Usage:"
        echo "  goto module list     [Description]"
        echo "  goto module add      [Description]"
        ;;
    *)
        echo "Unknown command: $subcommand"
        return 1
        ;;
esac

**Key Module Patterns:**

1. **Function Naming:**
   - Public functions: no prefix (`goto`, `bookmark`, `recent`)
   - Internal functions: double underscore (`__goto_navigate_to`, `__goto_cache_lookup`)
   - Variables: UPPERCASE for globals, lowercase for locals

2. **Environment Variables:**
   ```bash
   # Always provide defaults
   GOTO_INDEX_FILE="${GOTO_INDEX_FILE:-$HOME/.goto_index}"
   GOTO_CACHE_TTL="${GOTO_CACHE_TTL:-86400}"
   GOTO_SEARCH_DEPTH="${GOTO_SEARCH_DEPTH:-3}"

undefined

**Dependency Rules:**
- Modules with no dependencies load first
- Modules depending on others load AFTER dependencies
- Main goto-function.sh loads LAST (depends on everything)

goto() {
    case "$1" in
        module)  # NEW
            if command -v goto_module &> /dev/null; then
                shift
                goto_module "$@"
            else
                echo "⚠️  Module command not loaded"
            fi
            return
            ;;
    esac
}

#!/bin/bash

# Act
local result=$(function_under_test "$input")

# Assert
if [[ "$result" == "expected" ]]; then
    pass "Feature works"
else
    fail "Feature failed: got '$result'"
fi

**Test Categories (ALL Required):**

1. **Unit Tests** - Test individual functions
2. **Integration Tests** - Test module interaction
3. **Edge Cases** - Test boundary conditions
4. **Performance Tests** - Validate speed requirements

**Example from CET-77 (Recent Directories):**
```bash

undefined

undefined

goto module <subcommand>

goto module list
goto module add value

**Example from CET-77:**
```markdown

goto recent [n]

goto recent        # Show all recent directories
goto recent 5      # Show 5 most recent

undefined

undefined

goto module list    # [Description]
goto module add     # [Description]

undefined

undefined

**Performance Targets:**
- Cached navigation: <100ms
- Bookmark lookup: <10ms
- Cache speedup: >20x
- Cache hit rate: >90%
- Cache build: <5s

git commit -m "feat: implement module feature (CET-XX)

[Detailed explanation]

Features:
- Feature 1
- Feature 2

Performance:
- Metric: value

Tests:
- X/X tests passing
- 100% coverage

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

feat: implement comprehensive benchmark suite (CET-85)

Implement complete benchmark framework with 5 benchmark tests, helpers,
workspace generation, and CSV results storage.

Features:
- 5 benchmark tests: cached vs uncached, multi-level paths, max depth,
  cache build performance, parallel navigation
- Benchmark helpers library with timing, stats, workspace management
- CSV results storage in ~/.goto_benchmarks/
- Performance target assertions (<100ms navigation)
- Comprehensive statistical analysis (min/max/mean/median/stddev)

Performance:
- Cached navigation: 26ms (target: <100ms) ✓
- Cache build: 3-5s (target: <5s) ✓
- Speedup ratio: 8x (target: >20x, in progress)

Tests:
- 5/5 benchmark tests passing
- All performance targets met for Phase 1

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

undefined

**Performance:**
- Build time: O(n) - 3-5s for 1200+ folders
- Lookup time: O(1) - <100ms target, 26ms actual
- Storage: ~42KB for 487 folders

**Cache Lookup Return Codes:**
```bash
__goto_cache_lookup "folder"

undefined

User Input → goto "project"
    │
    ├─► Check special cases (list, index, benchmark, @bookmark)
    ├─► Check multi-level paths (contains /)
    ├─► Try cache lookup (O(1)) → Cache hit → Navigate
    ├─► Try direct folder match in search paths
    ├─► Recursive search (max depth 3)
    │   ├─► Single match → Navigate
    │   └─► Multiple matches → Show disambiguation
    └─► Natural language AI resolution (if spaces)

work|/Users/manu/work|1697558122
api|/Users/manu/code/api-server|1697558130

bookmark add work /path/to/work
bookmark remove work
goto @work

1697558122|/Users/manu/work
1697558130|/Users/manu/Documents/LUXOR

goto recent        # Show all recent directories
goto recent 5      # Show 5 most recent
back              # Go back to previous directory

Feature: Recent Directories Command
Problem: Users can't quickly revisit recently navigated directories
Interface: goto recent [n]
Performance: <10ms for history retrieval
Dependencies: history-tracking.sh
Tests: List recent, empty history, limit entries, navigate by number
Docs: API.md, README.md

#!/bin/bash

if [ ! -f "$GOTO_HISTORY_FILE" ]; then
    return 1
fi

# Extract paths, reverse order, unique, limit
local dirs=$(awk -F'|' '{print $2}' "$GOTO_HISTORY_FILE" | \
             tac | \
             awk '!seen[$0]++' | \
             ${limit:+head -n "$limit"})

echo "$dirs"
return 0

local dirs=$(__goto_recent_dirs "$limit")

if [ -z "$dirs" ]; then
    echo "No recent directories"
    return 1
fi

echo "$dirs"
return 0

**Step 3: Add to Loader** (`goto.sh`)
```bash
source "$GOTO_LIB_DIR/history-tracking.sh"
source "$GOTO_LIB_DIR/recent-command.sh"  # NEW

goto() {
    case "$1" in
        recent)
            shift
            goto_recent "$@"
            return
            ;;
    esac
}

#!/bin/bash
set -e

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
source "$SCRIPT_DIR/lib/recent-command.sh"

TESTS_PASSED=0
TESTS_FAILED=0

pass() { echo "✓ PASS: $1"; ((TESTS_PASSED++)); }
fail() { echo "✗ FAIL: $1"; ((TESTS_FAILED++)); }

**Step 6: Document API** (`docs/API.md`)
```markdown

goto recent        # Show all recent directories
goto recent 5      # Show 5 most recent

**Step 7: Update README** (`README.md`)
```markdown

goto recent        # Show all recent directories
goto recent 5      # Show 5 most recent

**Step 8: Validate Performance**
```bash
time goto recent

**Step 9: Commit**
```bash
git commit -m "feat: implement recent directories command (CET-77)

Add goto recent command to display recently navigated directories.

Features:
- List all recent directories
- Limit to N most recent
- Unique directories only
- Reverse chronological order

Performance:
- History retrieval: <10ms ✓

Tests:
- 3/3 tests passing
- 100% coverage

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

#!/bin/bash

echo "Configuration:"
echo "  Iterations: 10"
echo "  Warmup: 3 runs"
echo ""

benchmark_cached_vs_uncached

generate_summary

# Setup workspace
local workspace=$(bench_create_workspace "medium")

# Phase 1: Uncached lookup
echo "Phase 1: Uncached lookup (no cache)"
echo "─────────────────────────────────"

# Warmup
bench_warmup "__goto_cache_lookup unix-goto" 3

# Run benchmark
local uncached_stats=$(bench_run "uncached" \
    "__goto_cache_lookup unix-goto" 10)

IFS=',' read -r uc_min uc_max uc_mean uc_median uc_stddev <<< "$uncached_stats"

bench_print_stats "$uncached_stats" "Uncached Results"

# Phase 2: Cached lookup
echo ""
echo "Phase 2: Cached lookup (with cache)"
echo "─────────────────────────────────"

# Build cache
__goto_cache_build

# Warmup
bench_warmup "__goto_cache_lookup unix-goto" 3

# Run benchmark
local cached_stats=$(bench_run "cached" \
    "__goto_cache_lookup unix-goto" 10)

IFS=',' read -r c_min c_max c_mean c_median c_stddev <<< "$cached_stats"

bench_print_stats "$cached_stats" "Cached Results"

# Calculate speedup
local speedup=$(bench_compare "$uc_mean" "$c_mean")

echo ""
echo "Speedup Analysis:"
echo "  Speedup ratio:                               ${speedup}x"

# Assert targets
bench_assert_target "$c_mean" 100 "Cached navigation time"

# Save results
bench_save_result "cached_vs_uncached" "$uncached_stats" "uncached"
bench_save_result "cached_vs_uncached" "$cached_stats" "cached"

# Cleanup
bench_cleanup_workspace "$workspace"

**Benchmark Helpers** (`benchmarks/bench-helpers.sh`)
```bash
#!/bin/bash

# Sort values
IFS=$'\n' sorted=($(sort -n <<<"${values[*]}"))

# Min/Max
local min=${sorted[0]}
local max=${sorted[$((count-1))]}

# Mean
local sum=0
for val in "${values[@]}"; do
    sum=$((sum + val))
done
local mean=$((sum / count))

# Median
local mid=$((count / 2))
local median=${sorted[$mid]}

# Standard deviation
local variance=0
for val in "${values[@]}"; do
    local diff=$((val - mean))
    variance=$((variance + diff * diff))
done
variance=$((variance / count))
local stddev=$(echo "sqrt($variance)" | bc)

echo "$min,$max,$mean,$median,$stddev"

IFS=',' read -r min max mean median stddev <<< "$stats"

echo ""
echo "$label:"
printf "  Min:                                             %dms\n" "$min"
printf "  Max:                                             %dms\n" "$max"
printf "  Mean:                                            %dms\n" "$mean"
printf "  Median:                                          %dms\n" "$median"
printf "  Std Dev:                                       %.2fms\n" "$stddev"

if [ "$actual" -lt "$target" ]; then
    echo "✓ $label meets target: ${actual}ms (target: <${target}ms)"
else
    echo "✗ $label exceeds target: ${actual}ms (target: <${target}ms)"
fi

local name="$1"
local stats="$2"
local metadata="${3:-}"

local timestamp=$(date +%s)
local results_file="$BENCH_RESULTS_DIR/results.csv"

# Create header if file doesn't exist
if [ ! -f "$results_file" ]; then
    echo "timestamp,benchmark_name,operation,min_ms,max_ms,mean_ms,median_ms,stddev,metadata" > "$results_file"
fi

# Append result
echo "$timestamp,$name,$metadata,$stats" >> "$results_file"

case "$size" in
    small)
        # 10 folders
        for i in {1..10}; do
            mkdir -p "$workspace/folder-$i"
        done
        ;;
    medium)
        # 50 folders
        for i in {1..50}; do
            mkdir -p "$workspace/folder-$i"
        done
        ;;
    large)
        # 500 folders
        for i in {1..500}; do
            mkdir -p "$workspace/folder-$i"
        done
        ;;
esac

echo "$workspace"

local times=()

for i in $(seq 1 $iterations); do
    local time=$(bench_time_ms "$cmd")
    times+=("$time")
    printf "  Run %2d: %dms\n" "$i" "$time"
done

bench_calculate_stats "${times[@]}"

for i in $(seq 1 $iterations); do
    eval "$cmd" > /dev/null 2>&1
done

local speedup=$(echo "scale=2; $baseline / $optimized" | bc)
echo "$speedup"

undefined

function_name() {
    local param1="$1"
    local param2="${2:-default}"

    # Validate inputs
    if [ -z "$param1" ]; then
        echo "Error: param1 required"
        return 1
    fi

    # Main logic
    local result=$(process "$param1")

    # Return value
    echo "$result"
    return 0
}

undefined

**Comments:**
```bash

undefined

undefined

undefined

set -x
source goto.sh
goto test
set +x

if declare -f __goto_cache_lookup > /dev/null; then
    echo "Function loaded"
fi

undefined

undefined

Backlog → In Progress → Complete

undefined

undefined

undefined

undefined

~/.goto_index         - Cache file
~/.goto_bookmarks     - Bookmarks file
~/.goto_history       - History file
~/.goto_stack         - Navigation stack
~/.goto_benchmarks/   - Benchmark results directory