claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/skills/writing-hooks/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: writing-hooks
+description: How to write Claude Code hooks — lifecycle events, exit codes, profiles, jq/node parsing, settings.json wiring, and testing.
+tokens: 2640
+user-invocable: false
+---
+
+# Writing Claude Code Hooks
+
+Hooks are shell scripts Claude Code runs at lifecycle events (before/after a tool, on session start, before compaction, on stop). They observe tool calls and can block a dangerous one. This reference covers the file format, exit codes, per-event stdin JSON, the profile system, parsing, `settings.json` wiring, and testing.
+
+## Use when
+
+- Writing or editing a hook under `.claude/scripts/hooks/`.
+- Wiring a hook into `.claude/settings.json`.
+- Debugging why a hook blocks, warns, or gets skipped.
+
+## Do not use when
+
+- Authoring agents or slash commands → use the writing-agents / writing-commands skills.
+- The task is application code, not lifecycle automation.
+
+## Hard Rules
+
+- Default to `exit 0`. Use `exit 2` only when you are certain the action must be blocked — a hook must never crash Claude Code.
+- On any unexpected error, fail open (`exit 0`); a broken hook must not stop the user's work.
+- Do NOT use `set -e` — one failing command must not abort the whole hook.
+- Keep every hook under ~1-2 seconds; guard external calls with the `timeout` command; never block on the network.
+- Always quote paths (`"$FILE_PATH"`); confirm a file exists before reading it.
+- `timeout:` in `settings.json` is in SECONDS, not milliseconds.
+- Hooks observe and warn — they do not modify files.
+
+## Hook File Anatomy
+
+Hooks are `.sh` files in `.claude/scripts/hooks/`.
+
+```bash
+#!/bin/bash
+# hook-name.sh — [Event] hook
+# Description of what this hook does
+# Profile: [always|fast|standard|strict]   # see Profile System
+
+# Read hook input from stdin (JSON)
+INPUT=$(cat)
+
+# Parse fields with jq (if available) or node
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+# Your validation logic here
+
+exit 0
+```
+
+## Exit Codes
+
+| Code | Meaning | Effect |
+|------|---------|--------|
+| `0` | Allow | Tool call proceeds (or no output for info-only hooks) |
+| `2` | **BLOCK** | Tool call is rejected; stderr message shown to Claude |
+| Other | Error | Hook failure logged, tool call proceeds (fail-open) |
+
+## Lifecycle Events
+
+### PreToolUse
+
+Fires **before** a tool executes. Can block the tool call.
+
+```json
+{ "tool_name": "Bash", "tool_input": { "command": "git push --force" } }
+```
+
+Settings wiring:
+
+```json
+{
+  "PreToolUse": [{
+    "matcher": "Bash",
+    "hooks": [{
+      "type": "command",
+      "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/scripts/hooks/your-hook.sh"
+    }]
+  }]
+}
+```
+
+Matcher values: `Bash`, `Edit`, `Write`, `Read`, `Glob`, `Grep`, or combinations with `|` (e.g. `Edit|Write`).
+
+### PostToolUse
+
+Fires **after** a tool executes. Cannot block (the tool already ran). Use for warnings and tracking. Output to stderr is shown as a warning to Claude:
+
+```bash
+echo "WARNING: console.log detected in production code" >&2
+```
+
+### PreCompact
+
+Fires before context compaction. Save important state here. Input: `{ "trigger": "manual" | "auto" }`. Stdout is NOT injected — persist data with file writes.
+
+### SessionStart
+
+Fires when a new Claude Code session begins. Stdout IS injected into Claude's initial context — use it to restore state.
+
+```bash
+echo "<previous-session-context>"
+echo "Last session was working on: feature X"
+echo "</previous-session-context>"
+```
+
+### Stop
+
+Fires when Claude is about to end a response. Use the `prompt` type for LLM-based verification. `timeout` is in SECONDS (the kit's `settings.json` uses `60`):
+
+```json
+{
+  "type": "prompt",
+  "prompt": "Verify compilation is clean and docs are updated.",
+  "model": "opus",
+  "timeout": 60
+}
+```
+
+## Profile System
+
+Users trade thoroughness for speed with the `CLAUDE_HOOK_PROFILE` env var, which takes one of three runtime values: `fast`, `standard` (default), `strict`. Each hook declares the tier at which it runs in its header `# Profile:` line — one of **four** labels:
+
+| Label | fast | standard | strict | Use for |
+|-------|------|----------|--------|---------|
+| `always` | runs | runs | runs | safety that must never be skipped (block `.env` commit, dangerous git) — carries no profile guard |
+| `fast` | runs | runs | runs | critical safety kept in the minimal fast set |
+| `standard` | skip | runs | runs | default core hooks (the common case) |
+| `strict` | skip | skip | runs | extra or expensive validation, pre-release only |
+
+`always` differs from `fast` only in intent: an `always` hook has no profile guard at all, so it keeps running even if the fast set is later trimmed.
+
+Implementing profile support:
+
+```bash
+#!/bin/bash
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+
+# 'standard' hook: skip in fast mode
+[ "$PROFILE" = "fast" ] && exit 0
+
+# extra checks only in strict mode
+if [ "$PROFILE" = "strict" ]; then
+  : # additional validation...
+fi
+```
+
+## Input Parsing Patterns
+
+With jq (preferred):
+
+```bash
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+```
+
+With node (jq fallback):
+
+```bash
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | node -e "
+  let d=''; process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    try { console.log(JSON.parse(d).tool_input?.file_path||''); }
+    catch { console.log(''); }
+  });
+")
+```
+
+File extension filter:
+
+```bash
+case "$FILE_PATH" in
+  *.go) ;;          # Go file — proceed
+  *.ts|*.tsx) ;;    # TypeScript file — proceed
+  *) exit 0 ;;      # not relevant — skip
+esac
+```
+
+## Registering a Hook
+
+Hooks are registered in `.claude/settings.json`. `timeout` is in **SECONDS**:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/scripts/hooks/your-hook.sh",
+        "timeout": 10
+      }]
+    }]
+  }
+}
+```
+
+Recommended `timeout` values (seconds):
+
+- PreToolUse: 5-10
+- PostToolUse: 5-15
+- PreCompact: 10-30
+- SessionStart: 10-30
+- Stop (prompt): 60 (matches the kit's `settings.json`)
+
+## Advanced: JSON on stdout
+
+This kit uses the exit-code + stderr protocol above. Claude Code also accepts a JSON object on a hook's stdout for finer control:
+
+- `{"decision": "block", "reason": "..."}` / `{"decision": "allow"}` — how the `Stop` prompt hook gates the end of a response (see the kit's `settings.json` Stop hook).
+- `{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "..."}}` — inject text into context from `SessionStart` or `UserPromptSubmit` (equivalent to plain stdout injection for those two events).
+
+Prefer exit codes + stderr unless you specifically need to return a structured decision or inject context.
+
+## Best Practices
+
+DO:
+
+- **Fail open** — unexpected errors should `exit 0`, not block work.
+- **Be fast** — hooks run on every matching tool call; keep them under 1-2 seconds.
+- **Use stderr for warnings** — `echo "WARNING: ..." >&2`.
+- **Check the profile first** — skip unnecessary work in fast mode.
+- **Quote paths** — always `"$FILE_PATH"` to handle spaces.
+- **Set timeouts** — wrap external calls in the `timeout` command.
+- **Be specific** — check file extensions before running expensive analysis.
+
+DON'T:
+
+- **Don't block on the network** — hooks must work offline.
+- **Don't modify files** — hooks observe and warn, they don't change code.
+- **Don't produce false positives** — every warning must be actionable.
+- **Don't use `set -e`** — one failing command shouldn't crash the hook.
+- **Don't read large files** — use `head` or grep patterns instead.
+- **Don't rely on stdout to block in PreToolUse** — in this kit's exit-code protocol, only the exit code and stderr affect a PreToolUse call (the JSON-on-stdout decision protocol above is not used by this kit's hooks).
+
+## Naming Convention
+
+Use descriptive kebab-case. Lead with the action verb when the hook blocks or mutates state; otherwise name by target + concern. Keep the event or trigger recognizable.
+
+```
+block-dangerous-git.sh     — PreToolUse: blocks dangerous git commands
+console-log-warning.sh     — PostToolUse: warns on console.log
+migration-safety.sh        — PostToolUse: validates migration files
+pre-compact-save.sh        — PreCompact: saves context before compaction
+session-context-restore.sh — SessionStart: restores previous context
+```
+
+## Example: Minimal PostToolUse Hook
+
+```bash
+#!/bin/bash
+# todo-check.sh — PostToolUse hook
+# Warns when TODO comments are added without ticket references
+# Profile: standard
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+[ "$PROFILE" = "fast" ] && exit 0
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
+
+[ -z "$FILE_PATH" ] && exit 0
+[ ! -f "$FILE_PATH" ] && exit 0
+
+# Only check source files
+case "$FILE_PATH" in
+  *.go|*.ts|*.tsx|*.py|*.rs) ;;
+  *) exit 0 ;;
+esac
+
+# Find TODOs, then drop the ones that carry a real ticket like TODO(PROJ-123).
+MATCHES=$(grep -nE 'TODO' "$FILE_PATH" 2>/dev/null | grep -vE 'TODO\([A-Z]+-[0-9]+\)' | head -3)
+if [ -n "$MATCHES" ]; then
+  echo "WARNING: TODO(s) without ticket reference in $FILE_PATH:" >&2
+  echo "$MATCHES" >&2
+  echo "  Expected form: TODO(PROJ-123) description" >&2
+fi
+
+exit 0
+```
+
+## Example: Minimal PreToolUse Hook
+
+```bash
+#!/bin/bash
+# block-env-commit.sh — PreToolUse hook
+# Blocks git commits that include .env files
+# Profile: always
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+
+# Only check git add/commit commands
+case "$COMMAND" in
+  git\ add*|git\ commit*) ;;
+  *) exit 0 ;;
+esac
+
+# Block if .env files are staged
+if git diff --cached --name-only 2>/dev/null | grep -q '\.env'; then
+  echo "BLOCKED: .env file is staged for commit. Remove with: git reset HEAD .env" >&2
+  exit 2
+fi
+
+exit 0
+```
+
+## Testing Hooks
+
+```bash
+# Test a PostToolUse hook manually:
+echo '{"tool_name":"Edit","tool_input":{"file_path":"src/main.go"}}' | \
+  bash .claude/scripts/hooks/your-hook.sh
+
+# Check exit code:
+echo $?  # 0 = allow, 2 = block
+
+# Check stderr output:
+echo '{"tool_name":"Bash","tool_input":{"command":"git push --force"}}' | \
+  bash .claude/scripts/hooks/block-dangerous-git.sh 2>&1
+```
+
+## Recap — non-negotiables
+
+- Default `exit 0`; `exit 2` only to block with certainty; fail open on errors; no `set -e`.
+- Keep hooks under ~1-2s, quote paths, and never block on the network.
+- `timeout:` in `settings.json` is in SECONDS.
+- Profile labels are `always` / `fast` / `standard` / `strict`; the runtime `CLAUDE_HOOK_PROFILE` is `fast` / `standard` / `strict`.
+- Hooks observe and warn — they never modify files.

package/packages/extras/bot-reviewer.md

@@ -0,0 +1,279 @@
+---
+name: bot-reviewer
+description: Review chat bot code (Telegram, Discord, Slack) for callback safety, state machines, rate limits, and production readiness
+tokens: 3438
+model: opus
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Chat Bot Code Reviewer
+
+You are a code reviewer specializing in chat bot code for Telegram, Discord, Slack, and other messaging platforms.
+
+## Hard Rules
+
+1. Every finding passes the Evidence Gate below — no `file:line` you actually Read this session, no finding.
+2. Two-stage discipline: Stage 1 (Discovery) surfaces EVERY candidate at any severity, no pre-filtering; Stage 2 (Triage) assigns Severity/Confidence. Better to surface a candidate that gets filtered than to silently miss a real bug.
+3. Route LOW-confidence (<60) or ambiguous candidates to the report's **Open Questions** section — never silently drop them.
+4. Use only canonical enums: Severity CRITICAL / WARNING / SUGGESTION · Confidence HIGH (≥80) / MEDIUM (60–79) / LOW (<60).
+5. Detect the bot platform (Phase 1) before applying checks — limits differ per platform.
+6. Emit every Output Contract section, including Open Questions (write "None" if empty).
+
+## Evidence Gate
+
+Report a finding ONLY if all four hold:
+1. **Citation** — exact `file:line` you Read in this session, never from memory.
+2. **Failure mode** — a concrete input/path that triggers the problem (no "could be problematic").
+3. **Context** — you read the surrounding function/callers, not just the flagged line.
+4. **Severity** you can defend to a skeptic.
+If a referenced file/symbol cannot be found: output `NOT FOUND: <path>` — never invent its contents.
+A clean review (0 findings) is a valid result — do not manufacture findings.
+
+Skip entirely (not even Open Questions): style nits already enforced by a linter, hypotheticals with no concrete trigger.
+
+## Phase 0 — Load Project Context
+
+Read if present, skip silently if absent: `CLAUDE.md` or `AGENTS.md`; any bot-specific `docs/architecture/*.md`.
+Use it to: learn callback data format conventions, state machine patterns, and rate-limit requirements. Violations of DOCUMENTED conventions → report with HIGH confidence instead of MEDIUM.
+
+## Process
+
+### Phase 1 — Detect Platform & Framework
+
+Goal: know which platform's API constraints apply.
+Actions: match dependency/import markers against this table.
+
+| Marker | Platform | Library |
+|--------|----------|---------|
+| `go-telegram-bot-api` / `tgbotapi` | Telegram | Go |
+| `python-telegram-bot` / `aiogram` / `telebot` | Telegram | Python |
+| `telegraf` / `grammY` / `node-telegram-bot-api` | Telegram | Node.js |
+| `discord.py` / `nextcord` / `pycord` | Discord | Python |
+| `discord.js` / `eris` | Discord | Node.js |
+| `serenity` / `poise` | Discord | Rust |
+| `@slack/bolt` / `slack-sdk` | Slack | Node.js/Python |
+
+Adapt checks to the platform's constraints (e.g., Telegram's 64-byte callback limit, Discord's 100-character command name limit).
+Done when: platform + library identified, or recorded as "unknown — generic checks applied".
+
+### Phase 2 — Discovery Scan (Stage 1)
+
+Goal: full coverage of the 22-item Review Checklist below.
+Actions: apply every checklist item to the target files; add every violation you notice to the candidate list at any severity. Do not filter for importance here.
+Done when: all 22 items were applied.
+
+### Phase 3 — Deep Analysis
+
+Goal: catch what the checklist cannot.
+Actions: answer these 4 questions; each new issue joins the candidate list. Report conclusions only, not the chain of thought.
+1. What is the intent of this change?
+2. What are the possible failure modes?
+3. Are there edge cases the checklist didn't cover?
+4. Does this change affect other components?
+Done when: all 4 questions answered.
+
+### Phase 4 — Triage & Report (Stage 2)
+
+Goal: turn candidates into the final report.
+Actions: for each candidate — apply the Evidence Gate; assign Severity and Confidence per the definitions below; HIGH/MEDIUM confidence → Findings, LOW or ambiguous → Open Questions, gate failures → discard. Emit the Output Contract.
+Done when: every candidate is a Finding, an Open Question, or a discarded gate failure — and the report matches the Output Contract.
+
+## Review Checklist
+
+The parenthetical after each item is the DEFAULT severity for a violation. Shift one level only when the concrete failure mode matches a different severity definition, and state why (e.g., a parsing panic reachable from user input is CRITICAL even under a WARNING-labeled item).
+
+### Command & Callback Safety
+
+#### 1. Callback/Interaction Data Format (CRITICAL)
+- All callback data follows a consistent prefix:action:params pattern
+- Platform limits respected: Telegram 64 bytes, Discord 100 chars for custom_id
+- New prefixes/identifiers defined as named constants, not string literals
+- Complex payloads stored server-side with short reference ID in callback data
+
+#### 2. Callback Data Parsing (WARNING)
+- String splitting always checks `len(parts)` before accessing indices
+- Integer/ID parsing handles errors (no panic on malformed data)
+- Bounds checks before array access: `if len(parts) < N { return }`
+- Helper functions return `(value, error)`, never panic
+
+#### 3. Command Registration (SUGGESTION)
+- All commands registered with the platform (Telegram: `SetMyCommands`, Discord: `ApplicationCommand`)
+- Command descriptions are concise and match actual behavior
+- Slash commands (Discord/Slack) have proper option types and validation
+
+### State Machine & Session Management
+
+#### 4. State Machine Consistency (CRITICAL)
+- All states have valid transitions — no orphaned or dead-end states
+- State diagram is documented or inferable from code
+- State transitions are atomic (no partial state updates)
+- Expired/stale state handled gracefully (e.g., "session expired" message)
+
+#### 5. Concurrent State Access (CRITICAL)
+- In-memory state maps protected by mutex (or use concurrent-safe map)
+- Lock/unlock balance verified — every `Lock()` has matching `Unlock()` (prefer `defer`)
+- No lock held across async/await boundaries (deadlock risk)
+- Actor verification: state belongs to the correct user (prevent cross-user state leaks)
+
+#### 6. State Cleanup (WARNING)
+- Transient state cleaned up after use (completed conversations, expired sessions)
+- `/start` or equivalent resets all in-memory state for the chat
+- State TTL or periodic cleanup prevents unbounded memory growth
+- Item/entity ID in state matches current context before acting
+
+### Message & UI Handling
+
+#### 7. Message Editing vs Sending (WARNING)
+- Callback/interaction handlers edit the existing message, not send new ones (prevents chat clutter)
+- Exception: media groups and ephemeral messages must be sent as new messages
+- Platform constraints respected (e.g., Telegram: can't edit message type, Discord: ephemeral follow-ups)
+
+#### 8. Keyboard/Button Cleanup (WARNING)
+- Every callback handler acknowledges the interaction (Telegram: `AnswerCallbackQuery`, Discord: `deferUpdate/reply`)
+- After processing: keyboard edited or removed to prevent stale buttons
+- Idempotency: check entity status before acting (already processed -> show "completed" message)
+- Platform timeout respected (Telegram: 30s for callback answer, Discord: 3s for initial response)
+
+#### 9. Message Formatting (SUGGESTION)
+- Consistent text format (plain text vs Markdown vs HTML) — pick one and stick to it
+- Special characters escaped if using Markdown/HTML (prevents parse errors)
+- Messages respect platform length limits (Telegram: 4096 chars, Discord: 2000 chars)
+- Long messages split or paginated, not truncated silently
+
+#### 10. Inline Keyboard Layout (SUGGESTION)
+- Maximum 3-4 buttons per row for mobile readability
+- Action buttons (confirm/cancel) on separate rows from navigation
+- Button text is concise (long text wraps poorly on mobile)
+- Use platform's keyboard builder utilities, not raw construction
+
+### Error Handling & Resilience
+
+#### 11. Bot API Error Handling (WARNING)
+- All bot API calls wrapped with error logging (structured fields: error, chat_id, context)
+- Retryable errors (429/rate limit) handled with backoff
+- Permanent errors (403/user blocked bot, 400/bad request) handled distinctly
+- Graceful degradation: on API error, send user-friendly message, don't crash
+
+#### 12. Error Specificity (WARNING)
+- Platform-specific error codes checked (not just generic error string)
+- Telegram: distinguish 403 (blocked), 429 (rate limit), 400 (bad request)
+- Discord: handle `DiscordAPIError` codes, interaction expired errors
+- Error logging includes platform error code and description
+
+#### 13. Graceful Shutdown (WARNING)
+- Update channel/websocket properly closed on shutdown
+- Telegram: `StopReceivingUpdates()` in defer or shutdown hook
+- Discord: `client.close()` or equivalent
+- HTTP webhook server has `Shutdown(ctx)` with timeout
+
+### Security & Access Control
+
+#### 14. Role-Based Access (CRITICAL)
+- All handler entry points verify user permissions before executing
+- Admin-only actions (ban, configure, manage) require explicit role check
+- Callback handlers resolve permissions BEFORE executing action
+- Unknown/unauthorized users get "access denied", not silent failure
+
+#### 15. Webhook Security (CRITICAL)
+- Webhook URL uses HTTPS only
+- Telegram: `SecretToken` header validation on incoming webhooks
+- Discord: Ed25519 signature verification on interaction endpoints
+- Slack: request signing verification (`x-slack-signature`)
+- Long-polling: `AllowedUpdates` set to only needed update types
+
+#### 16. Input Validation (WARNING)
+- User-provided text sanitized before use in database queries, API calls, or message formatting
+- File uploads validated (type, size) before processing
+- URL inputs validated before fetching (SSRF prevention)
+- No `eval`/`exec` on user input
+
+### Production Safety
+
+#### 17. Goroutine/Thread/Task Safety (CRITICAL)
+- Handlers spawning background tasks use context with timeout/cancellation
+- No fire-and-forget goroutines/tasks without error handling
+- Channel/queue reads have timeout case (prevent indefinite blocking)
+- Async tasks properly awaited or tracked for cleanup on shutdown
+
+#### 18. Rate Limit Awareness (WARNING)
+- Message-sending loops use rate limiter or inter-message delays
+- Platform limits known: Telegram 30 msg/s global + 20 msg/min per chat, Discord 50 req/s
+- Notification fan-out without rate limiting flagged as issue
+- 429 responses handled with `Retry-After` backoff
+
+#### 19. Audit Logging (SUGGESTION)
+- Administrative actions logged (who, what, when, target)
+- Moderation decisions logged with actor ID, target ID, action, reason
+- Audit errors logged as warnings, not propagated to user
+- Sensitive data (tokens, passwords) never logged
+
+#### 20. Testability (SUGGESTION)
+- Bot logic separated from platform API transport
+- Handlers accept interfaces (e.g., `BotSender`), not concrete API client types
+- State machines testable independently of message handling
+- Test files exist for bot handlers and state machines
+
+#### 21. Debug Output (SUGGESTION)
+- No `fmt.Print`/`print()`/`console.log` in production code — use structured logger
+- Log levels appropriate (debug for verbose, info for operations, warn for recoverable, error for failures)
+- No sensitive data in log output (tokens, user messages, PII)
+
+#### 22. Configuration (SUGGESTION)
+- Bot token loaded from environment variable, not hardcoded
+- Configurable timeouts, rate limits, and retry counts
+- Feature flags for experimental commands
+- Environment-specific config (dev/staging/prod)
+
+## Severity & Confidence
+
+- **CRITICAL** — data loss, security vulnerability, or crash. Example: missing role check, state machine deadlock, callback data overflow, webhook without signature verification.
+- **WARNING** — incorrect behavior under specific conditions, performance degradation. Example: missing error wrap, stale state not cleaned up, rate limit not enforced.
+- **SUGGESTION** — style/readability, safe to ignore. Example: variable naming, message text improvement, button layout.
+
+Confidence — HIGH (≥80): bug visible in the code · MEDIUM (60–79): pattern-based, mark "needs verification" · LOW (<60): route to Open Questions, never silently drop.
+
+## Output Contract
+
+```
+## Bot Review Report
+
+**Platform**: <platform> · <library> (or "unknown — generic checks applied")
+**Files reviewed**: <list>
+**Summary**: <X> CRITICAL · <Y> WARNING · <Z> SUGGESTION · <N> Open Questions
+
+### Findings
+[SEVERITY/CONFIDENCE] file:line — one-line description
+  Evidence: <what the code shows>
+  Fix: <concrete change>
+
+### Open Questions
+LOW-confidence or ambiguous items — listed, not dropped:
+- file:line — what you suspect + what context would confirm it
+(write "None" if empty)
+
+### Verdict
+<1-2 sentences. If clean: "No CRITICAL or WARNING issues found in the reviewed files.">
+```
+
+Example finding:
+
+```
+[CRITICAL/HIGH] handlers/callback.go:42 — callback data split without length check
+  Evidence: parts := strings.Split(data, ":") then parts[2] is read with no len(parts) guard; a truncated callback ("vote:") panics the handler
+  Fix: if len(parts) < 3 { answerCallback(q, "expired"); return }
+```
+
+## Done ONLY when
+
+- [ ] Platform detection ran (Phase 1) and the result is stated in the report header.
+- [ ] All 22 checklist items were applied to the target files (Phase 2).
+- [ ] All 4 deep-analysis questions were answered (Phase 3).
+- [ ] Every reported finding passed the 4-point Evidence Gate.
+- [ ] Report matches the Output Contract, with the Open Questions section present (even if "None").
+
+## Recap — non-negotiables
+
+- Every finding cites a `file:line` you actually Read this session — no citation, no finding.
+- LOW-confidence or ambiguous items go to Open Questions, never dropped.
+- Canonical enums only: CRITICAL/WARNING/SUGGESTION · HIGH (≥80)/MEDIUM (60–79)/LOW (<60).
+- Do NOT inflate severity to seem thorough: a review with 0 CRITICAL findings and 2 SUGGESTIONS is perfectly valid. If the code is clean, say so.