@sandrinio/vbounce 1.0.0

package/skills/vibe-code-review/references/deep-audit.md

@@ -0,0 +1,259 @@
+# Deep Audit Mode
+
+A comprehensive analysis of the entire codebase. This takes longer but gives a complete picture of architectural health, coupling, duplication, and sustainability.
+
+## When to Use
+
+- Before a major release or launch
+- When the user suspects the codebase is getting "too complex to change"
+- Quarterly or monthly health assessments
+- Before hiring a new developer or onboarding someone
+- When feature velocity is noticeably declining
+
+## Steps
+
+### 1. Project Census
+
+Get a full picture of the codebase size and shape:
+
+```bash
+echo "=== Project Census ==="
+
+# Count files by type
+echo "--- Files by extension ---"
+find . -type f \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.next/*" \
+  -not -path "*/dist/*" \
+  -not -path "*/build/*" \
+  -not -path "*/__pycache__/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/coverage/*" \
+  | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20
+
+echo ""
+echo "--- Total lines of code ---"
+find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \
+  | grep -v node_modules | grep -v .next | grep -v dist | grep -v __pycache__ \
+  | xargs wc -l 2>/dev/null | tail -1
+
+echo ""
+echo "--- Directory structure (2 levels) ---"
+find . -maxdepth 2 -type d \
+  -not -path "*/node_modules/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/.next/*" \
+  | sort
+```
+
+### 2. Architectural Consistency Analysis
+
+This is the most important check. AI agents drift between patterns across sessions.
+
+```bash
+echo "=== Architectural Pattern Map ==="
+
+# Detect all patterns in use
+echo "--- State Management ---"
+grep -rl "createSlice\|configureStore\|createStore" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "Redux: {} files"
+grep -rl "zustand\|create(" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "Zustand: {} files"
+grep -rl "createContext\|useContext" --include="*.tsx" --include="*.jsx" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "Context API: {} files"
+grep -rl "makeAutoObservable\|makeObservable" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "MobX: {} files"
+grep -rl "@tanstack/react-query\|useQuery\|useMutation" --include="*.ts" --include="*.tsx" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "React Query: {} files"
+
+echo ""
+echo "--- API Patterns ---"
+grep -rl "fetch(" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "Raw fetch: {} files"
+grep -rl "axios" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "Axios: {} files"
+grep -rl "ky\b\|import.*from.*'ky'" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "Ky: {} files"
+
+echo ""
+echo "--- Component Patterns ---"
+grep -rl "class.*extends.*Component\|class.*extends.*React" --include="*.tsx" --include="*.jsx" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "Class components: {} files"
+grep -rl "export default function\|export const.*=.*(" --include="*.tsx" --include="*.jsx" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "Functional components: {} files"
+
+echo ""
+echo "--- Styling Patterns ---"
+find . -name "*.module.css" -o -name "*.module.scss" | grep -v node_modules | wc -l | xargs -I{} echo "CSS Modules: {} files"
+grep -rl "styled\." --include="*.ts" --include="*.tsx" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "Styled-components: {} files"
+grep -rl "className=\".*tailwind\|className={.*cn(" --include="*.tsx" --include="*.jsx" . 2>/dev/null | grep -v node_modules | wc -l | xargs -I{} echo "Tailwind: {} files"
+find . -name "*.css" -not -name "*.module.css" | grep -v node_modules | wc -l | xargs -I{} echo "Plain CSS: {} files"
+```
+
+**Analysis rule:** If multiple competing patterns exist for the same concern (e.g., Redux AND Zustand for state, or both class and functional components), flag as architectural inconsistency. One pattern should dominate (>80% usage).
+
+### 3. Full Duplication Analysis
+
+```bash
+# Install jscpd if needed
+npx jscpd --version 2>/dev/null || npm install -g jscpd
+
+# Run full-project duplication scan
+npx jscpd . \
+  --min-lines 5 \
+  --min-tokens 50 \
+  --reporters "console,json" \
+  --output /tmp/jscpd-report \
+  --ignore "node_modules,dist,build,.next,__pycache__,coverage,*.test.*,*.spec.*" \
+  2>/dev/null
+
+# Parse results if JSON available
+if [ -f /tmp/jscpd-report/jscpd-report.json ]; then
+  python3 -c "
+import json
+with open('/tmp/jscpd-report/jscpd-report.json') as f:
+    data = json.load(f)
+    total = data.get('statistics', {}).get('total', {})
+    print(f'Total duplicated lines: {total.get(\"duplicatedLines\", 0)}')
+    print(f'Duplication percentage: {total.get(\"percentage\", 0):.1f}%')
+    dupes = data.get('duplicates', [])
+    print(f'Duplicate blocks found: {len(dupes)}')
+    for d in dupes[:10]:
+        first = d['firstFile']
+        second = d['secondFile']
+        print(f'  {first[\"name\"]}:{first[\"startLoc\"][\"line\"]} ↔ {second[\"name\"]}:{second[\"startLoc\"][\"line\"]} ({d[\"lines\"]} lines)')
+"
+fi
+```
+
+**Thresholds:**
+- 🟢 Under 3%: Excellent
+- 🟡 3–8%: Normal, but watch it
+- 🔴 Over 8%: Significant duplication — AI is reinventing solutions
+
+### 4. Dependency Graph and Coupling
+
+```bash
+# For JavaScript/TypeScript
+npx dependency-cruiser --version 2>/dev/null || npm install -g dependency-cruiser
+
+# Generate dependency graph
+npx depcruise --include-only "^src" --output-type text src/ 2>/dev/null | head -100
+
+# Count circular dependencies
+echo "=== Circular Dependencies ==="
+npx depcruise --include-only "^src" --output-type err src/ 2>/dev/null | grep "circular" | head -20
+
+# Identify most-imported modules (coupling hotspots)
+echo ""
+echo "=== Most-imported modules (coupling hotspots) ==="
+grep -rh "from ['\"]" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" . \
+  | grep -v node_modules \
+  | sed "s/.*from ['\"]//;s/['\"].*//" \
+  | sort | uniq -c | sort -rn | head -20
+```
+
+**What to flag:**
+- Circular dependencies (always 🔴)
+- Any module imported by more than 30% of files (coupling hotspot)
+- God modules that import more than 15 other project modules
+
+### 5. Dead Code Detection
+
+```bash
+# JavaScript/TypeScript
+echo "=== Dead Code Analysis ==="
+npx knip --no-exit-code 2>/dev/null
+
+# If knip unavailable
+npx ts-unused-exports tsconfig.json 2>/dev/null
+
+# Count files not imported by anything
+echo ""
+echo "=== Potentially orphaned files ==="
+for file in $(find src -name "*.ts" -o -name "*.tsx" | grep -v test | grep -v spec | grep -v index); do
+  BASENAME=$(basename "$file" | sed 's/\.\(ts\|tsx\)$//')
+  REFS=$(grep -rl "$BASENAME" --include="*.ts" --include="*.tsx" src/ | grep -v "$file" | wc -l)
+  if [ "$REFS" -eq 0 ]; then
+    echo "  ⚠️  $file — not imported anywhere"
+  fi
+done
+```
+
+### 6. Error Handling Comprehensive Audit
+
+```bash
+echo "=== Error Handling Audit ==="
+
+echo "--- Empty catch blocks ---"
+grep -rn "catch" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" -A 2 . \
+  | grep -v node_modules \
+  | grep -E "catch.*\{$" -A 1 | grep "^\-\-$\|^\s*\}" | head -20
+
+echo ""
+echo "--- Console-only error handling ---"
+grep -rn "catch" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" -A 5 . \
+  | grep -v node_modules \
+  | grep -c "console\.\(log\|error\|warn\)"
+echo " instances of console-only error handling"
+
+echo ""
+echo "--- Missing try/catch around async operations ---"
+# Find await statements not inside try blocks (heuristic)
+grep -rn "await " --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" . \
+  | grep -v node_modules | grep -v test | grep -v spec | wc -l
+echo " total await statements"
+
+echo ""
+echo "--- Error boundaries (React) ---"
+grep -rl "ErrorBoundary\|componentDidCatch\|getDerivedStateFromError" --include="*.tsx" --include="*.jsx" . \
+  | grep -v node_modules | wc -l
+echo " error boundary implementations"
+
+echo ""
+echo "--- API error responses ---"
+grep -rn "res\.\(status\|json\)" --include="*.ts" --include="*.js" -B2 -A2 . \
+  | grep -v node_modules | grep -E "4[0-9]{2}|5[0-9]{2}" | head -10
+echo "(Checking for proper HTTP error status codes)"
+```
+
+### 7. Test Quality Assessment
+
+```bash
+echo "=== Test Quality Assessment ==="
+
+echo "--- Test file inventory ---"
+find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" \
+  | grep -v node_modules | grep -v __pycache__
+
+echo ""
+echo "--- Assertion patterns ---"
+# Check if tests have real assertions or just smoke tests
+grep -rn "expect\|assert\|should" --include="*.test.*" --include="*.spec.*" . \
+  | grep -v node_modules | wc -l
+echo " total assertions"
+
+# Check for weak assertions
+echo ""
+echo "--- Weak assertions (testing existence, not behavior) ---"
+grep -rn "toBeDefined\|toBeTruthy\|not\.toBeNull\|to\.exist" --include="*.test.*" --include="*.spec.*" . \
+  | grep -v node_modules | wc -l
+echo " weak assertions (only check that something exists)"
+
+# Check for snapshot tests (often low value in AI codebases)
+echo ""
+grep -rn "toMatchSnapshot\|toMatchInlineSnapshot" --include="*.test.*" --include="*.spec.*" . \
+  | grep -v node_modules | wc -l
+echo " snapshot tests (often brittle in AI-generated code)"
+```
+
+### 8. The "Explain It" Consistency Test
+
+This is unique to vibe-coded projects. Ask the AI to describe the architecture, then compare it against what the code actually shows.
+
+**Instructions for Claude:**
+1. Read the project's README, any architecture docs, and the top-level directory structure
+2. Write a plain-language architectural description based ONLY on the actual code structure
+3. Compare this against any existing documentation
+4. Flag contradictions — these mean the codebase has drifted from its intended design
+
+## Report Output
+
+Use `references/report-template.md` with the **Deep Audit** section. The report should be comprehensive enough to hand to a new team member or a code reviewer as a briefing document.
+
+Structure findings into:
+- **Architecture** — Pattern map, consistency score, coupling graph
+- **Code Health** — Duplication, dead code, file sizes
+- **Reliability** — Error handling, test quality
+- **Sustainability** — Dependency health, complexity trends
+- **Recommendations** — Prioritized action items with effort estimates

