Name: unix-goto-development
Author: manutej

Expert guidance for unix-goto shell navigation tool development, including architecture, 9-step feature workflow, testing (100% coverage), performance optimization (<100ms targets), and Linear issue integration

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 Module Dependencies Critical Load Order (dependencies must load before dependents): 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: Example Recent Directories Feature (CET 77): Step 2: Create Module (if needed) Module Template: 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: 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: 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: Step 5: Add Tests (100% Coverage Required) Test File Template: 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): Step 6: Document API Add to docs/API.md : bash goto module <subcommand bash goto module list goto module add value Example from CET 77: bash goto recent [n] bash goto recent Show all recent directories goto recent 5 Show 5 most recent Step 7: Update User Documentation Add to README.md : bash goto module list [Description] goto module add [Description] Step 8: Performance Validation Validate performance meets targets: Performance Targets: Cached navigation: <100ms Bookmark lookup: <10ms Cache speedup: 20x Cache hit rate: 90% Cache build: <5s Step 9: Linear Issue Update & Commit Update Linear Issue: Add implementation comment Include test results Include performance metrics Link to commit Move to "Complete" Commit Format: Commit Types: feat: New feature fix: Bug fix perf: Performance improvement refactor: Code refactoring test: Add or update tests docs: Documentation only chore: Build, dependencies, or tooling Example Commit from CET 85: Feature Checklist Before submitting ANY feature: [ ] Implementation complete [ ] Loaded in goto.sh [ ] Integrated with main goto function [ ] Tests written and passing (100% coverage) [ ] API documented in docs/API.md [ ] User documentation updated in README.md [ ] Performance validated (if applicable) [ ] Linear issue updated with results [ ] Committed with proper message format Cache System Architecture Purpose: O(1) folder lookup with automatic refresh Implementation: lib/cache index.sh Key Components: goto cache build O(n) index building goto cache lookup O(1) hash table lookup goto cache is valid TTL based validation Auto refresh on stale cache (24 hour TTL) Cache File Format: 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: Navigation Data Flow Bookmark System Architecture Storage: ~/.goto bookmarks Format: Key Functions: goto bookmark add Add with validation goto bookmark remove Remove by name goto bookmark get Retrieve path (O(1) grep) goto bookmark goto Navigate to bookmark Performance Target: <10ms lookup time Usage: History Tracking Architecture Storage: ~/.goto history Format: Key Functions: goto track Append with auto trim (max 100 entries) goto get history Retrieve full history goto recent dirs Get unique directories in reverse chronological order goto stack push/pop Stack based back navigation Example Usage: Examples Example 1: Adding a Recent Directories Feature (CET 77) Step 1: Plan Step 2: Create Module ( lib/recent command.sh ) Step 3: Add to Loader ( goto.sh ) Step 4: Integrate ( lib/goto function.sh ) Step 5: Add Tests ( test recent.sh ) Step 6: Document API ( docs/API.md ) bash goto recent Show all recent directories goto recent 5 Show 5 most recent Step 7: Update README ( README.md ) bash goto recent Show all recent directories goto recent 5 Show 5 most recent Step 8: Validate Performance Step 9: Commit Example 2: Adding Benchmark Suite (CET 85) Complete benchmark implementation with helpers, workspace, and CSV storage. Benchmark Structure ( benchmarks/bench cached vs uncached.sh ) Benchmark Helpers ( benchmarks/bench helpers.sh ) Best Practices Code Style Standards Function Structure: Error Handling: Comments: Data File Format Pattern Standard format: Pipe delimited with metadata header Performance Optimization Tips Cache System: Use cache for all lookups Limit recursive search depth Avoid redundant filesystem operations Use grep for fast text matching Memory: Cache file: <100KB for 500 folders Memory usage: Minimal (shell functions only) No persistent processes Debugging Tips Enable Bash Tracing: Check Function Existence: Debug Cache Issues: Linear Workflow Integration Linear Project Details: Team: Ceti luxor Project: unix goto Shell Navigation Tool Project ID: 7232cafe cb71 4310 856a 0d584e6f3df0 Issue Lifecycle: Standard Workflow: 1. Pick an issue from Phase 3 backlog 2. Move to "In Progress" in Linear 3. Create feature branch: feature/CET XX feature name 4. Implement following 9 step workflow 5. Test thoroughly (100% coverage) 6. Commit with proper format 7. Update Linear issue with results 8. Move to "Complete" Linear Issue Template: Quick Reference Essential Commands File Locations Performance Targets Summary Metric Target Current Cached navigation <100ms 26ms ✓ Cache build <5s 3 5s ✓ Cache hit rate 90% 92 95% ✓ Speedup ratio 20 50x 8x ⚠ Test coverage 100% 100% ✓ Skill Version: 1.0 Last Updated: October 2025 Maintained By: Manu Tej + Claude Code Source Repository: https://github.com/manutej/unix goto