shell-review

Files (3)

• SKILL.md
• README.md · references/
• review.sh · scripts/

SKILL.md (first lines)

# Shell Script Review — Hermes Skill

A structured review workflow for any Bash / sh / zsh script. Encodes the methodology
in `/Users/lex/git/knowledge/develop/shell-review/` as a single Hermes skill so an
AI agent can produce a complete, severity-tagged review on demand.

## Overview

`shellcheck` alone catches 30–50% of real Shell bugs. The remaining 50–70% are logic,
secret-handling, portability, and runtime-survival issues that no single tool catches.

This skill implements a **4-layer × 8-class** framework:

```
L1 SYNTAX   — Does it parse?            (bash -n)
L2 STATIC   — Does it smell right?       (shellcheck, shfmt, regex sweeps, diff)
L3 SEMANTIC — Does it do what it claims? (logic / data-flow / secret / portability / AI)
L4 RUNTIME  — Does it survive a run?     (dry-run, trace, bats, sandbox)
```

The full reasoning for each class lives in `references/methodology.md` (the master doc).
This SKILL.md is the **executive entrypoint** — it tells the agent which commands to
run, when, and how to format the output.

## When to Use

Trigger this skill when the user:

- Asks to review, audit, or check a `.sh` / `.bash` / `.zsh` script
- Pastes a shell script and asks "is this OK?" / "any bugs?" / "ship it?"
- Asks for a PR review where the diff contains shell scripts
- Says "shell review" / "bash audit" / "lint my script" / "review this PR"
- Wants a structured findings list with blockers vs. suggestions

**Skip for:** non-shell PRs, docs-only changes, generated scripts (review the generator).

## Inputs the agent should collect before starting

If the user didn't provide these, ask once and wait:

1. **Target** — what to review:
   - Single file path: `scripts/setup.sh`
   - PR diff: `main...HEAD` against which repo?
   - Whole directory: `scripts/*.sh`
2. **Risk class** — which tier of review applies (defaults to "B — reusable infra"):
   - A — one-shot throwaway (5 min review)
   - B — reusable infra script (15 min review) ← default
   - C — teammate's PR (20 min review)
   - D — production-touching / destructive (full audit + 2nd reviewer)
3. **Diff base** if reviewing a PR (default: `git diff main...HEAD`)

If the user says "just review this" with no other context, default to **single file +
risk class B + bash dialect** and run all four layers.

## Workflow — what the agent actually does

### Step 1 — Pre-flight (5 sec)

```bash
# Auto-detect changed files if PR diff requested
git diff main...HEAD --name-only -- '*.sh' '*.bash' '*.zsh'
```

If the file list is empty, ask the user for the target path.

Print a one-line banner so the user sees the scope:
```
[shell-review] target=scripts/setup.sh  tier=B  dialect=bash
```

### Step 2 — Layer 1: SYNTAX (5 sec, mandatory)

```bash
for f in <changed_files>; do bash -n "$f"; done
```

- If any exit ≠ 0 → **FAIL FAST**, report the parse error as a `blocker` and stop.
  Don't run L2/L3/L4 on a script that doesn't parse.

### Step 3 — Layer 2: STATIC (15 sec, mandatory)

Run all four L2 classes in order. Each is a fast command:

**2.1 shellcheck** (the workhorse):
```bash
shellcheck -S warning -x <files>
```
If `-S warning` is clean, escalate to `-S info` for one more pass. Always add the
`disable=SC2016` false-positive escape hatch with a comment for grep patterns.

**2.2 shfmt format check**:
```bash
shfmt -d -i 2 -ci -ln bash <files>
```
Diff output = format violations. Don't fail the review on this; report as `suggestion`.

**2.4 secret / destructive sweep** (regex sweep, your platform's house rules):
```bash
git diff main...HEAD -- '*.sh' | grep -E '^\+' \
  | grep -iE 'password\s*=|secret\s*=|api[_-]?key\s*=|token\s*=|rm\s+(-r|-f)|--force|2>/dev/null'
```

**2.5 diff sweep** (added lines only):
```bash
git diff main...HEAD -- '*.sh' | grep -E '^\+' \
  | grep -iE 'TODO|FIXME|XXX|HACK|set -x|echo "DEBUG'
```

If `git diff` is not applicable (single-file review, no PR), fall back to scanning
the whole file with `grep -nE`.

### Step 4 — Layer 3: SEMANTIC (3–10 min, the human/AI layer)

This is where the agent uses its own reasoning. Read the script top to bottom and
apply each class:

- **3.1 Logic flow** — match against the gotcha table in `references/methodology.md` §3.1
  (`cmd && ok || warn`, `cd && rm -rf *`, `cat | grep`, `for f in $(ls)`, unquoted `$VAR`,
  missing `${VAR:-}` guards)

From aibangjuxin/knowledge, MIT.