version
1.5.0
GitHub stars
13

Install

/plugin install dev-tools@pickled-claude-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add technicalpickles/pickled-claude-plugins.

Contents

Discovered from source

Skills 8

Adopting Renovate

Policy lives in the shared presets at technicalpickles/renovate-config. This skill is the procedure for applying them to one repo. When a lesson changes policy, fix the preset, not the repo.

Prerequisites

  • Renovate CLI: npm:renovate in the global mise tools (mise exec npm:renovate -- renovate --version). mise install npm:renovate on the command line resolves latest and ignores config options, so use plain mise install.
  • gh authenticated with read access to the repo.
  • The Renovate GitHub app has access to the repo. A config does nothing without it; see Gotchas.

What the shared presets do

Know this before promising anyone when PRs will show up.

  • Schedule: Monday before 5am UTC. It gates when Renovate may create branches and PRs, not when it runs. The app runs all the time, so the Dependency Dashboard issue is ungated and appears or updates right away, even on a Wednesday. Grouped PRs wait for the window.
  • Majors need dashboard approval. They are listed on the Dependency Dashboard and only become PRs after someone ticks them.
  • :lockfile is opt-in. The base preset does not refresh lockfiles. Add :lockfile only when asked.
  • 7-day cooldown, 3 concurrent PRs. A release younger than a week is not proposed yet, and no more than three PRs are open at once. Security fixes skip both, and the schedule.
  • No automerge unless the repo extends :automerge.

So on a fresh adoption, expect the onboarding PR or dashboard issue now, grouped PRs after the next Monday window, and majors never until approved.

Procedure

1. Detect ecosystems

