@softspark/ai-toolkit 1.3.13 → 1.3.15

package/app/skills/cve-scan/scripts/cve_scan.py

@@ -0,0 +1,412 @@
+#!/usr/bin/env python3
+"""CVE dependency scanner — detect ecosystems and run native audit tools.
+
+Stdlib only. No external dependencies.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ECOSYSTEMS = {
+    "npm": {
+        "manifests": ["package.json"],
+        "locks": ["package-lock.json", "yarn.lock", "pnpm-lock.yaml"],
+        "tool": "npm",
+        "audit_cmd": ["npm", "audit", "--json"],
+        "fix_cmd": ["npm", "audit", "fix"],
+        "install_hint": "npm is bundled with Node.js",
+    },
+    "pip": {
+        "manifests": ["requirements.txt", "pyproject.toml", "setup.py", "setup.cfg"],
+        "locks": ["requirements.txt"],
+        "tool": "pip-audit",
+        "audit_cmd": ["pip-audit", "--format=json", "--output=-"],
+        "fix_cmd": ["pip-audit", "--fix"],
+        "install_hint": "pip install pip-audit",
+    },
+    "composer": {
+        "manifests": ["composer.json"],
+        "locks": ["composer.lock"],
+        "tool": "composer",
+        "audit_cmd": ["composer", "audit", "--format=json"],
+        "fix_cmd": ["composer", "update"],
+        "install_hint": "https://getcomposer.org/download/",
+    },
+    "cargo": {
+        "manifests": ["Cargo.toml"],
+        "locks": ["Cargo.lock"],
+        "tool": "cargo-audit",
+        "audit_cmd": ["cargo", "audit", "--json"],
+        "fix_cmd": ["cargo", "audit", "fix"],
+        "install_hint": "cargo install cargo-audit",
+    },
+    "go": {
+        "manifests": ["go.mod"],
+        "locks": ["go.sum"],
+        "tool": "govulncheck",
+        "audit_cmd": ["govulncheck", "-json", "./..."],
+        "fix_cmd": ["go", "get", "-u", "./..."],
+        "install_hint": "go install golang.org/x/vuln/cmd/govulncheck@latest",
+    },
+    "ruby": {
+        "manifests": ["Gemfile"],
+        "locks": ["Gemfile.lock"],
+        "tool": "bundle-audit",
+        "audit_cmd": ["bundle-audit", "check", "--format=json"],
+        "fix_cmd": ["bundle-audit", "update"],
+        "install_hint": "gem install bundler-audit",
+    },
+    "dart": {
+        "manifests": ["pubspec.yaml"],
+        "locks": ["pubspec.lock"],
+        "tool": "dart",
+        "audit_cmd": ["dart", "pub", "outdated", "--json"],
+        "fix_cmd": ["dart", "pub", "upgrade"],
+        "install_hint": "https://dart.dev/get-dart",
+    },
+}
+
+
+def detect_ecosystems(root: Path) -> list[dict]:
+    """Detect which package ecosystems are present in the project."""
+    found = []
+    for name, eco in ECOSYSTEMS.items():
+        detected_files = []
+        has_lock = False
+        for m in eco["manifests"]:
+            if (root / m).exists():
+                detected_files.append(m)
+        for m in eco["locks"]:
+            if (root / m).exists():
+                detected_files.append(m)
+                has_lock = True
+        # Deduplicate (requirements.txt is both manifest and lock)
+        detected_files = list(dict.fromkeys(detected_files))
+        if detected_files:
+            tool_path = shutil.which(eco["tool"])
+            found.append({
+                "name": name,
+                "files": detected_files,
+                "has_lock": has_lock,
+                "tool": eco["tool"],
+                "tool_available": tool_path is not None,
+                "install_hint": eco["install_hint"],
+                "audit_cmd": eco["audit_cmd"],
+                "fix_cmd": eco["fix_cmd"],
+            })
+    return found
+
+
+def run_audit(eco: dict, root: Path, fix: bool = False) -> dict:
+    """Run the native audit command for an ecosystem."""
+    cmd = eco["fix_cmd"] if fix else eco["audit_cmd"]
+    result = {
+        "ecosystem": eco["name"],
+        "tool": eco["tool"],
+        "command": " ".join(cmd),
+        "success": False,
+        "raw_output": "",
+        "error": "",
+    }
+
+    if not eco["tool_available"]:
+        result["error"] = f"Tool '{eco['tool']}' not installed. Install: {eco['install_hint']}"
+        return result
+
+    if not eco.get("has_lock", True) and eco["name"] in ("npm",):
+        result["warning"] = "No lock file — run `npm install` first"
+        result["success"] = True
+        return result
+
+    try:
+        proc = subprocess.run(
+            cmd,
+            cwd=str(root),
+            capture_output=True,
+            text=True,
+            timeout=120,
+        )
+        result["raw_output"] = proc.stdout
+        result["error"] = proc.stderr if proc.returncode not in (0, 1) else ""
+        # npm audit returns 1 when vulnerabilities found — that's not an error
+        result["success"] = True
+    except FileNotFoundError:
+        result["error"] = f"Tool '{eco['tool']}' not found in PATH"
+    except subprocess.TimeoutExpired:
+        result["error"] = f"Audit command timed out after 120s"
+
+    return result
+
+
+def parse_npm_audit(raw: str) -> list[dict]:
+    """Parse npm audit JSON output into unified findings."""
+    findings = []
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return findings
+
+    vulns = data.get("vulnerabilities", {})
+    for pkg_name, info in vulns.items():
+        for via in info.get("via", []):
+            if isinstance(via, dict):
+                severity = via.get("severity", "unknown").upper()
+                findings.append({
+                    "severity": severity,
+                    "package": pkg_name,
+                    "installed": info.get("range", "unknown"),
+                    "cve": via.get("cve", [via.get("url", "N/A")]),
+                    "title": via.get("title", "Unknown"),
+                    "url": via.get("url", ""),
+                    "fixed_in": info.get("fixAvailable", {}).get("version", "unknown") if isinstance(info.get("fixAvailable"), dict) else "unknown",
+                })
+    return findings
+
+
+def parse_pip_audit(raw: str) -> list[dict]:
+    """Parse pip-audit JSON output into unified findings."""
+    findings = []
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return findings
+
+    for dep in data.get("dependencies", []):
+        for vuln in dep.get("vulns", []):
+            vuln_id = vuln.get("id", "N/A")
+            aliases = vuln.get("aliases", [])
+            # Use GHSA link if available, otherwise OSV
+            url = ""
+            for alias in aliases:
+                if alias.startswith("GHSA-"):
+                    url = f"https://github.com/advisories/{alias}"
+                    break
+            if not url:
+                url = f"https://osv.dev/vulnerability/{vuln_id}"
+
+            fix_versions = vuln.get("fix_versions", [])
+            # Determine severity from CVE ID prefix heuristic — pip-audit
+            # doesn't provide severity directly, so we mark as HIGH by default
+            severity = "HIGH"
+
+            findings.append({
+                "severity": severity,
+                "package": f"{dep['name']}@{dep['version']}",
+                "installed": dep.get("version", "unknown"),
+                "cve": vuln_id,
+                "title": vuln.get("description", "")[:120] + ("..." if len(vuln.get("description", "")) > 120 else ""),
+                "url": url,
+                "fixed_in": ", ".join(fix_versions) if fix_versions else "unknown",
+            })
+    return findings
+
+
+def parse_cargo_audit(raw: str) -> list[dict]:
+    """Parse cargo audit JSON output into unified findings."""
+    findings = []
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return findings
+
+    for vuln in data.get("vulnerabilities", {}).get("list", []):
+        advisory = vuln.get("advisory", {})
+        pkg = vuln.get("package", {})
+        findings.append({
+            "severity": "HIGH",
+            "package": f"{pkg.get('name', 'unknown')}@{pkg.get('version', 'unknown')}",
+            "installed": pkg.get("version", "unknown"),
+            "cve": advisory.get("id", "N/A"),
+            "title": advisory.get("title", "Unknown"),
+            "url": advisory.get("url", ""),
+            "fixed_in": ", ".join(vuln.get("versions", {}).get("patched", [])) or "unknown",
+        })
+    return findings
+
+
+def _table(headers: list[str], rows: list[list[str]]) -> list[str]:
+    """Render an aligned plain-text table with box-drawing borders."""
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(cell))
+
+    sep = "├" + "┼".join("─" * (w + 2) for w in widths) + "┤"
+    top = "┌" + "┬".join("─" * (w + 2) for w in widths) + "┐"
+    bot = "└" + "┴".join("─" * (w + 2) for w in widths) + "┘"
+
+    def fmt_row(cells: list[str]) -> str:
+        parts = []
+        for i, cell in enumerate(cells):
+            parts.append(f" {cell:<{widths[i]}} ")
+        return "│" + "│".join(parts) + "│"
+
+    lines = [top, fmt_row(headers), sep]
+    for row in rows:
+        lines.append(fmt_row(row))
+    lines.append(bot)
+    return lines
+
+
+def format_text_report(ecosystems: list[dict], results: list[dict], all_findings: list[dict]) -> str:
+    """Format findings as a terminal-friendly report."""
+    lines = ["", "═══ CVE Scan Report ═══", ""]
+
+    # Ecosystems detected
+    eco_rows = []
+    for eco in ecosystems:
+        status = "✓" if eco["tool_available"] else "⚠ not installed"
+        files = ", ".join(eco["files"])
+        eco_rows.append([eco["name"], files, eco["tool"], status])
+    lines.extend(_table(["Ecosystem", "Files", "Tool", "Status"], eco_rows))
+    lines.append("")
+
+    # Summary
+    severity_counts = {"CRITICAL": 0, "HIGH": 0, "MODERATE": 0, "MEDIUM": 0, "LOW": 0}
+    for f in all_findings:
+        sev = f["severity"].upper()
+        if sev in severity_counts:
+            severity_counts[sev] += 1
+        else:
+            severity_counts[sev] = severity_counts.get(sev, 0) + 1
+
+    # Merge MODERATE into MEDIUM for display
+    severity_counts["MEDIUM"] += severity_counts.pop("MODERATE", 0)
+
+    total = sum(severity_counts.values())
+    summary_rows = []
+    for sev in ["CRITICAL", "HIGH", "MEDIUM", "LOW"]:
+        if severity_counts.get(sev, 0) > 0:
+            summary_rows.append([sev, str(severity_counts[sev])])
+    summary_rows.append(["TOTAL", str(total)])
+    lines.extend(_table(["Severity", "Count"], summary_rows))
+    lines.append("")
+
+    if not all_findings:
+        lines.append("✓ No known vulnerabilities found.")
+        lines.append("")
+
+    # Findings by severity
+    if all_findings:
+        severity_order = {"CRITICAL": 0, "HIGH": 1, "MODERATE": 2, "MEDIUM": 2, "LOW": 3}
+        sorted_findings = sorted(all_findings, key=lambda f: severity_order.get(f["severity"].upper(), 9))
+
+        finding_rows = []
+        for f in sorted_findings:
+            sev = f["severity"].upper()
+            if sev == "MODERATE":
+                sev = "MEDIUM"
+            cve = f["cve"] if isinstance(f["cve"], str) else ", ".join(f["cve"]) if f["cve"] else "N/A"
+            title = f["title"][:60] + ("..." if len(f["title"]) > 60 else "")
+            finding_rows.append([sev, f["package"], cve, f["fixed_in"], title])
+
+        lines.extend(_table(["Severity", "Package", "CVE", "Fix", "Title"], finding_rows))
+        lines.append("")
+
+        # Detailed advisory links
+        lines.append("Advisory links:")
+        for f in sorted_findings:
+            if f.get("url"):
+                cve = f["cve"] if isinstance(f["cve"], str) else ", ".join(f["cve"]) if f["cve"] else "N/A"
+                lines.append(f"  {cve}: {f['url']}")
+        lines.append("")
+
+    # Install hints for missing tools
+    missing = [e for e in ecosystems if not e["tool_available"]]
+    if missing:
+        lines.append("Missing tools:")
+        for eco in missing:
+            lines.append(f"  {eco['name']}: install with: {eco['install_hint']}")
+        lines.append("")
+
+    # Warnings (non-fatal issues like missing lock files)
+    warnings = [r for r in results if r.get("warning")]
+    if warnings:
+        for r in warnings:
+            lines.append(f"⚠ {r['ecosystem']}: {r['warning']}")
+        lines.append("")
+
+    # Errors (fatal issues)
+    errors = [r for r in results if r.get("error")]
+    if errors:
+        for r in errors:
+            lines.append(f"✗ {r['ecosystem']}: {r['error']}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(description="CVE dependency scanner")
+    parser.add_argument("--json", action="store_true", help="JSON output")
+    parser.add_argument("--fix", action="store_true", help="Auto-fix vulnerabilities")
+    parser.add_argument("--ecosystem", type=str, help="Scan specific ecosystem only")
+    parser.add_argument("path", nargs="?", default=".", help="Project root path")
+    args = parser.parse_args()
+
+    root = Path(args.path).resolve()
+    if not root.is_dir():
+        print(f"Error: {root} is not a directory", file=sys.stderr)
+        sys.exit(1)
+
+    # Detect
+    ecosystems = detect_ecosystems(root)
+    if args.ecosystem:
+        ecosystems = [e for e in ecosystems if e["name"] == args.ecosystem]
+
+    if not ecosystems:
+        msg = "No supported package ecosystems detected."
+        if args.json:
+            print(json.dumps({"ecosystems": [], "findings": [], "message": msg}))
+        else:
+            print(msg)
+        sys.exit(0)
+
+    # Run audits
+    results = []
+    all_findings = []
+    for eco in ecosystems:
+        result = run_audit(eco, root, fix=args.fix)
+        results.append(result)
+
+        # Parse results with ecosystem-specific parsers
+        if result["success"] and result["raw_output"]:
+            parsers = {
+                "npm": parse_npm_audit,
+                "pip": parse_pip_audit,
+                "cargo": parse_cargo_audit,
+            }
+            parser = parsers.get(eco["name"])
+            if parser:
+                findings = parser(result["raw_output"])
+                for f in findings:
+                    f["ecosystem"] = eco["name"]
+                all_findings.extend(findings)
+
+    # Output
+    if args.json:
+        output = {
+            "ecosystems": [{"name": e["name"], "files": e["files"], "tool_available": e["tool_available"]} for e in ecosystems],
+            "results": results,
+            "findings": all_findings,
+            "total_findings": len(all_findings),
+        }
+        print(json.dumps(output, indent=2))
+    else:
+        report = format_text_report(ecosystems, results, all_findings)
+        print(report)
+
+    # Exit code: non-zero if CRITICAL or HIGH found
+    high_or_critical = [f for f in all_findings if f["severity"].upper() in ("CRITICAL", "HIGH")]
+    if high_or_critical:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/app/skills/database-patterns/SKILL.md

@@ -296,3 +296,13 @@ client.create_payload_index(
 | COSINE | Text embeddings | Yes |
 | EUCLID | Image embeddings | No |
 | DOT | When vectors pre-normalized | Yes |
+
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "We'll add indexes later when it's slow" | Missing indexes on production tables cause outages, not slowdowns — index from design |
+| "The ORM handles performance" | ORMs generate queries, they don't optimize them — always check the query plan |
+| "NoSQL is faster" | NoSQL trades consistency for speed — if you need joins, use a relational DB |
+| "We don't need migrations, we'll update the schema directly" | Direct schema changes are irreversible and untestable — migrations are the safety net |
+| "One big table is simpler" | Denormalization without measurement creates update anomalies — normalize first, denormalize with data |

package/app/skills/debug/SKILL.md

@@ -144,6 +144,16 @@ Have them talk to each other to challenge each other's theories.
 Report consensus when done.
 ```
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It works on my machine" | Environment differences are the #1 cause of production bugs — reproduce in prod-like env |
+| "It must be a library bug" | 95% of the time it's your code — exhaust local hypotheses first |
+| "I'll just add more logging and wait" | Passive debugging wastes hours — form a hypothesis and test it actively |
+| "The error message says X, so it must be X" | Error messages often describe symptoms, not root causes — trace the full chain |
+| "It only happens sometimes, probably a fluke" | Intermittent bugs are race conditions or state leaks — they get worse, not better |
+
 ## Debug Checklist
 
 - [ ] Identified error/symptom
@@ -152,3 +162,9 @@ Report consensus when done.
 - [ ] Reproduced issue
 - [ ] Formed hypothesis
 - [ ] Tested fix
+
+## Related Skills
+- Bug fixed? → `/review` to verify the fix quality
+- Need a regression test? → `/tdd` to write it test-first
+- Performance issue? → `/analyze --type=complexity` for hotspot analysis
+- Incident in production? → `/workflow incident-response` for full response

package/app/skills/docs/SKILL.md

@@ -113,6 +113,16 @@ Proposed
 - [ ] Commit changes
 ```
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "The code is self-documenting" | Code shows how, not why — decisions, constraints, and context need prose |
+| "Nobody reads docs anyway" | People don't read bad docs — good docs are the first thing consulted |
+| "I'll document it when it's stable" | Unstable code needs docs most — document intent so others can contribute |
+| "Comments get stale" | That's an argument for maintaining docs, not skipping them |
+| "The tests are the documentation" | Tests verify behavior but don't explain architecture, trade-offs, or setup |
+
 ## Configuration
 
 Documentation settings in:
@@ -143,3 +153,9 @@ Create an agent team for documentation:
 - Teammate 3 (documenter): "Generate README sections: installation, usage, API reference." Use Opus.
 Teammates should NOT overlap — each owns their assigned scope.
 ```
+
+## Related Skills
+- Documenting an architecture decision? → `/council` for multi-perspective analysis first
+- Need to explore the codebase? → `/explore` to understand structure before documenting
+- Writing a PRD? → `/write-a-prd` for structured product requirements
+- Auditing existing docs? → `/analyze` for coverage gaps

package/app/skills/git-mastery/SKILL.md

@@ -68,3 +68,13 @@ git cherry-pick --continue
 - `perf:` Performance improvement
 - `test:` Adding missing tests
 - `chore:` Build process/auxiliary tools
+
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "I'll clean up commits later" | Later means never — write clean commits as you go |
+| "Force push is fine on my branch" | Others may have fetched your branch — use --force-with-lease |
+| "One big commit is simpler" | Big commits are impossible to review, bisect, or revert — keep them atomic |
+| "Merge conflicts mean someone else's problem" | Conflicts mean you diverged too long — rebase frequently to stay aligned |
+| "Commit messages don't matter" | Messages are documentation — future you needs to understand why, not just what |

package/app/skills/onboard/SKILL.md

@@ -17,6 +17,21 @@ Guide the user through setting up the ai-toolkit in their project, including con
 
 ## Setup Steps
 
+### Step 0: Intent Capture Interview
+
+Before setting up tooling, understand the project's undocumented context. Ask the developer these questions (adapt based on what the codebase scan reveals):
+
+1. **What's the one thing a new contributor always gets wrong?** — This reveals the biggest documentation gap
+2. **Are there files or directories that should NOT be modified?** — Identifies protected areas (legacy, generated, vendor)
+3. **What's the deployment model?** — Monolith, microservices, serverless, edge — shapes which agents and skills are most relevant
+4. **Are there non-obvious constraints?** — Compliance requirements, performance budgets, browser support matrix
+5. **What's the team's review culture?** — Strict PR reviews, trunk-based, pair programming — configures `/review` behavior
+
+Use answers to:
+- Customize the generated `CLAUDE.md` with project-specific warnings and conventions
+- Select the right `--profile` (minimal/standard/strict) automatically
+- Pre-configure relevant language rules
+
 ### Step 1: Prerequisites Check
 - [ ] Claude Code CLI installed
 - [ ] ai-toolkit repository cloned

package/app/skills/performance-profiling/SKILL.md

@@ -57,3 +57,13 @@ Always measure -> change -> measure.
 2. **Algorithm**: (O(n²) -> O(n log n))
 3. **Memory**: (Allocation churn, GC pressure)
 4. **Micro-optimization**: (Loop unrolling, etc.) - *Smallest Gains*
+
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It feels slow, let me optimize this function" | Feelings aren't data — profile first, then optimize the actual bottleneck |
+| "We should optimize everything" | Premature optimization is the root of all evil — focus on the critical path |
+| "Caching will fix it" | Caching masks problems and adds complexity — fix the root cause first |
+| "It's fast enough in dev" | Dev has 1 user — production has thousands and cold caches |
+| "We'll optimize later" | Performance debt compounds — a 100ms regression per sprint = 5s in a year |

package/app/skills/plan/SKILL.md

@@ -95,6 +95,16 @@ During planning:
 - NO code writing
 - NO file creation (except plan)
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "We already know what to build" | Assumed requirements lead to rework — validate assumptions explicitly |
+| "Planning is wasted time, just start coding" | Unplanned work has 3-5x more rework — 30 min planning saves days |
+| "The requirements will change anyway" | Plans adapt — without one, you can't assess impact of changes |
+| "It's a small feature, no plan needed" | Small features in complex systems have hidden dependencies — map them |
+| "We'll figure it out as we go" | Discovery without structure leads to scope creep and missed edge cases |
+
 ## Next Steps
 
 After plan approval:
@@ -108,3 +118,9 @@ Before planning:
 smart_query("project template: {type}")
 hybrid_search_kb("architecture {pattern}")
 ```
+
+## Related Skills
+- Plan approved? → `/orchestrate` or `/workflow` to execute with agents
+- Need requirements first? → `/write-a-prd` for structured product requirements
+- Want to stress-test the plan? → `/grill-me` for Socratic questioning
+- Ready to break into issues? → `/prd-to-plan` → `/triage-issue`

package/app/skills/refactor/SKILL.md

@@ -81,6 +81,16 @@ Before executing:
 - [ ] Tests passing
 - [ ] Backup created
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "It works, don't touch it" | Working code that's hard to maintain slows every future change |
+| "We'll refactor it later" | Later never comes — refactor when the pain is fresh and context is loaded |
+| "It's too risky to change" | That's exactly why it needs refactoring — risk compounds with complexity |
+| "Just one more hack won't hurt" | Each hack makes the next one easier to justify — break the cycle now |
+| "We need to rewrite from scratch" | Incremental refactoring is safer and delivers value continuously |
+
 ## READ BEFORE WRITE
 
 This command analyzes and plans first.
@@ -122,3 +132,9 @@ Create an agent team for refactoring:
 - Teammate 2 (backend-specialist): "Implement the refactoring changes identified by the reviewer." Use Opus.
 Teammate 1 completes first, then Teammate 2 acts on the plan.
 ```
+
+## Related Skills
+- Need a safe refactor plan? → `/refactor-plan` for incremental steps as GitHub RFC
+- Want to validate architecture? → `/analyze` for code quality metrics
+- Need tests before refactoring? → `/tdd` to build safety net first
+- Architecture decision needed? → `/council` for multi-perspective evaluation

package/app/skills/review/SKILL.md

@@ -117,17 +117,40 @@ After all reviewers complete:
 - **Lines Added**: [+count]
 - **Lines Removed**: [-count]
 - **Issues Found**: [count]
+- **Overall Confidence**: [1-10] — how confident the reviewer is in the assessment
 
 ### Findings
 
 #### Critical
 - **[file:line]**: [issue]
-  - [explanation]
+  - Severity: critical | Confidence: [1-10]
+  - Evidence: [specific code reference and reasoning]
   - Suggested fix: [code]
 
-#### Suggestions
+#### Major
+- **[file:line]**: [issue]
+  - Severity: major | Confidence: [1-10]
+  - Evidence: [specific code reference and reasoning]
+  - Suggested fix: [code]
+
+#### Minor
+- **[file:line]**: [issue]
+  - Severity: minor | Confidence: [1-10]
+  - Evidence: [line number + reasoning]
+
+#### Nit
 - **[file:line]**: [suggestion]
-  - [explanation]
+  - Severity: nit | Confidence: [1-10]
+
+### Confidence Guide
+
+| Score | Meaning |
+|-------|---------|
+| 9-10 | Certain — verified via code, tests, or documentation |
+| 7-8 | High — strong evidence, minor assumptions |
+| 5-6 | Medium — plausible issue, needs author confirmation |
+| 3-4 | Low — speculative, based on patterns not proof |
+| 1-2 | Guess — flag for discussion, don't block on this |
 
 ### Positive Notes
 - [What's good about the code]
@@ -136,6 +159,38 @@ After all reviewers complete:
 [APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION]
 ```
 
+## Common Rationalizations
+
+| Excuse | Why It's Wrong |
+|--------|----------------|
+| "Small change, quick scan is enough" | Small changes introduce subtle bugs — apply consistent review regardless of size |
+| "Tests pass, so the code is correct" | Tests validate specific scenarios, not all behaviors — verify missing coverage |
+| "It's just a refactor, no need for deep review" | Refactors change invariants — verify behavior preservation, not just compilation |
+| "The author is senior, they know what they're doing" | Seniority doesn't prevent mistakes — review the code, not the person |
+| "We're in a hurry, ship it" | Rushed reviews create tech debt that costs 10x more to fix later |
+
+## Self-Evaluation (LLM-as-Judge)
+
+After completing the review, perform a self-evaluation pass:
+
+### Check for Blind Spots
+1. **Did I verify, or assume?** — For each finding, confirm you read the actual code (not inferred from context)
+2. **Did I miss the inverse?** — If you flagged X as a problem, did you check if NOT doing X is also a problem elsewhere?
+3. **Did I anchor on the first issue?** — Review whether early findings biased you toward similar patterns, missing different issue classes
+4. **Did I check the unhappy path?** — Error handling, edge cases, failure modes — not just the golden path
+5. **Did I flag uncertainty?** — Findings with confidence < 6 should be clearly marked as "needs author input"
+
+### Calibrate Confidence
+- If all findings are confidence 7+, you may be overconfident — re-examine the weakest finding
+- If any finding lacks a file:line reference, downgrade it or remove it
+- If you found zero issues, state what you specifically checked (not "looks good")
+
 ## READ-ONLY
 
 This skill only analyzes. It does NOT modify any files.
+
+## Related Skills
+- Issues found? → `/debug` to trace root causes
+- Missing tests? → `/tdd` to add test-first coverage
+- Security findings? → `/cve-scan` for dependency vulnerabilities
+- Architecture concerns? → `/analyze` for deeper code quality metrics