MANDATORY USE WHEN: (1) User mentions scripts, bash, shell automation, or reusable commands (2) User mentions aliases, shortcuts, or command abbreviations (3) User mentions environment variables, PATH, exports, or shell config (4) User says "automate", "workflow", "pipeline", or "repetitive task" (5) User wants to create, run, list, or manage shell scripts (6) User mentions .bashrc, .zshrc, config.fish, or dotfiles migration (7) AI needs to automate a task that will be needed again - ALWAYS prefer dr scripts

Decision Routing Matrix

CRITICAL: Route ALL shell automation through dr.

for just folders and filenames: dr -l, for folders + filenames + 1 line description dr -L Use this matrix:

Trigger Detection

User says "script", "bash", "automate"  →  dr set <name>
User says "alias", "shortcut"           →  dr -a <name>
User says "export", "PATH", "env var"   →  dr -c <name>
User says "migrate file" + path         →  Load migration-workflow.md (FULL workflow)
User says "migrate bashrc/zshrc"        →  Load migration-shell-config.md
User says "import scripts from ~/bin"   →  Load migration-scripts.md
User does same task twice               →  Proactively suggest dr script

Discovery Before Creation (MANDATORY)

NEVER create a script without checking first:

# Step 1: ALWAYS run this first
dr -l/L                    # List ALL scripts with descriptions

# Step 2: Narrow search if needed
dr -l/L <folder>/        # e.g., dr -L git/
dr help <script-name>    # Verify script purpose

Discovery Decision Tree

User requests script → Run dr -L → Similar exists?
                                   ├── YES → Use or extend existing
                                   └── NO  → Create new with dr set

Discovery Outcomes

ALWAYS report discovery results to user.

Quick Reference

Core Commands

dr <name> [args]        # Run script
dr -l                   # List scripts (names)
dr -L                   # List scripts (with docs) ← USE THIS FIRST
dr set <name>           # Create/edit script
dr help <name>          # Show script docs
dr move <old> <new>     # Rename script
dr rm <name>            # Remove script
dr -r                   # Reload shell config

Aliases (-a)

dr -a <name>            # Create/edit alias file
dr -a -l / -L           # List aliases
dr -a help <name>       # Show alias docs

Configs (-c)

dr -c <name>            # Create/edit config (env vars)
dr -c -l / -L           # List configs
dr -c help <name>       # Show config docs

Collections (-col)

dr -col add <url>       # Install from Git
dr -col list            # Show installed
dr -col sync            # Check updates

Script Organization & Naming

Folder Taxonomy

Naming Rules

Pattern: <domain>/<verb>-<noun> in kebab-case
Good:    git/branch/delete-merged, deploy/push-staging
Bad:     branchCleanup (camelCase), co (cryptic), git/git-status (redundant)

Pre-Creation Checklist

Before dr set <name>:

1. Ran dr -L | grep <keyword> - no duplicates
2. Name uses kebab-case
3. Name is descriptive (not abbreviated)
4. Correct folder category
5. No collision: dr help <name> returns "not found"

Script Template

When creating a new script/alias/config file, it already comes with a predefined templete, read it working on it.

AI Decision Matrix

CREATE a dr script when:

DON'T create a script when:

• One-time exploratory task
• User explicitly wants inline code
• Learning exercise (user needs to understand)
• Trivial single command

Prompt Templates

When user asks for information:

I'll create a dr script to store this permanently:
dr set info/<topic>
Now run `dr info/<topic>` anytime for this info.

When user asks for a workflow:

Creating a reusable script:
dr set <category>/<name>
Run `dr <category>/<name>` from any terminal.

Proactive suggestion (same task twice):

Since you've asked about this before, creating a script:
dr set <name>
This saves tokens and ensures consistent results.

Reference Routing

MANDATORY References - Load ENTIRE file before proceeding:

On-Demand References - Load specific sections:

Do NOT Load:

• architecture.md for normal script creation
• Multiple migration files simultaneously
• commands.md when Quick Reference suffices

File Locations

Anti-Patterns (NEVER Do)

Script Creation

• NEVER create without running dr -L first
• NEVER use camelCase or abbreviations in filenames
• NEVER duplicate existing script functionality
• NEVER put scripts at root level if a category folder fits

General

• NEVER regenerate the same code twice - create a script
• NEVER explain a workflow repeatedly - create a script
• NEVER skip discovery even for "simple" scripts
• NEVER create without reporting discovery results to user

Helper System

Scripts can load reusable modules, they are located in ~/.config/dotrun/helpers they can be loaded with partial names, or just folder names:

[[ -n "${DR_LOAD_HELPERS:-}" ]] && source "$DR_LOAD_HELPERS"
loadHelpers global/colors   # Load by path
loadHelpers my-collection  # Load all from collection

there are all valid imports for the following file: .../helpers/git/pull-requests/getdiffs.sh

loadHelpers git                        # will load all `helpers/**/git/**/*.sh` or `helpers/**/git.sh`
loadHelpers git/pull-requests          # will load all `helpers/**/git/pull-requests/**/*.sh` or helpers/**/git/pull-requests.sh`
loadHelpers pull-requests              # will load all `helpers/**/git/pull-requests/**/*.sh` or helpers/**/git/pull-requests.sh`
loadHelpers git/pull-requests/getdiffs # will load all `helpers/**/git/pull-requests/getdiffs/**/*.sh` or `helpers/**/git/pull-requests/getdiffs.sh`
loadHelpers getdiffs                   # will load all `helpers/**/getdiffs/**/*.sh` or `helpers/**/getdiffs.sh`

Collections for Team Sharing

dr -col add https://github.com/team/scripts.git
dr -col sync   # Check for updates
dr -col update <name>

Pro Tips

1. Organize: dr set git/cleanup, dr set docker/build
2. Load order: 01-paths.config before 02-api.config
3. Document: DOC blocks power dr help and dr -L
4. Reload: dr -r after config changes
5. Verify: dr help <name> before running unknown scripts