gh api repos/<owner>/<repo>/contents -q '[.[].name]|join(" ")'
FilesManager
package.json, package-lock.jsonnpm
Cargo.toml, Cargo.lockcargo
go.modgomod
pyproject.toml, uv.lockpep621 / uv
Gemfile, *.gemspecbundler
mise.toml, .mise.tomlmise
Dockerfile, .devcontainer/dockerfile
.github/workflows/*.y*mlgithub-actions

Flag any mise tool pinned to "latest": Renovate cannot bump it. Pin it in the same PR.

2. Decide on automerge

Automerge only when main has required status checks.

gh api repos/<owner>/<repo>/branches/main/protection -q '.required_status_checks.contexts|join(",")'

Empty or a 404 means PRs only. No pull_request workflows at all means PRs only and say so in the PR body.

3. Write renovate.json

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "github>technicalpickles/renovate-config",
    "github>technicalpickles/renovate-config:mise",
    "github>technicalpickles/renovate-config:automerge"
  ]
}

Include only the presets that apply: :mise when there is a mise config, :automerge per step 2, :lockfile only if asked. Put local overrides below extends. A mise config outside the repo root needs "mise": {"managerFilePatterns": ["/^config/mise/.+\\.toml$/"]}.

Validate it:

mise exec npm:renovate -- renovate-config-validator renovate.json

4. Dry-run before merging

This lists the branches Renovate would open and changes nothing. The git clone fails inside the Claude Code sandbox (proxy aborts HTTPS), so this one command needs the sandbox off. It only reads the repo.

cat > "$SCRATCH/config.js" <<'EOF'
module.exports = { extends: ["github>technicalpickles/renovate-config", "github>technicalpickles/renovate-config:mise"] };
EOF
RENOVATE_CONFIG_FILE="$SCRATCH/config.js" RENOVATE_TOKEN="$(gh auth token)" \
  LOG_LEVEL=debug LOG_FORMAT=json RENOVATE_PLATFORM=github RENOVATE_DRY_RUN=full \
  RENOVATE_REPOSITORIES=<owner>/<repo> RENOVATE_ONBOARDING=false RENOVATE_REQUIRE_CONFIG=optional \
  mise exec npm:renovate -- renovate > "$SCRATCH/run.log" 2>&1

jq -r 'select(.msg=="branches info extended")|.branchesInformation[]|"\(.branchName) | \(.prTitle // "")"' "$SCRATCH/run.log"
jq -r 'select(.msg|test("creation is disabled because dependencyDashboardApproval"))|.msg' "$SCRATCH/run.log"

Read the output:

  • Majors show in the branch list but are held: "creation is disabled because dependencyDashboardApproval=true". They only become PRs when someone ticks them on the Dependency Dashboard.
  • The PRs that will actually open are the grouped ones plus a single "pin dependencies" PR. More than a handful means a grouping rule is missing from the preset.
  • Check that every ecosystem from step 1 appears. A manager that detected files but planned nothing deserves a look (see the go gotcha).

5. Open the PR

Use the git:pull-request skill. If Renovate already opened its own "Configure Renovate" onboarding PR, ours replaces it: merge ours and the onboarding PR autocloses. Mention the preset repo in the body, and the dry-run branch count.

Checking that the app is onboarded

There is no API for whether the Renovate app has access to a repo. Look for evidence instead, any one of:

  • A "Configure Renovate" onboarding PR from the app.
  • A Dependency Dashboard issue.
  • The Mend portal job log for the repo (app.renovatebot.com), which shows runs and errors.

None of these after a run, with the config merged, means the app is not installed on the repo.

Check the merge method

Renovate's PRs and the onboarding PR follow the repo's allowed merge methods. Squash may be disabled on a repo, which makes gh pr merge --squash fail and automerge stall:

gh api repos/<owner>/<repo> -q '{squash: .allow_squash_merge, merge: .allow_merge_commit, rebase: .allow_rebase_merge}'

If squash is off, merge with a method that is on, or pick automergeStrategy to match, rather than changing repo settings unasked.

6. After it merges

Enable dependency alerts so security fixes can be found (they skip the cooldown and the schedule):

gh api -X PUT repos/<owner>/<repo>/vulnerability-alerts

Look for the Dependency Dashboard issue and the first grouped PRs after the next scheduled run (Monday before 5am UTC). If nothing appears, the app is probably not installed on the repo.

Pinning floating images

Compose files and Dockerfiles often use floating tags (image: postgres:latest, image: nginx). Renovate cannot bump a floating tag, so pin it, and pin to what is actually running rather than to whatever is newest:

docker ps --format '{{.Names}} {{.Image}}'
docker inspect --format '{{index .RepoDigests 0}}' <container>

Read the real version from the running container (its image label, or the binary's --version), write that tag into the file, and let Renovate propose the upgrade later. Pinning to the newest tag in the same PR mixes an upgrade into an adoption change.

Gotchas

  • The app must be installed per repo. No Renovate PRs, branches or Dependency Dashboard issue after a scheduled run means the app has no access. gh cannot list installations (needs a GitHub App token); check the repo's access list in GitHub settings or the Mend portal.
  • extractVersion on every mise tool drops updates. A rule that strips the v prefix must be scoped with matchDepNames: ["github:**"]. Unscoped, it silently removed go updates. The :mise preset already scopes it; a hand-rolled rule may not.
  • Cooldown vs provenance. minimumReleaseAge (7 days in the base preset) holds every package, including your own tools unless the preset exempts them. Renovate reads npm provenance only to add a caution note to a PR body when a new version loses an attestation, and never blocks on it.
  • mise has its own trust check. mise's aube installer can reject a transitive npm dependency that lost provenance (trustPolicy=no-downgrade). Vet the release, then exclude the exact package@version via trust_policy_excludes on that tool, with the reasoning in a comment.
  • Public presets only. github> presets are fetched from GitHub; keep the preset repo public.
  • Dry-run caveat. The dry-run does not prove automerge fires or that a lockfile like go.sum comes out right. Watch the first real PR.

Colima

Overview

Colima provides container and VM runtimes (Docker, Containerd, Incus) on macOS with minimal setup. It runs a Linux VM and exposes the chosen runtime to the host.

Use this skill when:

  • Docker commands fail ("Cannot connect to Docker daemon")
  • Starting/stopping container runtime on macOS
  • Managing multiple Docker profiles/contexts
  • Troubleshooting container environment issues
  • Need SSH agent forwarding for Docker builds
  • Running incus on macOS (system containers or VMs with nested virtualization)

Not for: Docker Compose or Kubernetes clusters.

Quick Reference

OperationCommand
Startcolima start or colima start <profile>
Start with SSH agentcolima start <profile> -s
Stopcolima stop or colima stop --force
Statuscolima status -p <profile>
List profilescolima list
SSH into VMcolima ssh or colima ssh -- <cmd>
SSH with chained commandscolima ssh -- bash -c "cmd1 && cmd2"
Get socket pathcolima status -p <profile> --json | jq -r .docker_socket

Docker Context Basics

Colima creates Docker contexts per profile:

  • Profile default → context colima
  • Profile work → context colima-work
# Switch context (global - affects all terminals)
docker context use colima-work

# Override per-session
export DOCKER_CONTEXT=colima-work

# Override per-command
docker --context colima-work ps

For details, see references/docker-contexts.md.

Common Issues

Docker daemon not connecting?

  1. colima status - is it running?
  2. docker context list - right context selected?
  3. See references/troubleshooting.md for more

Need more VM resources?

colima stop && colima start --cpu 4 --memory 8

"Broken" status after restart?

colima stop --force && colima start

References

  • references/ssh-commands.md - SSH command syntax, chaining, escaping
  • references/docker-contexts.md - Context switching, DOCKER_HOST, socket paths
  • references/profile-management.md - Creating, configuring, deleting profiles
  • references/troubleshooting.md - Common issues and solutions
  • references/common-options.md - Flags, VM types, resource configuration
  • references/incus-runtime.md - Running incus (containers + VMs with nested virt) on Apple Silicon

Upstream Documentation

Local copies of official Colima docs (from github.com/abiosoft/colima):

  • references/colima-upstream/README.md - Official README with features and usage
  • references/colima-upstream/FAQ.md - Official FAQ and troubleshooting
  • references/colima-upstream/INSTALL.md - Installation options

Designing CLIs

Overview

Modern CLIs are conversations between human and machine. Great CLIs feel discoverable, responsive, and forgiving. Poor CLIs leave users guessing, waiting, and frustrated.

Core principle: Every CLI interaction should answer: "What happened? What can I do? What's next?"

When to Use

Building:

  • Creating new CLI commands or tools
  • Designing output format, error messages, progress indicators
  • Planning CLI architecture (flags, subcommands, interaction model)

Improving:

  • Enhancing existing CLI user experience
  • Adding features to existing commands
  • Making CLI "less confusing" or "easier to use"

Reviewing:

  • Auditing CLI code for UX issues
  • Responding to user complaints about difficulty
  • Troubleshooting discoverability problems

Quick Decision Framework

Working OnRead This
New CLI under time pressurepractical-patterns.md (Priority Checklist)
Adding to existing CLIpractical-patterns.md (Working with Existing CLIs)
Fixing "confusing" CLIpractical-patterns.md (CLI UX Audit Checklist)
Command structure, flagsux-principles.md (Familiarity, Discoverability)
Output formattingvisual-techniques.md (Layout, Spacing, Color)
Error messages, help textpractical-patterns.md (Error Message Patterns)
Overall architectureux-principles.md (complete overview)

The Six UX Principles

  1. Familiarity - Use known conventions (--help, --version, verb-noun)
  2. Discoverability - Guide users (help text, prompts, examples)
  3. Feedback - Show what's happening (progress, confirmations, state)
  4. Clarity - Structure output (spacing, alignment, hierarchy)
  5. Flow - Minimize friction (shortcuts, defaults, scriptability)
  6. Forgiveness - Handle errors gracefully (clear messages, suggestions, safety)

See ux-principles.md for detailed guidance and examples.

The Five Visual Techniques

  1. Color - Semantic meaning (green=success, red=error, yellow=warning)
  2. Spacing - Visual grouping (blank lines, indentation, alignment)
  3. Layout - Structured regions (panels, blocks, persistent areas)
  4. Symbols - Fast signifiers (✓ ✗ ⚠ →, checkboxes, progress indicators)
  5. Structured Feedback - Narrative output (phases, lists, visible progress)

See visual-techniques.md for implementation patterns.

Common Mistakes

❌ Silent operations - No feedback during slow operations ✅ Show progress, confirmations, or at minimum "Working..."

❌ Cryptic errors without guidance - "Error: invalid input" ✅ Explain what's wrong, what's valid, how to fix: "Error: Invalid environment 'production'. Valid: dev, staging, prod"

❌ No --help text - Forces users to read docs or source ✅ Every command supports --help with usage and examples

❌ Wrong exit codes - Always returns 0, breaks scripting ✅ 0 for success, 1 for errors

❌ Color-only information - Inaccessible without color support ✅ Always pair color with text/symbols, support --no-color

❌ Walls of unstructured text - Dense output hard to scan ✅ Use spacing, alignment, hierarchy to structure information

Priority Under Time Pressure

When building CLI urgently, include these first (high impact, low effort):

  1. --help flag (2 minutes) - Include usage, examples, common flags
  2. Exit codes (1 minute) - 0=success, 1=error, enables CI/CD
  3. Clear errors (5 minutes) - What happened + what's valid + how to fix
  4. Progress feedback (3 minutes) - Show activity during slow operations

Skip initially (lower priority):

  • Color schemes (polish, not function)
  • Advanced formatting (tables, columns)
  • Multiple output formats (JSON, YAML, etc.)

Cross-References

Detailed guidance:

  • practical-patterns.md - Checklists, templates, decision trees
  • ux-principles.md - Principles with real-world examples
  • visual-techniques.md - Implementation patterns for terminal output
  • reading-list.md - Sources and deeper learning

Research materials:

  • research/ - Original blog-style documentation and analysis

API Documentation Discovery

Overview

When an API call fails in a way that points at a version mismatch, look up the installed version's docs instead of retrying from memory. Training data ages; the installed version is the truth.

When to Use

  • Two or more failed attempts against the same library or API.
  • Errors like "method not found", "wrong number of arguments", "unknown flag", "undefined method", or a version mismatch in a stack trace.
  • You're about to rely on an API detail you haven't checked against the installed version, including one the user is sure of that keeps failing.

Skip it for a first failure whose error names the fix, and for errors that aren't about API usage (logic bugs, type errors in your own code).

The Discovery Workflow

Step 1: Stop retrying

Treat the trigger as the signal to look it up, not to try another variation.

Step 2: Identify Context

  • What library/framework is failing? (check imports, stack traces, go.mod/Gemfile)
  • What version is installed? (language tools show this)
  • What operation are you trying? (the actual goal, not the syntax attempt)

Step 3: Use Language Discovery Tools

Check language-specific reference for HOW to discover documentation:

  • references/go.md - Go module exploration
  • references/ruby.md - Ruby gem exploration

Follow progressive discovery: docs → examples → source

Step 4: Verify Before Using

  • Found API signature? Verify it matches your use case
  • Found example? Adapt it, don't just copy pattern from memory
  • Found docs? Read them, don't skim for confirmation

Common Anti-Patterns

RationalizationReality
"User is confident, syntax is probably right"User confidence ≠ current API. Verify.
"Training data shows this pattern"Training data ages. Check installed version.
"Let me try one more variation"Guessing wastes time. Check docs now.
"This is documented somewhere"Then go READ it before claiming confidence.
"Should be simple, just tweak syntax"Simplicity bias. Use discovery tools.
"We've spent enough time on this"Sunk cost fallacy. 2 min checking docs beats 20 min guessing.

Navigation: Language References

Available language discovery guides:

  • references/go.md - Go: go doc, go list, example/test scanning
  • references/ruby.md - Ruby: bundle info, ri, gem exploration

Path issues: If go or bundle isn't found, mise exec -- <command> is fine for a one-off doc lookup. If it keeps happening, it's a shell activation problem; see dev-tools:working-with-mise.

Extending this skill: To add a new language reference, see references/WRITING.md for principles and template.

After Finding Documentation

  1. Verify: API signature matches your use case
  2. Adapt: Use the pattern for your specific need
  3. Test: Try the verified approach
  4. Update understanding: Note what changed from your training data

hk - Git Hook Manager

Overview

hk is a fast git hook manager by jdx (author of mise). Uses pkl configuration language. Provides 90+ built-in linters.

Docs: https://hk.jdx.dev/ GitHub: https://github.com/jdx/hk

Detection

Identify which hook manager a project uses:

FileHook Manager
hk.pklhk
lefthook.ymllefthook
.husky/ directoryhusky
.pre-commit-config.yamlpre-commit (python)

Key Commands

hk init              # Create initial hk.pkl
hk install           # Set up git hooks
hk check             # Run checks manually (read-only)
hk fix               # Auto-fix issues
hk builtins          # List available builtins
hk validate          # Validate config
hk config dump       # Show effective configuration

Core Concepts

  • Hooks: Git hook types (pre-commit, commit-msg, pre-push)
  • Steps: Named units of work within hooks
  • Builtins: Pre-configured linters (90+) via Builtins.pkl
  • Profiles: Enable/disable groups of steps (--profile slow)

Configuration

When editing hk.pkl, read hk-pkl-reference.md in this skill directory for structure and examples.

Built-in Linters

When looking up builtins, read builtins-reference.md in this skill directory. Or run hk builtins for the live list.

Finding Help

Stable reference: Read the reference files in this skill directory when needed.

Latest docs:

npx @mdream/crawl https://hk.jdx.dev/ --output /tmp/hk-docs

GitHub issues:

gh issue list -R jdx/hk                    # List open issues
gh search issues --repo jdx/hk "error"     # Search issues
gh issue view 123 -R jdx/hk                # View specific issue

Troubleshooting

Hook not running:

hk install        # Reinstall hooks
cat .git/hooks/pre-commit  # Verify hook calls hk

Step skipped:

hk check -v       # Verbose output shows skip reasons
hk config dump    # Check effective configuration

Validate config:

hk validate       # Check hk.pkl syntax

Working in Scratch Areas

One-off scripts, debug tools, analysis notes, and reports worth keeping go in the repo's .scratch/ area, not in the repo tree or a temp dir. .scratch is a symlink from the repo root to a per-repo directory under a central scratch-areas root, so the files outlive the checkout and never get committed. (The session scratchpad the harness provides is still the place for throwaway intermediates nobody will look at again.)

Setup

test -L .scratch tells you whether the repo has one. If not:

  1. Find the areas root: a "Scratch Areas" line in ~/.claude/CLAUDE.md (the setup script reads it), else ask the user. Suggest ~/workspace/scratch-areas, or a scratch-areas/ dir next to the repo.
  2. From the repo root, run this skill's scripts/setup-scratch-area.sh [--areas-root PATH] [--save-to-claude-md]. It creates the repo's area, the .scratch symlink, and a README from the template. Skip --save-to-claude-md when ~/.claude/CLAUDE.md is generated from dotfiles; add the line to its source instead.
  3. Make sure .scratch is gitignored, globally (git config --global core.excludesfile) or in the project .gitignore.

Rules

  • Always a topic subdirectory (.scratch/database-debug/), never the .scratch/ root. Reuse a relevant existing subdirectory if there is one (ask if unsure). Each subdirectory gets a README.md: what's in it, what investigation spawned it, how the files relate.
  • Every file starts with a header: purpose, date created, and what it was used for. Scripts also need a shebang.
  • Make scripts executable with this skill's scripts/make-executable <file> (checks for a shebang; approved once instead of per-file chmod), then run them directly (./.scratch/sub/script.sh), not through an interpreter, so allow-lists match.
  • Never delete; document instead. When a file is done, add a [RESOLVED - <date>] header: how it was used, what it found, why it's kept.
  • Never commit scratch files. Stage explicit paths, never git add . or git add -A.

If ~/workspace/pickled-scratch-area/ exists, it holds one-time migration and test tools for scratch areas.

Working with mise

Overview

mise is a polyglot tool version manager. Use this skill when:

  • Adding tools to a project via mise
  • Troubleshooting "command not found" when mise should have tools available
  • Deciding whether mise is the right choice for a dependency

Rules

  1. Add tools with mise use, not by editing config by hand: it checks the tool exists, installs it, and writes valid syntax.
  2. Use the config file the project already has; don't create a second one.
  3. Fix the shell when tools aren't on PATH: diagnose activation instead of making mise exec the permanent workaround.

When to Use mise vs Alternatives

Use mise when version matters per-project

Tools where different projects need different versions:

  • Language runtimes: node, python, ruby, go, rust
  • Infrastructure tools: terraform, kubectl, helm
  • Tools with breaking changes between versions
# Good mise candidates - version sensitivity
mise use node@20      # Projects may need different Node versions
mise use terraform@1.5  # IaC often pins specific versions
mise use ruby@3.2     # Gemfiles often require specific Ruby

Use Homebrew/system when version rarely matters

Stable CLIs with consistent interfaces across versions:

  • jq, yq - query languages are stable
  • gh, hub - GitHub CLI
  • ripgrep, fd - search tools
  • tree, htop - system utilities
# Better as Homebrew - version doesn't matter
brew install jq gh ripgrep

Decision checklist

Ask yourself:

  1. Does this project's README/docs specify a version? → mise
  2. Could different team members need different versions? → mise
  3. Does the tool have breaking changes between versions? → mise
  4. Is it a stable CLI you use the same way everywhere? → Homebrew

Adding Tools with mise

1. Check for existing config files first

Before adding tools, detect what config format the project uses:

# Check for existing mise config
ls -la mise.toml .mise.toml mise.local.toml .mise.local.toml .tool-versions 2>/dev/null

Config file precedence (mise uses the first it finds):

  • mise.toml or .mise.toml - standard mise config
  • mise.local.toml or .mise.local.toml - local overrides (usually gitignored)
  • .tool-versions - legacy asdf format

If a config file exists, use that format. Don't create a new one.

2. Use mise use to add tools

Always use the CLI - it validates the tool exists and works:

# Add to project config (mise.toml or existing format)
mise use node@20

# Add to global config (~/.config/mise/config.toml)
mise use -g python@3.12

# Dry run to see what would happen
mise use --dry-run terraform@1.5

Never manually edit config files - mise use ensures:

  • The tool/version exists in the registry
  • The tool installs correctly
  • The config syntax is valid

3. Verify the tool is available

# Check mise sees the tool
mise ls

# Check the tool is on PATH
which node
node --version

# Compare with mise's view
mise which node

Conventions: Pins, Runtimes, and Local Overrides

Defaults to follow unless the repo you're in says otherwise. Rationale and history: dotfiles ADR 0067.

Pin exact versions

Prefer mise use --pin tool@x.y.z, which saves the resolved concrete version. "latest" and fuzzy versions can't be bumped by Renovate (nothing to compare against), and two machines can end up on different builds. If a pin is deliberate, say so in a comment beside it.

Renovate and mise

  • Renovate's mise manager reads mise.toml, .mise.toml and .config/mise/ by default. Config kept elsewhere (a dotfiles config/mise/, say) needs managerFilePatterns on the mise manager.
  • It understands github: and npm: backends and core tools like bun and go. It skips "latest", lts and stable.
  • mise strips the v from github: tags but Renovate writes the raw tag back. The github>technicalpickles/renovate-config:mise preset handles this. A hand-written rule needs "extractVersion": "^v?(?<version>.+)$" scoped with "matchDepNames": ["github:**"]; unscoped, it drops updates for core tools like go (see dev-tools:adopting-renovate).

Runtimes belong to the project

go, python, rust and ruby go in the project's own mise.toml, not the global config. Global config is for tools you run everywhere (CLIs, node for npm: tools).

Local overrides for clones without mise config

When you've cloned something with no mise config of its own, create mise.local.toml with the versions it needs (read them from go.mod, CI or .ruby-version), and keep it out of git:

# Per clone. In a bare-repo + worktrees layout the exclude lives in the common dir
echo mise.local.toml >> "$(git rev-parse --git-common-dir)/info/exclude"

Or ignore mise.local.toml and .mise.local.toml in the global gitignore once, and skip the per-clone step.

Don't read go.mod as a version source

idiomatic_version_file_enable_tools = ["go"] makes mise read the go directive in go.mod, but that is only a minimum version and mise removes the support in 2026.11.0. A toolchain goX.Y.Z line, .go-version or mise.toml still work.

npm: backend still needs node to run

The npm: backend installs without node, but the installed bin shims run whichever node is first on PATH. Keep a node on PATH wherever an npm: tool is used.

Troubleshooting "Command Not Found"

When a tool should be available but isn't found:

Diagnostic workflow

# 1. Check mise installation health
mise doctor

# 2. Check what tools mise knows about
mise ls                    # All installed tools
mise ls --current          # Tools for current directory

# 3. Compare which vs mise which
which node                 # What shell finds
mise which node            # What mise thinks it should be

# 4. Check if tool would work via mise exec
mise exec -- node --version  # If this works, it's an activation issue

Common causes and fixes

Shell activation not set up

Symptom: mise exec -- node works, but node doesn't

Diagnose:

mise doctor  # Look for activation warnings

Fix - add to shell rc file:

# For zsh (~/.zshrc)
eval "$(mise activate zsh)"

# For bash (~/.bashrc)
eval "$(mise activate bash)"

# For fish (~/.config/fish/config.fish)
mise activate fish | source

Then restart your shell or source the rc file.

Config file not trusted

Symptom: mise shows trust warning, tools not activated

Fix:

mise trust
Tool not installed for current directory

Symptom: mise ls shows tool globally but not in mise ls --current

Diagnose:

# Check what config file applies
mise config

# Check if there's a local config overriding global
cat mise.toml .mise.toml .tool-versions 2>/dev/null

Fix: Add the tool to the project config:

mise use node@20  # Adds to project config
Shims vs PATH activation confusion

Symptom: Tools work in terminal but not in IDE/scripts

See references/dev-tools/shims-html.md for detailed explanation.

Quick fix for non-interactive contexts:

# In ~/.zprofile or ~/.bash_profile (non-interactive)
eval "$(mise activate zsh --shims)"

# In ~/.zshrc or ~/.bashrc (interactive)
eval "$(mise activate zsh)"

When to use mise exec (legitimately)

mise exec is appropriate for:

  • One-off commands with specific versions: mise exec node@18 -- npm test
  • CI/CD scripts where activation isn't available
  • Testing a different version temporarily

mise exec is NOT a fix for:

  • Tools not being on PATH in your terminal (fix activation instead)
  • "It works with mise exec" as a permanent solution

Available References

Scope - Developer Environment Management

Scope is a DevEx tool that helps maintain consistent development environments through automated checks, error detection, and fixes.

Core Commands

scope doctor

Run automated environment checks and fixes.

scope doctor run                   # Run all checks
scope doctor run --only group-name # Run specific group
scope doctor run --fix=false       # Check only, no fixes
scope doctor run --no-cache        # Disable caching
scope doctor list                  # List available checks

scope analyze

Detect known errors in logs or command output.

scope analyze logs file.log                # Analyze log file
scope analyze command -- cmd args          # Analyze command output
scope analyze --extra-config path file.log # Use additional configs

scope report

Generate bug reports with automatic secret redaction.

scope report ./script.sh     # Run and report on script
scope report -- command args # Run and report on command

scope-intercept

Monitor script execution in real-time (used as shebang).

#!/usr/bin/env scope-intercept bash
# Script content here

Configuration Resources

All Scope configurations use Kubernetes-inspired YAML format:

apiVersion: scope.github.com/v1alpha
kind: <ResourceType>
metadata:
  name: unique-identifier
  description: Human-readable description
spec:
  # Resource-specific configuration

ScopeKnownError

Define error patterns and provide automated help/fixes for common issues.

Structure

apiVersion: scope.github.com/v1alpha
kind: ScopeKnownError
metadata:
  name: descriptive-error-name
  description: Brief description of what this error means
spec:
  pattern: 'regex pattern to match the error'
  help: |
    Clear explanation of the issue.

    Steps to resolve:
    1. First step
    2. Second step
    3. Where to get help if needed
  fix:
    prompt:
      text: User-friendly prompt asking permission
    commands:
      - first-fix-command
      - second-fix-command

Key Fields

  • pattern: Regex pattern using ripgrep syntax to match error text
  • help: Multi-line markdown explanation with resolution steps
  • fix (optional): Automated remediation configuration
    • commands: List of commands to run to fix the error (required)
    • helpText: Descriptive text shown if the fix fails (optional)
    • helpUrl: Documentation link for manual resolution (optional)
    • prompt: User approval before running fix (optional)
      • text: Question asking for user permission
      • extraContext: Additional context about what the fix does and why approval is needed

Note: When a fix is defined, it only runs when the error pattern is detected. The fix is optional - if not provided, only the help text is shown.

File Organization

Place files in categorized directories:

  • Location: {config-root}/known-errors/{category}/{error-name}.yaml
  • Common categories: docker/, ruby/, git/, github/, mysql/, postgres/, dns/, aws/
  • Include matching .txt file with example error for testing

Example

apiVersion: scope.github.com/v1alpha
kind: ScopeKnownError
metadata:
  name: gem-missing-file
  description: A gem source file is missing and fails to be loaded
spec:
  pattern: "/lib/ruby/.* `require': cannot load such file --.*/lib/ruby/gems/.*(LoadError)"
  help: |
    A gem source file is missing. The solution is to reinstall the gems:
    1. Run `bundle pristine`
  fix:
    commands:
      - bundle pristine
    helpText: |
      Bundle pristine failed. Try these steps:
      1. Check your bundle config: bundle config list
      2. Reinstall bundler: gem install bundler
      3. Contact #help-ruby if issues persist
    helpUrl: https://bundler.io/man/bundle-pristine.1.html
    prompt:
      text: |-
        This will reinstall all gems from your Gemfile.
        Do you wish to continue?
      extraContext: >-
        bundle pristine reinstalls gems without changing versions,
        which resolves missing file errors but preserves your lock file