package/skills/vibe-code-review/references/pr-review.md

@@ -0,0 +1,234 @@
+# PR Review Mode
+
+Analyze only the changed files in a PR or git diff. This is the scalable daily-driver — it runs on every merge and catches problems before they enter the main branch.
+
+## When to Use
+
+- User wants to review a PR before merging
+- User has a set of changed files to evaluate
+- User asks "is this diff safe to merge?"
+- Continuous integration / pre-merge quality gate
+
+## Input
+
+The user should provide one of:
+- A branch name to compare against main/master
+- A commit range
+- A set of files to review
+
+If no input is given, default to:
+```bash
+git diff main...HEAD
+```
+
+## Steps
+
+### 1. Identify Changed Files
+
+```bash
+# Get list of changed files (excluding generated/config)
+CHANGED=$(git diff --name-only main...HEAD 2>/dev/null || git diff --name-only HEAD~1)
+echo "$CHANGED" | grep -v "package-lock.json\|yarn.lock\|.lock$\|node_modules\|dist/\|build/" 
+
+echo ""
+echo "=== Change Summary ==="
+echo "Files changed: $(echo "$CHANGED" | wc -l)"
+echo "Insertions/Deletions:"
+git diff --stat main...HEAD 2>/dev/null || git diff --stat HEAD~1
+```
+
+Flag if a PR touches more than 15 files across more than 5 directories — this is a coupling red flag.
+
+### 2. Complexity Delta
+
+For each changed file, measure complexity before and after:
+
+```bash
+# For JavaScript/TypeScript — install if needed
+npm list -g cr 2>/dev/null || npm install -g complexity-report
+
+# Analyze only changed source files
+for file in $(git diff --name-only main...HEAD | grep -E '\.(ts|tsx|js|jsx)$' | grep -v node_modules); do
+  if [ -f "$file" ]; then
+    echo "=== $file ==="
+    cr "$file" 2>/dev/null || npx cr "$file" 2>/dev/null || echo "  (complexity-report not available, skipping)"
+  fi
+done
+```
+
+Alternative approach if cr is not available — count nesting depth as a proxy for complexity:
+
+```bash
+for file in $(git diff --name-only main...HEAD | grep -E '\.(ts|tsx|js|jsx|py)$' | grep -v node_modules); do
+  if [ -f "$file" ]; then
+    MAX_INDENT=$(cat "$file" | sed 's/[^ \t].*//' | awk '{print length}' | sort -rn | head -1)
+    LINES=$(wc -l < "$file")
+    echo "$file — $LINES lines, max indent: $MAX_INDENT spaces"
+    if [ "$MAX_INDENT" -gt 20 ]; then
+      echo "  ⚠️  Deep nesting detected — likely complex logic"
+    fi
+  fi
+done
+```
+
+### 3. Duplication Check Against Existing Code
+
+This is the most important check for AI-generated code. The agent writing new code may not know what already exists.
+
+```bash
+# Install jscpd if not available
+npx jscpd --version 2>/dev/null || npm install -g jscpd
+
+# Run duplication detection focused on changed files
+# Create a temp file with changed file list
+git diff --name-only main...HEAD | grep -E '\.(ts|tsx|js|jsx|py)$' | grep -v node_modules > /tmp/changed_files.txt
+
+# Run jscpd on the whole project but focus report on matches involving changed files
+npx jscpd . \
+  --min-lines 5 \
+  --min-tokens 50 \
+  --reporters "console" \
+  --ignore "node_modules,dist,build,.next,__pycache__,coverage" \
+  2>/dev/null || echo "jscpd not available — manual duplication check needed"
+```
+
+If jscpd is not available, do a manual heuristic check:
+
+```bash
+# Find function names in changed files and check if they exist elsewhere
+for file in $(git diff --name-only main...HEAD | grep -E '\.(ts|tsx|js|jsx)$'); do
+  FUNCS=$(grep -oE '(function|const|let|var)\s+([a-zA-Z_][a-zA-Z0-9_]*)' "$file" | awk '{print $2}')
+  for func in $FUNCS; do
+    MATCHES=$(grep -rl "$func" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" . \
+      | grep -v node_modules | grep -v "$file" | head -3)
+    if [ -n "$MATCHES" ]; then
+      echo "⚠️  '$func' in $file also appears in:"
+      echo "   $MATCHES"
+    fi
+  done
+done
+```
+
+### 4. New Dependency Audit
+
+```bash
+# Check if package.json was modified
+if git diff --name-only main...HEAD | grep -q "package.json"; then
+  echo "=== New Dependencies ==="
+  # Show what was added to dependencies
+  git diff main...HEAD -- package.json | grep "^+" | grep -v "^+++" | grep -E '"[^"]+":' | head -20
+  
+  echo ""
+  echo "=== Dependency diff ==="
+  # Count before and after
+  BEFORE=$(git show main:package.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d.get('dependencies',{})))" 2>/dev/null || echo "?")
+  AFTER=$(cat package.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d.get('dependencies',{})))")
+  echo "Dependencies before: $BEFORE → after: $AFTER"
+fi
+
+# Same for Python
+if git diff --name-only main...HEAD | grep -q "requirements.txt"; then
+  echo "=== New Python Dependencies ==="
+  git diff main...HEAD -- requirements.txt | grep "^+" | grep -v "^+++"
+fi
+```
+
+For each new dependency, ask: Is this necessary? Does the project already have something that does the same thing?
+
+### 5. Error Handling Audit on Diff
+
+```bash
+echo "=== Error handling in changed code ==="
+
+# Get the actual diff content
+DIFF=$(git diff main...HEAD -- $(git diff --name-only main...HEAD | grep -E '\.(ts|tsx|js|jsx|py)$' | grep -v node_modules))
+
+# Check for empty catch blocks in new code
+echo "$DIFF" | grep "^+" | grep -E "catch.*\{" -A 2 | grep -E "^\+\s*\}" | head -10
+if [ $? -eq 0 ]; then
+  echo "🔴 Empty catch blocks found in new code"
+fi
+
+# Check for console.log-only error handling
+echo "$DIFF" | grep "^+" | grep -B1 -A3 "catch" | grep "console\.\(log\|error\)" | head -10
+if [ $? -eq 0 ]; then
+  echo "🟡 Console-only error handling in new code"
+fi
+
+# Check for TODO/FIXME in new code
+echo "$DIFF" | grep "^+" | grep -i "TODO\|FIXME\|HACK\|XXX" | head -10
+if [ $? -eq 0 ]; then
+  echo "🟡 TODO/FIXME markers in new code — unfinished work"
+fi
+
+# Check for missing null/undefined checks on new function params
+echo "$DIFF" | grep "^+" | grep -E "function|=>\s*\{" | head -10
+echo "(Review above functions for parameter validation)"
+```
+
+### 6. Test Coverage for Changed Files
+
+```bash
+echo "=== Test coverage for changed files ==="
+
+for file in $(git diff --name-only main...HEAD | grep -E '\.(ts|tsx|js|jsx)$' | grep -v node_modules | grep -v test | grep -v spec); do
+  BASENAME=$(basename "$file" | sed 's/\.\(ts\|tsx\|js\|jsx\)$//')
+  TEST_EXISTS=$(find . -name "${BASENAME}.test.*" -o -name "${BASENAME}.spec.*" | grep -v node_modules | head -1)
+  
+  if [ -n "$TEST_EXISTS" ]; then
+    # Check if test file was also updated
+    if echo "$CHANGED" | grep -q "$TEST_EXISTS"; then
+      echo "🟢 $file — test exists AND was updated"
+    else
+      echo "🟡 $file — test exists but was NOT updated with this change"
+    fi
+  else
+    echo "🔴 $file — no corresponding test file found"
+  fi
+done
+```
+
+### 7. Coupling Analysis
+
+```bash
+echo "=== Cross-module impact ==="
+
+# Count how many different directories the PR touches
+DIRS=$(git diff --name-only main...HEAD | grep -v node_modules | xargs -I{} dirname {} | sort -u)
+DIR_COUNT=$(echo "$DIRS" | wc -l)
+echo "Directories touched: $DIR_COUNT"
+echo "$DIRS"
+
+if [ "$DIR_COUNT" -gt 5 ]; then
+  echo "🔴 High cross-module impact — this PR reaches across $DIR_COUNT directories"
+  echo "   Consider breaking into smaller, focused PRs"
+elif [ "$DIR_COUNT" -gt 3 ]; then
+  echo "🟡 Moderate cross-module impact"
+else
+  echo "🟢 Focused change"
+fi
+
+echo ""
+echo "=== Import analysis on changed files ==="
+# Show what each changed file imports
+for file in $(git diff --name-only main...HEAD | grep -E '\.(ts|tsx|js|jsx)$' | grep -v node_modules); do
+  if [ -f "$file" ]; then
+    IMPORTS=$(grep "^import" "$file" | wc -l)
+    echo "$file — $IMPORTS imports"
+    if [ "$IMPORTS" -gt 15 ]; then
+      echo "  ⚠️  High import count — potential coupling issue"
+    fi
+  fi
+done
+```
+
+## Report Output
+
+Use `references/report-template.md` with the **PR Review** section. The report must answer one clear question: **"Is this safe to merge?"**
+
+Verdict options:
+- ✅ **Ship it** — No blocking issues found
+- ⚠️ **Ship with notes** — Minor issues documented, merge is OK but address soon
+- 🛑 **Hold** — Blocking issues that should be fixed before merge
+
+Include the specific files and line references for each finding.

