Shell Script Review

Audit shell scripts for correctness, safety, and portability.

Verification

After review, run shellcheck <script> to verify fixes address identified issues.

Testing

Run pytest plugins/pensive/tests/skills/test_shell_review.py -v to validate review patterns.

Quick Start

/shell-review path/to/script.sh

When To Use

CI/CD pipeline scripts
Git hook scripts
Wrapper scripts (run-*.sh)
Build automation scripts
Pre-commit hook implementations

When NOT To Use

Non-shell scripts (Python, JS, etc.)
One-liner commands that don't need review

Required TodoWrite Items

shell-review:context-mapped
shell-review:exit-codes-checked
shell-review:portability-checked
shell-review:safety-patterns-verified
shell-review:structure-checked
shell-review:evidence-logged

Workflow

Step 1: Map Context (`shell-review:context-mapped`)

Identify shell scripts:

# Find shell scripts
find . -not -path "*/.venv/*" -not -path "*/__pycache__/*" \
  -not -path "*/node_modules/*" -not -path "*/.git/*" \
  -name "*.sh" -type f | head -20
# Check shebangs
rg -l "^#!/" scripts/ hooks/ 2>/dev/null | head -10
# fallback: grep -l "^#!/" scripts/ hooks/ 2>/dev/null | head -10

Document:

Script purpose and trigger context
Integration points (make, pre-commit, CI)
Expected inputs and outputs

Step 2: Exit Code Audit (`shell-review:exit-codes-checked`)

@include modules/exit-codes.md

Step 3: Portability Check (`shell-review:portability-checked`)

@include modules/portability.md

Step 4: Safety Patterns (`shell-review:safety-patterns-verified`)

@include modules/safety-patterns.md

Step 5: Structure Patterns (`shell-review:structure-checked`)

@include modules/structure-patterns.md

Step 6: Evidence Log (`shell-review:evidence-logged`)

Use imbue:proof-of-work to record findings with file:line references.

Summarize:

Critical issues (failures masked, security risks)
Major issues (portability, maintainability)
Minor issues (style, documentation)

Output Format

## Summary
Shell script review findings

## Scripts Reviewed
- [list with line counts]

## Exit Code Issues
### [E1] Pipeline masks failure
- Location: script.sh:42
- Pattern: `cmd | grep` loses exit code
- Fix: Use pipefail or capture separately

## Portability Issues
[cross-platform concerns]

## Safety Issues
[unquoted variables, missing set flags]

## Recommendation
Approve / Approve with actions / Block

Exit Criteria

Exit code propagation verified (pipelines checked for pipefail or capture-and-check)
Portability issues documented (Bash-isms in #!/bin/sh scripts flagged)
Safety patterns verified (no echo, braced vars, :? expansion, cd in subshells, no basename/dirname)
Structure patterns verified (library/executable distinction, main call, preamble, depcheck, shfmt formatting)
Evidence logged with file:line references via imbue:proof-of-work

Table of Contents