Validation

Validate schema structure:

brew install sourcemeta/apps/jsonschema
jsonschema validate schema.json known-error.yaml

Test pattern matching:

scope analyze logs --extra-config config-dir/ test-error.txt

Additional Resources

Pattern Writing Tips

  • Use ripgrep regex syntax (similar to PCRE)
  • Escape special characters: \\., \\[, \\(
  • Use character classes: [[:digit:]], [[:alpha:]]
  • Test patterns: echo "error text" | rg "pattern"
  • Balance specificity vs flexibility to avoid false positives/negatives

ScopeDoctorGroup

Define environment setup and maintenance checks with automated fixes.

Structure

apiVersion: scope.github.com/v1alpha
kind: ScopeDoctorGroup
metadata:
  name: tool-name
  description: Brief description of what this group does
spec:
  include: when-required # or "by-default"
  needs:
    - dependency-1
    - dependency-2
  actions:
    - name: action-name
      description: What this action checks/fixes
      required: true # default true; false for optional checks
      check:
        paths:
          - 'file-to-watch.txt'
          - '**/*.config'
        commands:
          - ./bin/check-script.sh
      fix:
        commands:
          - ./bin/fix-script.sh
        helpText: |
          What to do if the fix fails.
          Where to get help.
        helpUrl: https://docs.example.com/help

Key Components

Include Modes
  • by-default: Always runs with scope doctor run
  • when-required: Only runs when explicitly specified or as dependency
Dependencies

List other groups that must run first in needs array. Creates execution graph.

Actions

Each action is an atomic check/fix operation that runs in order.

Check Logic

Determines if fix should run. Fix runs when:

  • No check defined: Fix always runs
  • paths specified: Any file changed or no files match globs
  • commands specified: Any command exits non-zero
  • Both can be combined (OR logic)
Fix Section
  • commands: List of commands to run in order
  • helpText: Shown if fix fails (markdown supported)
  • helpUrl: Optional link to documentation

File Organization

  • Application setup: {config-root}/application/
  • Environment setup: {config-root}/environment/
  • Project-specific: .scope/ in project root

Example

apiVersion: scope.github.com/v1alpha
kind: ScopeDoctorGroup
metadata:
  name: ruby-version
  description: Set up Ruby with correct version
spec:
  include: when-required
  needs:
    - ruby-manager
    - homebrew
  actions:
    - name: install
      description: Ensures correct version of ruby is installed
      check:
        paths:
          - '{{ working_dir }}/.ruby-version'
        commands:
          - ./bin/ruby-version.sh verify
      fix:
        commands:
          - ./bin/ruby-version.sh install
        helpText: |
          Ruby installation failed.
          Contact: #help-channel

Script Conventions

Create helper scripts following check/fix pattern:

#!/usr/bin/env bash
set -euo pipefail

ACTION="${1:-check}"

check() {
  # Return 0 if check passes, non-zero if fix needed
  if [[ condition ]]; then
    echo "Check passed"
    return 0
  else
    echo "Check failed" >&2
    return 1
  fi
}

fix() {
  # Perform fix, return 0 on success
  echo "Running fix..."
  # Fix commands here
  return 0
}

case "$ACTION" in
  check) check ;;
  fix) fix ;;
  *)
    echo "Usage: $0 [check|fix]" >&2
    exit 1
    ;;
