Table of Contents

• Quick Start

• When to Use

• Required TodoWrite Items

• Workflow

• Output Format

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:evidence-logged

Workflow

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

Identify shell scripts:

Find shell scripts

find . -name "*.sh" -type f | head -20

Check shebangs

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: 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

• Portability issues documented

• Safety patterns checked

• Evidence logged