Shell Script Refactor Analysis

Analyze Bash/Shell scripts against security best practices, ShellCheck standards, and enterprise shell scripting guidelines. Generate a comprehensive refactoring report with prioritized recommendations.

Parallel Agent Integration

This command ALWAYS uses parallel agents (security-critical). Executes: ~/.claude/scripts/parallel_agent.sh --json --full-output --validate

Consensus scoring:

•≥80%: Auto-proceed with unified recommendation
•50-79%: Highlight disagreements to user
•<50%: Escalate for human review

Task

You are a Senior DevOps/Infrastructure Engineer analyzing production shell scripts. Your goals are to:

•Run ShellCheck analysis for security and quality issues
•Identify security vulnerabilities (command injection, unquoted variables, dangerous commands)
•Find code quality and maintainability issues
•Rate each finding by effort (Minimal/Medium/High) and risk (Low/Medium/High/Critical)
•Generate an actionable improvement roadmap with priority matrix
•Check for proper error handling and logging

Instructions

Step 0: Consult Knowledge Base

Before starting analysis, check for known patterns relevant to this codebase:

bash

~/.claude/scripts/learning_capture.sh query --language bash --format llm

If the knowledge base contains relevant antipatterns or insights for Bash/Shell:

•Include them as additional check items in your analysis
•Flag any occurrences of known antipatterns with their KB ID (e.g., ANTI-001)
•Note if a known antipattern has been resolved

This step is non-blocking — if the knowledge base is empty or the query fails, proceed with the standard analysis.

Step 1: Identify Shell Scripts

Find all shell scripts in the repository:

bash

find . -name "*.sh" -type f
find . -type f -exec grep -l "^#!/bin/bash\|^#!/bin/sh" {} \;

Step 2: Run ShellCheck Analysis

For each script, run ShellCheck:

bash

shellcheck --severity=info script.sh

Key ShellCheck Codes to Prioritize:

Code	Severity	Issue
SC2086	Critical	Unquoted variable expansion (injection risk)
SC2046	Critical	Quote word splitting in `$(cmd)`
SC2162	High	Read without -r (backslash handling)
SC2164	High	`cd` without checking if it succeeded
SC2155	Medium	Declare and assign separately
SC2034	Low	Variable appears unused

Step 3: Security Pattern Analysis

Scan for dangerous patterns:

Command Injection Risks

bash

# Bad: Unquoted variables in commands
grep -rn 'eval' *.sh
grep -rn '\$(' *.sh | grep -v '"\$('  # Unquoted command substitution
grep -rn '\${[^}]*}' *.sh | grep -v '"\${'  # Unquoted variable expansion

Dangerous Commands

bash

grep -rn 'rm -rf' *.sh
grep -rn 'curl.*|.*bash' *.sh
grep -rn 'wget.*|.*sh' *.sh
grep -rn '^[[:space:]]*eval ' *.sh

Insufficient Error Handling

bash

grep -rn '^[[:space:]]*cd ' *.sh | grep -v '&&\|||'  # cd without error check
grep -n 'set -e' *.sh  # Check if scripts fail on error

Step 4: Code Quality Analysis

Long Functions

bash

# Functions longer than 50 lines
awk '/^[a-zA-Z_][a-zA-Z0-9_]*\(\)/ {start=NR; fname=$1} /^}/ && start {len=NR-start; if(len>50) print FILENAME":"start" "fname" ("len" lines)"}' script.sh

Global Variables

bash

# Find all global variables (SCREAMING_SNAKE_CASE)
grep -n '^[A-Z_][A-Z0-9_]*=' script.sh

Magic Values

bash

# Hardcoded paths, IPs, URLs
grep -nE '/(usr|etc|var|tmp|home)/[^"]*[^[:space:]]' script.sh
grep -nE '[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}' script.sh
grep -nE 'https?://[^"[:space:]]+' script.sh

Step 5: Documentation Analysis

Check for:

•Shebang line (#!/bin/bash)
•Script-level comments explaining purpose
•Function documentation
•Usage/help function
•Example invocations

Step 6: Best Practices

Recommended Patterns

bash

# Should use:
set -euo pipefail  # Fail on errors, undefined vars, pipe failures
readonly VAR="value"  # Immutable variables
local var="value"  # Function-scoped variables
[[ ... ]]  # Modern test syntax instead of [ ... ]
"${var}"  # Always quote variables

Effort Classification

Level	Time	Scope	Examples
Minimal	<30 min	Single-line fixes	Quote variable, add `readonly`, fix shebang
Medium	1-4 hours	Function refactor	Add error handling, break up long function
High	1-2 days	Architectural	Rewrite with proper structure, add tests

Risk Classification

Level	Impact	Testing Required	Examples
Low	No behavior change	None	Add comments, rename variables
Medium	Internal changes	Manual testing	Add error checks, refactor helpers
High	Logic changes	Integration tests	Fix command injection, change flow
Critical	Security/Breaking	Full regression	Fix injection, remove dangerous commands

Output Format