esac

Script best practices:

  • Use relative paths with ./ prefix (relative to YAML file)
  • Make scripts idempotent (safe to run multiple times)
  • Exit 0 for success, non-zero for failure
  • Write errors to stderr
  • Include helpful error messages

Caching

File-based checks use content hashing:

  • Cache stores file path and content hash
  • Only re-runs if file contents change
  • Persists between runs
  • Disable with --no-cache

ScopeReportLocation

Configure where and how bug reports are uploaded.

GitHub Issues

apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: github
spec:
  destination:
    githubIssue:
      owner: org-name
      repo: repo-name
  additionalData:
    nodeVersion: node -v
    rubyPath: which ruby

Authentication via environment variables:

  • GitHub App: SCOPE_GH_APP_ID + SCOPE_GH_APP_KEY
  • Personal Access Token: SCOPE_GH_TOKEN

Local File System

apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: local
spec:
  destination:
    local:
      directory: /tmp/scope-reports
  additionalData:
    pwd: pwd
    username: id -un
    scopeVersion: scope version

RustyPaste

apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: rustypaste
spec:
  destination:
    rustyPaste:
      url: http://localhost:8000

Additional Data

Capture environment context with arbitrary commands:

additionalData:
  diskSpace: df -h
  gitBranch: git branch --show-current
  envVars: env | sort

