unix-goto-development

What this skill does

# unix-goto Development Expert

Comprehensive development expertise for the unix-goto shell navigation system - a high-performance Unix navigation tool with natural language support, sub-100ms cached navigation, and 100% test coverage.

## When to Use This Skill

Use this skill when:
- Developing new features for unix-goto shell navigation system
- Implementing cache-based navigation optimizations
- Adding bookmarks, history, or navigation commands
- Following the standard 9-step feature addition workflow
- Integrating with Linear project management
- Writing comprehensive test suites (100% coverage required)
- Optimizing performance to meet <100ms targets
- Creating API documentation for shell modules
- Debugging navigation or cache issues

Do NOT use this skill for:
- General bash scripting (use generic bash skills)
- Non-navigation shell tools
- Projects without performance requirements
- Simple one-off shell scripts

## Project Overview

### unix-goto System Architecture

unix-goto is a high-performance Unix navigation system designed with five core principles:

1. **Simple** - ONE-line loading (`source goto.sh`), minimal configuration
2. **Fast** - Sub-100ms navigation performance
3. **Lean** - No bloat, no unnecessary dependencies
4. **Tested** - 100% test coverage for core features
5. **Documented** - Clear, comprehensive documentation

### Key Performance Metrics

| Metric | Target | Achieved | Status |
|--------|--------|----------|--------|
| Cached navigation | <100ms | 26ms | ✅ Exceeded |
| Cache hit rate | >90% | 92-95% | ✅ Exceeded |
| Speedup ratio | 20-50x | 8x | ⏳ On track |
| Test coverage | 100% | 100% | ✅ Met |
| Cache build time | <5s | 3-5s | ✅ Met |

### System Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      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    │
└──────────────────┘ └──────────────┘ └──────────────────┘
```

### Module Dependencies

**Critical Load Order** (dependencies must load before dependents):

```
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)
```

## Core Knowledge

### The 9-Step Feature Addition Workflow

This is the STANDARD process for adding any feature to unix-goto. Follow ALL nine steps.

#### Step 1: Plan Your Feature

Before writing ANY code, answer these questions:

**Planning Questions:**
- What problem does this solve?
- What's the user interface (commands/flags)?
- What's the expected performance?
- What dependencies exist?
- What tests are needed?
- What documentation is required?

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

**Example - Recent Directories Feature (CET-77):**
```
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
```

#### Step 2: Create Module (if needed)

**Module Template:**
```bash
#!/bin/bash
# unix-goto - [Module purpose]
# https://github.com/manutej/unix-goto

# Storage location
GOTO_MODULE_FILE="${GOTO_MODULE_FILE:-$HOME/.goto_module}"

# Main function
goto_module() {
    local subcommand="$1"
    shift

    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}"
   ```

3. **Return Codes:**
   - `0` - Success
   - `1` - General error (not found, invalid input)
   - `2` - Multiple matches found (cache lookup only)

#### Step 3: Add to Loader

Edit `goto.sh` to load your module in the correct dependency order:

```bash
# Add to load sequence (respect dependencies)
source "$GOTO_LIB_DIR/history-tracking.sh"
source "$GOTO_LIB_DIR/module.sh"  # NEW - add after dependencies
source "$GOTO_LIB_DIR/back-command.sh"
```

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

#### Step 4: Integrate with Main Function

Edit `lib/goto-function.sh` to route commands to your module:

```bash
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
}
```

#### Step 5: Add Tests (100% Coverage Required)

**Test File Template:**
```bash
#!/bin/bash
# Test suite for [feature] functionality

set -e

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

# Test counters
TESTS_PASSED=0
TESTS_FAILED=0

# Test helper
pass() {
    echo "✓ PASS: $1"
    ((TESTS_PASSED++))
}

fail() {
    echo "✗ FAIL: $1"
    ((TESTS_FAILED++))
}

# Test 1: [Description]
test_feature() {
    # Arrange
    local input="test"

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

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

# Run tests
test_feature

# Summary
echo ""
echo "Tests passed: $TESTS_PASSED"
echo "Tests failed: $TESTS_FAILED"

[ $TESTS_FAILED -eq 0 ] && exit 0 || exit 1
```

**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
# Unit