gh-technicalpickles-pickled-claude-plugins-plugins-debugging-tools/skills/scope/references/quick-reference.md

Scope Quick Reference

Condensed reference for common Scope operations and patterns.

Command Cheat Sheet

# Doctor
scope doctor run                   # Run all checks
scope doctor run --only group-name # Run specific group
scope doctor run --fix=false       # Check only
scope doctor run --no-cache        # Force re-check
scope doctor list                  # List all checks

# Analyze
scope analyze logs file.log            # Check log for errors
scope analyze command -- cmd args      # Check command output
scope analyze --extra-config dir/ file # Use extra configs

# Report
scope report ./script.sh     # Run & report script
scope report -- command args # Run & report command

# Version
scope version # Show version

YAML Templates

Known Error Template

apiVersion: scope.github.com/v1alpha
kind: ScopeKnownError
metadata:
  name: error-name
  description: What this error means
spec:
  pattern: 'regex pattern'
  help: |
    Explanation and steps to fix:
    1. First step
    2. Second step
  fix:
    prompt:
      text: Permission prompt
    commands:
      - fix-command

Doctor Group Template

apiVersion: scope.github.com/v1alpha
kind: ScopeDoctorGroup
metadata:
  name: group-name
  description: What this group does
spec:
  include: when-required
  needs:
    - dependency-1
  actions:
    - name: action-name
      description: What this checks
      required: true
      check:
        paths:
          - 'file.txt'
        commands:
          - ./bin/check.sh
      fix:
        commands:
          - ./bin/fix.sh
        helpText: |
          Help if fix fails

Report Location Template

apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: location-name
spec:
  destination:
    local:
      directory: /tmp/reports
    # OR githubIssue:
    #   owner: org
    #   repo: repo
    # OR rustyPaste:
    #   url: http://localhost:8000
  additionalData:
    command1: command-to-run

Regex Pattern Examples

# Match specific version error
pattern: "ruby [0-9]+\\.[0-9]+\\.[0-9]+ is not installed"

# Match file not found
pattern: "cannot load such file -- .*/([^/]+)\\.(rb|so)"

# Match Docker daemon not running
pattern: "\\.colima/[^/]+/docker\\.sock.*Is the docker daemon running\\?"

# Match Git lock error
pattern: "Unable to create '.*\\.git/refs/heads/.*\\.lock'"

# Match DNS resolution failure
pattern: "Could not resolve host: ([a-zA-Z0-9.-]+)"

# Match permission denied
pattern: "Permission denied.*(/[^:]+)"

# Character classes
[[:digit:]]   # 0-9
[[:alpha:]]   # a-z, A-Z
[[:alnum:]]   # alphanumeric
[[:space:]]   # whitespace

# Quantifiers
*             # 0 or more
+             # 1 or more
?             # 0 or 1
{n,m}         # between n and m

# Escaping
\\.           # literal dot
\\[           # literal [
\\(           # literal (

Check/Fix Script Template

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

ACTION="${1:-check}"

check() {
  # Exit 0 if OK, non-zero if needs fix
  if [[ condition ]]; then
    return 0
  else
    echo "Check failed: reason" >&2
    return 1
  fi
}

fix() {
  # Perform fix, exit 0 on success
  echo "Fixing..."
  # commands
  return 0
}

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

Common Patterns

Version Check

- name: min-version
  description: Check minimum version
  check:
    commands:
      - test "$(tool --version | cut -d' ' -f2)" = "1.2.3"
  fix:
    helpText: Update tool via Managed Software Center

File Exists

- name: config-exists
  description: Config file exists
  check:
    commands:
      - test -f .config
  fix:
    commands:
      - ./bin/create-config.sh

Service Running

- name: service-up
  description: Service is running
  check:
    commands:
      - pgrep -x service-name
  fix:
    commands:
      - brew services restart service-name

Dependencies Installed

- name: deps
  description: Dependencies installed
  check:
    paths:
      - package.json
      - yarn.lock
  fix:
    commands:
      - yarn install

Path-Based Auto-Run

# Runs fix when file changes
- name: auto-update
  check:
    paths:
      - config.yaml
      - '**/*.conf'
  fix:
    commands:
      - ./bin/reload.sh

Validation Workflow

# 1. Create error file
mkdir -p {config-root}/known-errors/category
cat > {config-root}/known-errors/category/error.yaml << 'EOF'
apiVersion: scope.github.com/v1alpha
kind: ScopeKnownError
metadata:
  name: my-error
spec:
  pattern: "error pattern"
  help: How to fix
EOF

# 2. Create test file with actual error
cat > {config-root}/known-errors/category/error.txt << 'EOF'
Actual error output goes here
EOF

# 3. Test pattern
scope analyze logs \
  --extra-config {config-root} \
  {config-root}/known-errors/category/error.txt

# 4. Validate schema (if available)
jsonschema validate schema.json error.yaml

File Organization

# Gusto shared configs
{config-root}/
├── application/              # App-level (ruby, node, db)
├── environment/              # System-level (homebrew, git)
├── known-errors/
│   ├── docker/
│   ├── ruby/
│   ├── git/
│   └── {category}/
│       ├── error-name.yaml
│       └── error-name.txt   # Test file
└── reports/

# Project-specific
.scope/
├── project-name.yaml         # Main orchestrator
├── db.yaml                  # Database setup
├── ruby.yaml                # Language setup
└── bin/                     # Helper scripts
    ├── check-*.sh
    └── fix-*.sh

Debugging Checklist

Known Error Not Matching

• Test regex: echo "error" | rg "pattern"
• Check escaping of special chars
• Verify test file has actual error
• Try broader pattern first

Doctor Always Runs

• Check path globs match: ls -la path/pattern
• Verify check command exits 0: ./bin/check.sh; echo $?
• Try --no-cache
• Check script is executable: ls -l script.sh

Dependencies Not Working

• Run scope doctor list - see order
• Verify needs names match exactly
• Check for circular deps
• Test with --only group-name

Script Issues

• Add set -euo pipefail to scripts
• Check relative path has ./ prefix
• Make executable: chmod +x script.sh
• Test standalone: ./bin/script.sh check

Testing Tips

# Test regex patterns
echo "error text here" | rg "pattern"

# Test check command
./bin/check.sh check
echo "Exit code: $?"

# Test doctor group in isolation
scope doctor run --only group-name --no-cache

# See what would run
scope doctor list | grep group-name

# Test with extra config
scope analyze --extra-config /path/to/config file.log

# Validate YAML syntax
yamllint file.yaml

# Check file matching
ls -la path/to/files/**/*.pattern

Environment Variables

# Report authentication
SCOPE_GH_TOKEN=ghp_xxx        # GitHub PAT
SCOPE_GH_APP_ID=123           # GitHub App
SCOPE_GH_APP_KEY=/path/to/key # GitHub App key

# Template variables (in YAML)
{{ working_dir }} # Current working directory

Common Gotchas

1. Regex escaping: Use \\. for literal dot, not .
2. Relative paths: Must start with ./ (relative to YAML file)
3. Check exit codes: 0 = pass, non-zero = needs fix
4. Cache persistence: Use --no-cache when testing
5. Pattern specificity: Too broad = false positives, too narrow = misses errors
6. Script permissions: Must be executable (chmod +x)
7. YAML indentation: Use 2 spaces, not tabs
8. Action order: Actions run in order defined
9. Dependency order: Use scope doctor list to verify
10. Help text: Use | for multi-line strings in YAML