Commands execute at report generation time. Scope automatically redacts secrets.

Common Patterns

Version checks, file-exists checks, service health, dependency installs, and path-triggered auto-run each have a ready YAML snippet in references/quick-reference.md ("Common Patterns"). An orchestration group is a ScopeDoctorGroup whose needs: lists other groups and whose actions: is empty.

Workflow: Creating a Known Error

A known error is a YAML definition plus a .txt file of real error output, side by side under {config-root}/known-errors/{category}/. It's done when scope analyze logs --extra-config {config-root} <the .txt> matches the sample and jsonschema validate schema.json <the .yaml> passes.

Workflow: Creating a Doctor Group

A doctor group is a YAML file in {config-root}/application/, {config-root}/environment/, or .scope/ (project-specific), plus any helper scripts under .scope/bin/, referenced by relative path and executable. Add it to its parent group's needs if it's a new dependency. It's done when scope doctor list shows it and scope doctor run --only <name> passes with and without --no-cache.

Debugging

See "Debugging Checklist" in references/quick-reference.md. The usual causes: a regex that needs escaping (test with rg "pattern" file), paths globs that match nothing, check commands that don't exit 0 on success, stale cache (--no-cache), non-executable scripts, script paths not relative to the YAML (./ prefix), and needs naming a missing group (scope doctor list shows order).

