- version
- 1.5.0
- GitHub stars
- 13
Install
/plugin install dev-tools@pickled-claude-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add technicalpickles/pickled-claude-plugins.
Contents
Discovered from sourceSkills 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:renovatein the global mise tools (mise exec npm:renovate -- renovate --version).mise install npm:renovateon the command line resolveslatestand ignores config options, so use plainmise install. ghauthenticated 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.
:lockfileis opt-in. The base preset does not refresh lockfiles. Add:lockfileonly 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(" ")'
| Files | Manager |
|---|---|
package.json, package-lock.json | npm |
Cargo.toml, Cargo.lock | cargo |
go.mod | gomod |
pyproject.toml, uv.lock | pep621 / uv |
Gemfile, *.gemspec | bundler |
mise.toml, .mise.toml | mise |
Dockerfile, .devcontainer/ | dockerfile |
.github/workflows/*.y*ml | github-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
gogotcha).
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.
ghcannot list installations (needs a GitHub App token); check the repo's access list in GitHub settings or the Mend portal. extractVersionon every mise tool drops updates. A rule that strips thevprefix must be scoped withmatchDepNames: ["github:**"]. Unscoped, it silently removedgoupdates. The:misepreset 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 exactpackage@versionviatrust_policy_excludeson 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.sumcomes 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
| Operation | Command |
|---|---|
| Start | colima start or colima start <profile> |
| Start with SSH agent | colima start <profile> -s |
| Stop | colima stop or colima stop --force |
| Status | colima status -p <profile> |
| List profiles | colima list |
| SSH into VM | colima ssh or colima ssh -- <cmd> |
| SSH with chained commands | colima ssh -- bash -c "cmd1 && cmd2" |
| Get socket path | colima status -p <profile> --json | jq -r .docker_socket |
Docker Context Basics
Colima creates Docker contexts per profile:
- Profile
default→ contextcolima - Profile
work→ contextcolima-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?
colima status- is it running?docker context list- right context selected?- See
references/troubleshooting.mdfor 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, escapingreferences/docker-contexts.md- Context switching, DOCKER_HOST, socket pathsreferences/profile-management.md- Creating, configuring, deleting profilesreferences/troubleshooting.md- Common issues and solutionsreferences/common-options.md- Flags, VM types, resource configurationreferences/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 usagereferences/colima-upstream/FAQ.md- Official FAQ and troubleshootingreferences/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 On | Read This |
|---|---|
| New CLI under time pressure | practical-patterns.md (Priority Checklist) |
| Adding to existing CLI | practical-patterns.md (Working with Existing CLIs) |
| Fixing "confusing" CLI | practical-patterns.md (CLI UX Audit Checklist) |
| Command structure, flags | ux-principles.md (Familiarity, Discoverability) |
| Output formatting | visual-techniques.md (Layout, Spacing, Color) |
| Error messages, help text | practical-patterns.md (Error Message Patterns) |
| Overall architecture | ux-principles.md (complete overview) |
The Six UX Principles
- Familiarity - Use known conventions (--help, --version, verb-noun)
- Discoverability - Guide users (help text, prompts, examples)
- Feedback - Show what's happening (progress, confirmations, state)
- Clarity - Structure output (spacing, alignment, hierarchy)
- Flow - Minimize friction (shortcuts, defaults, scriptability)
- Forgiveness - Handle errors gracefully (clear messages, suggestions, safety)
See ux-principles.md for detailed guidance and examples.
The Five Visual Techniques
- Color - Semantic meaning (green=success, red=error, yellow=warning)
- Spacing - Visual grouping (blank lines, indentation, alignment)
- Layout - Structured regions (panels, blocks, persistent areas)
- Symbols - Fast signifiers (✓ ✗ ⚠ →, checkboxes, progress indicators)
- 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):
- --help flag (2 minutes) - Include usage, examples, common flags
- Exit codes (1 minute) - 0=success, 1=error, enables CI/CD
- Clear errors (5 minutes) - What happened + what's valid + how to fix
- 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 explorationreferences/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
| Rationalization | Reality |
|---|---|
| "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 scanningreferences/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
- Verify: API signature matches your use case
- Adapt: Use the pattern for your specific need
- Test: Try the verified approach
- 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:
| File | Hook Manager |
|---|---|
hk.pkl | hk |
lefthook.yml | lefthook |
.husky/ directory | husky |
.pre-commit-config.yaml | pre-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:
- 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 ascratch-areas/dir next to the repo. - 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.scratchsymlink, and a README from the template. Skip--save-to-claude-mdwhen~/.claude/CLAUDE.mdis generated from dotfiles; add the line to its source instead. - Make sure
.scratchis 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 aREADME.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-filechmod), 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 .orgit 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
- Add tools with
mise use, not by editing config by hand: it checks the tool exists, installs it, and writes valid syntax. - Use the config file the project already has; don't create a second one.
- Fix the shell when tools aren't on PATH: diagnose activation instead of making
mise execthe 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:
- Does this project's README/docs specify a version? → mise
- Could different team members need different versions? → mise
- Does the tool have breaking changes between versions? → mise
- 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.tomlor.mise.toml- standard mise configmise.local.tomlor.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.tomland.config/mise/by default. Config kept elsewhere (a dotfilesconfig/mise/, say) needsmanagerFilePatternson themisemanager. - It understands
github:andnpm:backends and core tools likebunandgo. It skips"latest",ltsandstable. - mise strips the
vfromgithub:tags but Renovate writes the raw tag back. Thegithub>technicalpickles/renovate-config:misepreset handles this. A hand-written rule needs"extractVersion": "^v?(?<version>.+)$"scoped with"matchDepNames": ["github:**"]; unscoped, it drops updates for core tools likego(seedev-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
- references/cli/use-html.md - Full
mise usedocumentation - references/cli/doctor-html.md - Diagnostic commands
- references/cli/activate-html.md - Shell activation
- references/cli/which-html.md - Path resolution
- references/dev-tools/shims-html.md - Shims vs PATH activation
- references/guides/getting-started.md - Setup guide
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
.txtfile 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 examplesreal-world-examples.md- Production-tested configurationstesting-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:
- Major topics/sections - What distinct subjects are discussed?
- Approximate flow - How does the conversation progress?
- 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:
- Present the suspected errors with surrounding context
- Ask the user to confirm corrections
- Note any additional context they provide
- 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:
- Ask how many speakers there are
- Ask for their names/identifiers
- 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→ writefoo - Transcript.md - If source is
foo.txt→ writefoo - 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
- Determine a brief topic slug from the conversation (e.g., "tool-routing-multiline", "auth-refactor")
- Create the directory if needed:
docs/retrospectives/ - Save to:
docs/retrospectives/YYYY-MM-DD-<topic>.md - 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- gitv3.6.0
- github-actionsv0.1.1
- hkv0.2.0
- inflight-artifactv0.5.0
- mcpproxyv1.0.2
- petri-dishv0.1.0
- pickle-modev0.3.0
- sandbox-advisorv0.3.0
- second-brainv2.2.0
- stay-on-targetv1.0.1
- stay-principledv0.1.1
- tailscalev0.5.0
- taskwarriorv1.4.0
- tool-routingv1.4.0
- wait-for-itv0.2.2
- woodpeckerv0.4.0
- working-in-monoreposv1.0.4
- writing-toolsv0.3.0
- actually-lspv0.7.1
- agent-metav3.4.1
- automic-vaultv0.3.0
- buildkitev1.1.4
- ci-cd-toolsv1.2.2
- come-onv0.2.1