package/skills/vibe-code-review/references/quick-scan.md

@@ -0,0 +1,178 @@
+# Quick Scan Mode
+
+A fast health check that gives you a snapshot of project quality in under 5 minutes. No git history needed — just the current state of the codebase.
+
+## When to Use
+
+- First look at a new project
+- "Is my codebase healthy?" type questions
+- Quick assessment before deciding if a deep audit is needed
+
+## Steps
+
+### 1. Detect Stack
+
+```bash
+# Find project root markers
+ls package.json requirements.txt go.mod Cargo.toml composer.json Gemfile pom.xml build.gradle 2>/dev/null
+```
+
+Identify: language, framework, package manager, test framework.
+
+### 2. File Size Check
+
+Flag files that are suspiciously large — a signature of AI-generated code dumping logic into monoliths.
+
+```bash
+# Find files over 400 lines (adjust for language)
+find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \
+  | grep -v node_modules | grep -v __pycache__ | grep -v .next \
+  | while read f; do
+    lines=$(wc -l < "$f")
+    if [ "$lines" -gt 400 ]; then
+      echo "⚠️  $f — $lines lines"
+    fi
+  done
+```
+
+**Thresholds:**
+- 🟢 Under 200 lines: Good
+- 🟡 200–400 lines: Acceptable but watch it
+- 🔴 Over 400 lines: Likely needs decomposition
+
+### 3. Function/Method Size Check
+
+```bash
+# For TypeScript/JavaScript — find functions over 50 lines
+# This is a heuristic: count lines between function declarations
+grep -rn "function \|const .* = \(.*\) =>\|async function\|export default function\|export function" \
+  --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" \
+  . | grep -v node_modules | head -50
+```
+
+For Python:
+```bash
+grep -rn "def " --include="*.py" . | grep -v __pycache__ | head -50
+```
+
+Manually spot-check the largest files for functions exceeding 50 lines.
+
+### 4. Dependency Count
+
+```bash
+# Node.js
+cat package.json | python3 -c "
+import sys, json
+pkg = json.load(sys.stdin)
+deps = len(pkg.get('dependencies', {}))
+dev = len(pkg.get('devDependencies', {}))
+print(f'Dependencies: {deps}')
+print(f'Dev dependencies: {dev}')
+print(f'Total: {deps + dev}')
+if deps > 30: print('⚠️  High dependency count — review for unnecessary packages')
+"
+
+# Python
+pip list 2>/dev/null | wc -l
+# or
+cat requirements.txt 2>/dev/null | grep -v "^#" | grep -v "^$" | wc -l
+```
+
+**Thresholds (production deps only):**
+- 🟢 Under 15: Lean
+- 🟡 15–30: Normal
+- 🔴 Over 30: Review for bloat — AI agents over-install
+
+### 5. Dead Import Detection
+
+```bash
+# For TypeScript/JavaScript projects with knip installed
+npx knip --no-exit-code 2>/dev/null || echo "Install knip: npm install -D knip"
+
+# Quick alternative: find unused exports
+npx ts-unused-exports tsconfig.json 2>/dev/null || true
+```
+
+For Python:
+```bash
+# Check if vulture is available, suggest install if not
+python3 -m vulture . --min-confidence 80 2>/dev/null || echo "Install vulture: pip install vulture"
+```
+
+### 6. Error Handling Audit
+
+```bash
+# Find empty or weak catch blocks
+echo "=== Empty catch blocks ==="
+grep -rn "catch" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" -A 2 . \
+  | grep -v node_modules \
+  | grep -E "catch.*\{$|catch.*\{\s*\}" | head -20
+
+echo ""
+echo "=== Console.log-only error handling ==="
+grep -rn "catch" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" -A 3 . \
+  | grep -v node_modules \
+  | grep -B1 "console\.\(log\|error\)" | head -20
+
+echo ""
+echo "=== TODO/FIXME/HACK markers ==="
+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" . \
+  | grep -v node_modules | grep -v __pycache__ | head -20
+```
+
+### 7. Test Presence Check
+
+```bash
+# Check if tests exist at all
+echo "=== Test files ==="
+find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" -o -name "*_test.*" \
+  | grep -v node_modules | grep -v __pycache__
+
+echo ""
+echo "=== Test file count vs source file count ==="
+SRC=$(find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" \
+  | grep -v node_modules | grep -v __pycache__ | grep -v test | grep -v spec | wc -l)
+TEST=$(find . -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" -o -name "*_test.*" \
+  | grep -v node_modules | grep -v __pycache__ | wc -l)
+echo "Source files: $SRC"
+echo "Test files: $TEST"
+if [ "$TEST" -eq 0 ]; then
+  echo "🔴 No tests found"
+elif [ "$TEST" -lt "$((SRC / 3))" ]; then
+  echo "🟡 Low test coverage — fewer than 1 test file per 3 source files"
+else
+  echo "🟢 Reasonable test file count"
+fi
+```
+
+### 8. Architectural Pattern Detection
+
+Scan for common patterns to check consistency:
+
+```bash
+echo "=== Framework patterns detected ==="
+# React patterns
+grep -rl "useEffect\|useState\|useContext" --include="*.tsx" --include="*.jsx" . 2>/dev/null | wc -l | xargs -I{} echo "React hooks files: {}"
+grep -rl "class.*extends.*Component" --include="*.tsx" --include="*.jsx" . 2>/dev/null | wc -l | xargs -I{} echo "React class component files: {}"
+
+# API patterns
+grep -rl "express\|app\.get\|app\.post\|router\." --include="*.ts" --include="*.js" . 2>/dev/null | wc -l | xargs -I{} echo "Express route files: {}"
+grep -rl "NextResponse\|NextRequest" --include="*.ts" --include="*.js" . 2>/dev/null | wc -l | xargs -I{} echo "Next.js API route files: {}"
+
+# State management
+grep -rl "createSlice\|configureStore" --include="*.ts" --include="*.js" . 2>/dev/null | wc -l | xargs -I{} echo "Redux files: {}"
+grep -rl "create.*store\|zustand" --include="*.ts" --include="*.js" . 2>/dev/null | wc -l | xargs -I{} echo "Zustand files: {}"
+grep -rl "useContext\|createContext" --include="*.tsx" --include="*.jsx" . 2>/dev/null | wc -l | xargs -I{} echo "Context API files: {}"
+```
+
+If multiple competing patterns are found (e.g., both Redux AND Zustand, or both class components AND hooks), flag as architectural inconsistency.
+
+## Report Output
+
+Use the template from `references/report-template.md` with the **Quick Scan** section. Produce a severity-sorted summary:
+
+- 🔴 **Critical** — Will cause problems soon (no tests, empty error handling, massive files)
+- 🟡 **Warning** — Technical debt accumulating (high deps, mild duplication, mixed patterns)
+- 🟢 **Healthy** — No action needed
+
+End with a plain-language summary: "If this were a building inspection, here's what I'd flag..."