Security Features

Automatic Redaction

Scope automatically redacts sensitive information:

  • GitHub API tokens
  • AWS credentials
  • SSH keys
  • Environment variable values containing secrets
  • Uses patterns from ripsecrets

This makes it safe to capture full environment in reports and share debug output publicly.

Reference

Configuration Structure

config-repository/
├── {config-root}/
│   ├── application/          # App-level (ruby, node, postgres)
│   ├── environment/          # System-level (homebrew, docker, github)
│   ├── known-errors/         # Error definitions by category
│   │   ├── docker/
│   │   ├── ruby/
│   │   ├── git/
│   │   └── ...
│   └── reports/              # Report locations

Additional Resources

See references directory for:

  • quick-reference.md - Command cheat sheet and pattern examples
  • real-world-examples.md - Production-tested configurations
  • testing-guide.md - Comprehensive validation workflows

Commands 2

Transcript Cleanup

Clean up the transcript for readability and accuracy. Supports both SRT subtitle files and plaintext transcripts.

Step 1: Read and Detect Format

Read the transcript file provided as $1.

Detect format:

  • SRT format: Has numbered entries with timestamps like 00:01:23,456 --> 00:01:25,789
  • Plaintext: Raw text without timestamps

For SRT files, strip the entry numbers, timestamps, and blank lines to extract the raw text. Note approximate time ranges for major topic shifts if helpful for the user.

Step 2: Identify High-Level Structure

Analyze the content and identify:

  1. Major topics/sections - What distinct subjects are discussed?
  2. Approximate flow - How does the conversation progress?
  3. Number of speakers - Is this a monologue or conversation?

Present this structure to the user for confirmation before proceeding.

Step 3: Identify Transcription Errors (Iterative)

Scan for likely transcription errors. Common patterns include:

Proper Nouns

  • Tool names (often mangled: "get hub" → GitHub, "chat GBT" → ChatGPT)
  • Company/product names
  • People's names
  • Technical terms and acronyms

Commands and Code

  • CLI commands (often split or garbled)
  • File paths
  • Code snippets mentioned verbally

Domain Terminology

  • Industry-specific terms
  • Project-specific vocabulary
  • Abbreviations

For each category of errors found:

  1. Present the suspected errors with surrounding context
  2. Ask the user to confirm corrections
  3. Note any additional context they provide
  4. Proceed to the next category

If context files were provided ($2, $3, etc.), read them to help resolve ambiguities. Context files might include:

  • Session logs (JSONL files from Claude sessions)
  • Related documentation
  • Glossaries or term lists

Step 4: Clarify Speaker Attribution

If multiple speakers are detected:

  1. Ask how many speakers there are
  2. Ask for their names/identifiers
  3. Present ambiguous exchanges and ask for attribution

Work through this iteratively—don't try to attribute everything at once.

Step 5: Produce Cleaned Transcript

Only after all clarifications are resolved, write the cleaned transcript.

Output format:

# [Title from filename or user]

[Optional: Brief description of what this is]

---

## [Section 1 Title]

**Speaker:** [content]

**Other Speaker:** [content]

---

## [Section 2 Title]

...

---

*End of transcript*

Formatting rules:

  • Section headers (##) for major topic changes
  • **Speaker:** prefix for speaker attribution (if multiple speakers)
  • Horizontal rules (---) between major sections
  • Backticks for commands, file paths, and code
  • Preserve meaning—only fix errors and improve readability
  • Keep some natural speech patterns; don't over-sanitize
  • Remove excessive filler words but keep the conversational tone

Output location: Write to the same directory as the source file:

  • If source is foo.srt → write foo - Transcript.md
  • If source is foo.txt → write foo - Transcript.md

Guidelines

  • Ask, don't guess: When uncertain about a correction, ask the user
  • Preserve meaning: Never add content that wasn't said
  • Iterative clarification: Work through one category of questions at a time
  • Context is key: Use provided context files to resolve ambiguities before asking
  • Speaker attribution: If you can't confidently attribute a statement, ask

Reflect on This Conversation

Help capture a retrospective of this conversation. You'll analyze what happened, ask the user a few questions, then generate a structured reflection document.

Step 1: Analyze the Conversation

Review the conversation so far and identify:

Failed Attempts

What was tried and didn't work? How was each failure resolved?

  • Look for error messages, retries, or approaches that were abandoned
  • Note what the resolution was (user correction, different approach, etc.)

Corrections Made

Where did the user provide feedback that changed direction?

  • Explicit corrections ("no, do it this way")
  • Redirections ("let's try something else")
  • Clarifications that revealed a misunderstanding

Skills Activated

Which skills were invoked during this conversation?

  • Look for Skill() tool calls
  • Look for announcements like "I'm using the X skill"
  • Note the skill names

Key Decisions

What significant choices were made about approach, tools, or architecture?

  • Why was each decision made?
  • Were alternatives considered?

Hook Interventions

Were any tool calls blocked or redirected by hooks?

  • What was blocked?
  • What was the workaround?

@reflect Notes

Scan user messages for @reflect tags — these are observations the user wanted captured.

  • Collect all @reflect <note> entries
  • These are proactive observations, not corrections

Step 2: Ask the User

Ask these questions to get the user's perspective. Use the AskUserQuestion tool with all questions at once:

Q1 - Outcome: "Did we accomplish what you set out to do?"

  • Options: Fully complete / Partially complete / Blocked / Abandoned

Q2 - Approach: "How did the approach feel? Any decisions that seemed off?"

  • Open-ended text

Q3 - Skills: (Only if skills were used) "Did any skills help or get in the way?"

  • Options: Helped / Got in the way / Mixed / No opinion

Q4 - Friction: "Where did you have to intervene or correct course?"

  • Open-ended text

Step 3: Generate the Retrospective

Create a markdown document with this structure:

# Reflection: [Brief Topic Description]

**Date:** YYYY-MM-DD
**Outcome:** [User's answer to Q1]
**Skills Used:** [comma-separated list, or "None"]

## Summary

[2-3 sentences: what was the task, what happened, what was learned]

## What Happened

### Key Decisions
- [Decision 1 and reasoning]
- [Decision 2 and reasoning]

### Failed Attempts
- [What failed] → [How it was resolved]

### Corrections Made
- [User correction] → [Impact on direction]

## Notes Captured

[List any @reflect observations from during the session. Omit this section if none.]

## User Feedback

**Approach:** [User's answer to Q2]

**Skills:** [User's answer to Q3, if applicable]

**Friction points:** [User's answer to Q4]

## Lessons Learned

### For Agent Workflows
- [Lesson 1]
- [Lesson 2]

### For Skills
- [Any gaps identified or improvements needed. Omit if no skills were used or no lessons apply.]

## Action Items

- [ ] [Concrete follow-up if any. Omit section if none.]

Step 4: Save the Document

  1. Determine a brief topic slug from the conversation (e.g., "tool-routing-multiline", "auth-refactor")
  2. Create the directory if needed: docs/retrospectives/
  3. Save to: docs/retrospectives/YYYY-MM-DD-<topic>.md
  4. Tell the user where it was saved

Guidelines

  • Keep the summary concise (2-3 sentences)
  • Be specific about what failed and why
  • Capture the user's perspective accurately
  • If sections have no content (no failed attempts, no corrections), you can note "None" or omit subsections
  • The retrospective should be useful for future reference, not exhaustive documentation

Sponsors

Details

Marketplace
technicalpickles/pickled-claude-plugins
Source
plugins/dev-tools
Category
Community

More from technicalpickles/pickled-claude-plugins

All 26