AtlasOmnia/donna-starter

# Apple Reminders

Use `remindctl` to manage Apple Reminders directly from the terminal. Tasks sync across all Apple devices via iCloud.

## Prerequisites

- **macOS** with Reminders.app
- Install: `brew install steipete/tap/remindctl`
- Grant Reminders permission when prompted
- Check: `remindctl status` / Request: `remindctl authorize`
- If macOS reports Full Access but `remindctl status` still says `Not determined` or `Denied`, test AppleScript instead:
 ```bash
 osascript -e 'tell application "Reminders" to return name of every list'
 ```
 If AppleScript works, use Reminders AppleScript as a fallback for list/read/create operations; the TCC grant may apply to Terminal/Python but not the `remindctl` binary context.

# iMessage

Use `imsg` to read and send iMessage/SMS via macOS Messages.app.

## Prerequisites

- **macOS** with Messages.app signed in
- Install: `brew install steipete/tap/imsg`
- Grant Full Disk Access for terminal (System Settings → Privacy → Full Disk Access)
- Grant Automation permission for Messages.app when prompted

## When to Use

- User asks to send an iMessage or text message
- Reading iMessage conversation history

# macOS App Automation

Use this skill when the user asks whether Hermes can control a native macOS app, or asks you to verify, configure, or troubleshoot AppleScript/Automation access for an app.

## Preferred automation ladder

1. AppleScript dictionary / app scripting API
 - Best for structured app data and repeatable operations.
 - Verify with the app's bundle ID, version, and scripting dictionary before promising coverage.
2. App URL scheme
 - Good for quick-add or deep-link actions when documented by the app.
3. System Events / Accessibility scripting
 - Useful for menu items and UI operations not exposed in the app dictionary.
4. Hermes `computer_use`
 - Last-resort GUI operation for UI-only features. Capture first, click by element index, verify after state changes.

# macOS Storage Management

Safely reclaim local Mac storage without mistaking cloud placeholders for resident data, losing File Provider content, or flattening metadata onto an incompatible external filesystem.

## Trigger

Load this skill when the user asks to free space on a Mac, move Documents/Desktop/Downloads to an external SSD, archive iCloud/File Provider folders, migrate between APFS and ExFAT, or explain conflicting Finder, `du`, and `df` storage figures.

## Safety Principles

1. **Measure the live Data volume, not only `/`.** On modern macOS, use `df -h "$HOME"` because `/System/Volumes/Data` carries user data.
2. **Inspect the destination filesystem before choosing a copy method.** ExFAT does not preserve native macOS symlinks, ownership, permissions, extended attributes, resource forks, or every filename semantic.
3. **Treat File Provider folders specially.** A logical file can be `dataless` with zero allocated blocks. Its apparent size is not reclaimable local space until downloaded.
4. **Never delete on a partial copy.** Copy/archive, independently verify, re-check source identity/state, then remove only verified source objects.
5. **Do not force cloud hydration onto a critically full disk.** If placeholders materially exceed free space, move only resident files or free space elsewhere first.

# Hermes Agent

Hermes Agent is an open-source AI agent framework by Nous Research that runs in your terminal, messaging platforms, and IDEs. It belongs to the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Hermes works with any LLM provider (OpenRouter, Anthropic, OpenAI, DeepSeek, local models, and 15+ others) and runs on Linux, macOS, and WSL.

What makes Hermes different:

- **Self-improving through skills** — Hermes learns from experience by saving reusable procedures as skills. When it solves a complex problem, discovers a workflow, or gets corrected, it can persist that knowledge as a skill document that loads into future sessions. Skills accumulate over time, making the agent better at your specific tasks and environment.
- **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends (built-in, Honcho, Mem0, and more) let you choose how memory works.
- **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Email, and 10+ other platforms with full tool access, not just chat.
- **Provider-agnostic** — swap models and providers mid-workflow without changing anything else. Credential pools rotate across multiple API keys automatically.
- **Profiles** — run multiple independent Hermes instances with isolated configs, sessions, skills, and memory.
- **Extensible** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, and the full Python ecosystem.

People use Hermes for software development, research, system administration, data analysis, content creation, home automation, and anything else that benefits from an AI agent with persistent context and full system access.

# Hermes Config Editing

Edit `~/.hermes/config.yaml` values reliably, working around the security guard that blocks direct file edits and CLI commands that don't persist for nested keys.

## The Problem

- **Security guard**: Direct `patch`/write_file on `config.yaml` is blocked — "security-sensitive configuration". Agent must not treat it as a normal file.
- **CLI doesn't work for all keys**: `hermes config set compression.threshold 0.80` runs without error but often fails to persist changes (especially nested YAML paths).
- **switch-provider.py may be missing**: AGENTS.md historically references it, but it can be removed or moved after updates. Never assume it exists; verify with `ls` before relying on it. If missing, fall back to manual config edits via the patterns below.

## Reliable Pattern: Inspect, Then Minimal Section-Aware Edit

Use the Hermes venv Python to inspect and validate YAML, but prefer targeted text edits for `config.yaml` so comments and ordering survive.

```bash

# Hermes Context Optimization

Use this when the user asks about Hermes prompt/context size, “hello” startup cost, compression behavior, memory/profile bloat, tool-schema overhead, skill loading, session-store/search-index storage, or multimodal/visual-context approaches such as Snapcompact.

For large `state.db` search-index maintenance, resumable `optimize-storage --no-vacuum` runs, foreground timeout handling, and post-run verification, follow `references/session-store-optimization.md`.

When bounded workers repeatedly fail with `session_persistence_failed` because a live profile DB is lock-contended, preserve the worktree handoff and use the non-disruptive isolated-`HERMES_HOME` workflow in `references/isolated-worker-state-store.md`. Diagnose the profile-specific DB and lock owners first; never terminate a user's live TUI or optimize its store merely to unblock a coding worker.

## Operating style for the user

- Be concise first. If he asks for the savings, give the numbers, not a lecture.
- Separate **hard blockers** from **engineering choices**.
- Prefer token/accounting estimates grounded in actual provider/runtime data when available; use ratios only when clearly labeled.
- Do not imply that all startup prompt text is interchangeable. Bucket it by runtime role.

# Hermes Overnight Autonomy

Use this skill when the user asks for Hermes projects to continue across the night, gateway restarts, worker failures, or 24/7 operation. The target is durable progress with bounded risk—not a tower of supervisors.

## Architecture decision

Use **Kanban as the durable execution kernel**:

- SQLite-backed cards preserve task bodies, dependencies, claims, heartbeats, run history, comments, retries, and circuit-breaker state.
- The gateway-embedded dispatcher is the normal scheduler and stale-claim reclaimer.
- Each unattended card has an explicit runtime cap, retry budget, named assignee, workspace, and acceptance contract.
- A separate OS-supervised watchdog provides liveness and alerting when the gateway or dispatcher is unavailable.
- Recovery remains disabled during calibration. Do not add a standalone Kanban daemon against the same board database or multiple competing relaunchers.

Kanban solves durable task lifecycle and dead-worker redispatch; it does not prove meaningful progress, resume in-memory reasoning, judge code quality, substitute models automatically, or survive total gateway loss by itself.

# Hermes Plugin Evaluation

Use this when the user asks about installing, trusting, pricing, or using a third-party Hermes Agent plugin or integration.

## Goal

Give a practical go/no-go read before touching the live Hermes gateway. Separate:

- **Plugin code cost/license** — whether the repository itself is public/open-source/free to install.
- **Service cost** — required SaaS account, usage billing, phone/SMS/voice costs, model API costs, tunnels, hosted routing, or paid feature gates.
- **Operational risk** — what data leaves Hermes, whether the plugin opens public webhooks/tunnels, and whether it modifies gateway behavior.

## Fast evaluation workflow

1. **Load authoritative Hermes context first** when the task involves Hermes plugins:

# Hermes Session Maintenance

Use this skill when the user asks about pruning Hermes sessions, session retention, session DB size, `hermes sessions prune`, `sessions.auto_prune`, `sessions.retention_days`, session export/backup, or whether old conversations should be capped.

## Operating principles

- Treat this as Hermes configuration/maintenance work. If broader Hermes setup or CLI behavior is involved, also load `hermes-agent` for authoritative command references.
- Do not assume retention policy from memory. Check live state before recommending destructive cleanup.
- Pruning is deletion. Prefer exporting a safety snapshot before the first aggressive prune or before reducing retention substantially.
- Distinguish default behavior from active behavior:
 - `hermes sessions prune` defaults to `--older-than 90`.
 - `sessions.retention_days` may also default to 90.
 - `sessions.auto_prune: false` means nothing is being deleted automatically.
- Only ended sessions are prune candidates; active sessions are not pruned.

# Local Model Selection for Hermes

Use this skill when the user asks which local model to run, which quant to pick, which uncensored variant to use, how to pair models across GPUs, or what auxiliary model to use alongside their main model.

## When to use

Trigger on requests like:
- "what's the best Qwen model for my hardware"
- "which quant should I use for 32GB VRAM"
- "what uncensored model for 16GB"
- "what should I run as a secondary/auxiliary model"
- "compare these three models for agent use"
- "is this model still the best or has something newer dropped"
- "where are my LM Studio models"
- "move/delete these LM Studio models to free space"

# OpenCode CLI

Use [OpenCode](https://opencode.ai) as an autonomous coding worker orchestrated by Hermes terminal/process tools. OpenCode is a provider-agnostic, open-source AI coding agent with a TUI and CLI.

## When to Use

- User explicitly asks to use OpenCode
- You want an external coding agent to implement/refactor/review code
- You need long-running coding sessions with progress checks
- You want parallel task execution in isolated workdirs/worktrees

## Prerequisites

- OpenCode installed: `npm i -g opencode-ai@latest` or `brew install anomalyco/tap/opencode`
- Auth configured: `opencode auth login` or set provider env vars (OPENROUTER_API_KEY, etc.)

# Computer Use (universal, any-model, cross-platform)

You have a `computer_use` tool that drives the user's desktop in the
**background** — your actions do NOT move the user's cursor, steal
keyboard focus, or switch virtual desktops / Spaces. The user can keep
typing in their editor while you click around in a browser in another
window. This is the opposite of pyautogui-style automation.

Everything here works with any tool-capable model — Claude, GPT, Gemini,
or an open model on a local OpenAI-compatible endpoint. There is no
Anthropic-native schema to learn.

Hermes drives [cua-driver](https://github.com/trycua/cua) under the hood
for the platform plumbing. The Hermes-side `computer_use` tool exposed
in this skill is a higher-level Hermes vocabulary; the raw cua-driver

# Claude Design for CLI/API Agents

Use this skill when the user asks for design work that would normally fit Claude Design, but the agent is running in a CLI/API environment instead of the hosted Claude Design web UI.

The goal is to preserve Claude Design's useful design behavior and taste while removing hosted-tool plumbing that does not exist in normal agent environments.

**Before starting, check for other web-design skills like `popular-web-designs` (ready-to-paste design systems for Stripe, Linear, Vercel, Notion, etc.) and `design-md` (Google's DESIGN.md token spec format).** If the user wants a known brand's look, load `popular-web-designs` alongside this one and let it supply the visual vocabulary. If the deliverable is a token spec file rather than a rendered artifact, use `design-md` instead. Full decision table below.

## When To Use This Skill vs `popular-web-designs` vs `design-md`

Hermes has three design-related skills under `skills/creative/`. They do different jobs — load the right one (or combine them):

| Skill | What it gives you | Use when the user wants... |
|---|---|---|
| **claude-design** (this one) | Design *process and taste* — how to scope a brief, gather context, produce variants, verify a local HTML artifact, avoid AI-design slop | a from-scratch designed artifact (landing page, prototype, deck, component lab, motion study) with no specific brand or token system dictated |

# Content Style: r/hermesagent & Community Posts

## Overview

Writing Reddit-native content that sounds human, avoids AI tells, and delivers value through structure and specificity. Applies to workshop posts, definitive model guides, research megathreads, and community FYI/update posts.

## Hook Patterns

Lead with one of these:
1. **Contradiction** — "Everyone says X but Y is actually true"
2. **Specific number** — "The 3 tools I use daily"
3. **Pain point** — "If you're doing X, stop"
4. **Before/after** — "Before: Y. After: Z"
5. **Question** — "Why does X still suck?"

# Marketing Collateral Design

## Overview

Use this skill to create professional static promotional graphics whose typography, claims, and contact details must remain exact. The core production rule is **hybrid, not one-shot**: generate or source imagery separately, then compose real text and vector elements deterministically in HTML/CSS/SVG. Image models are art departments, not typesetters.

The default deliverable is a self-contained HTML source plus rendered PNG and PDF when the format requires them. Use PowerPoint only when the user explicitly needs routine editing by nontechnical staff. Use a native design tool only when the user requests that source format or the printer requires it.

Read the supporting files when relevant:

- Production specifications
- Visual QA rubric
- Imagery and asset guidance
- [Archetype-neutral canvas](templates/canvas.html) — default starting point
- [Image-led flyer example](templates/flyer.html) — example only, not a universal layout

# Dogfood: Systematic Web Application QA Testing

## Overview

This skill guides you through systematic exploratory QA testing of web applications using the browser toolset. You will navigate the application, interact with elements, capture evidence of issues, and produce a structured bug report.

## Prerequisites

- Browser toolset must be available (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_vision`, `browser_console`, `browser_scroll`, `browser_back`, `browser_press`)
- A target URL and testing scope from the user

## Inputs

The user provides:
1. **Target URL** — the entry point for testing

# Codebase Inspection with pygount

Analyze repositories for lines of code, language breakdown, file counts, and code-vs-comment ratios using `pygount`.

## When to Use

- User asks for LOC (lines of code) count
- User wants a language breakdown of a repo
- User asks about codebase size or composition
- User wants code-vs-comment ratios
- General "how big is this repo" questions

## Prerequisites

```bash

# GitHub Authentication Setup

This skill sets up authentication so the agent can work with GitHub repositories, PRs, issues, and CI. It covers two paths:

- **`git` (always available)** — uses HTTPS personal access tokens or SSH keys
- **`gh` CLI (if installed)** — richer GitHub API access with a simpler auth flow

## Detection Flow

When a user asks you to work with GitHub, run this check first:

```bash
# Check what's available
git --version
gh --version 2>/dev/null || echo "gh not installed"

# GitHub Code Review

Perform code reviews on local changes before pushing, or review open PRs on GitHub. Most of this skill uses plain `git` — the `gh`/`curl` split only matters for PR-level interactions.

## Prerequisites

- Authenticated with GitHub (see `github-auth` skill)
- Inside a git repository

### Setup (for PR interactions)

```bash
if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 AUTH="gh"
else

# GitHub Issues Management

Create, search, triage, and manage GitHub issues. Each section shows `gh` first, then the `curl` fallback.

## Prerequisites

- Authenticated with GitHub (see `github-auth` skill)
- Inside a git repo with a GitHub remote, or specify the repo explicitly

### Setup

```bash
if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 AUTH="gh"
else

# GitHub Pull Request Workflow

Complete guide for managing the PR lifecycle. Each section shows the `gh` way first, then the `git` + `curl` fallback for machines without `gh`.

## Prerequisites

- Authenticated with GitHub (see `github-auth` skill)
- Inside a git repository with a GitHub remote

### Quick Auth Detection

```bash
# Determine which method to use throughout this workflow
if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 AUTH="gh"

# Pre-Push Quality Gates

Before pushing a branch to a shared remote, run through these gates. They prevent pushing credentials, PII, private history, or a broken tree. The skill covers the pre-PR quality phase — use `github-pr-workflow` for the PR lifecycle itself.

## Dependency audit interpretation

- The standard production gate is `npm audit --omit=dev --audit-level=high`, but a zero result there does not clear a vulnerable developer toolchain. Run the full audit too when the repository ships or executes from source.
- Separate lockfile evidence from installed-tree evidence. `npm audit --package-lock-only` can pass while stale `node_modules` still reports old versions; use a clean `npm ci` in CI and then run ordinary `npm audit` before declaring the dependency fix verified.
- If a patched transitive version requires an override, verify every resolved package path and exercise tests/build/validation. Do not use `npm audit fix --force` without reviewing proposed major downgrades and behavior changes.

## Workflow overview

```text
[code complete] → [immutable verification] → [privacy scan] → [reviewer] → [push + SHA verify] → [PR]
```

# GitHub README and Documentation Maintenance

Use this skill for edits where the goal is to keep repository-facing Markdown documentation accurate, current, and review-friendly.

## Scope

Apply this skill when editing:

- `README.md` and similar top-level docs
- `AGENTS.md`, `CLAUDE.md`, and other agent-facing repository guidance
- Community megathread catalogs or link indexes
- Repository runbooks, contribution guidance, and operational playbook docs

For agent-facing guidance, document stable architecture, ownership boundaries, generated-file rules, safety invariants, and executable verification commands. Do not copy temporary campaign state, process IDs, review generations, or acceptance SHAs into durable repository instructions.

# GitHub Repository Management

Create, clone, fork, configure, and manage GitHub repositories. Each section shows `gh` first, then the `git` + `curl` fallback.

## Prerequisites

- Authenticated with GitHub (see `github-auth` skill)

### Setup

```bash
if command -v gh &>/dev/null && gh auth status &>/dev/null; then
 AUTH="gh"
else
 AUTH="git"

# GitHub Workflows

Use this skill for the full GitHub operating loop:
1) authenticate, 2) manage repos and remotes, 3) open and review PRs, 4) work on issues, and 5) monitor CI.

## Why this umbrella exists

The old project-specific skills (`github-auth`, `github-repo-management`, `github-pr-workflow`, `github-issues`, `github-code-review`) all target the same operational domain: repository setup, PR lifecycles, issue triage, and review. Consolidating them avoids fragmented workflows and makes the sequence from local repo state to merged code explicit.

## Core entrypoints

1. **Authentication first**
 - Set up GitHub access with `gh` where available, or token-based/SSH fallback.
 - Confirm auth method before attempting repo/PR operations.

# Local App GitHub Publishing

Use this when the user asks to push a local app/prototype/project to GitHub for the first time, especially Electron, iOS/Xcode, mobile, desktop, or AI/API-integrated apps.

This skill complements the protected `github-repo-management` skill with the user-specific first-push hygiene: publish the useful source, not the machine's junk drawer wearing a trench coat.

## Core Rule

Before the first commit, sanitize and verify. Generated builds, dependency folders, local Xcode state, and API credentials do not belong in the initial history.

## Default Behavior

- **Default visibility: private** unless the user explicitly asks for public.
- Use a simple repo name matching the user's wording when possible, normalized to GitHub style, e.g. “iOS translator” → `ios-translator`.
- If the repo name exists, choose the closest available variant only if the user gave broad wording; otherwise ask.

# Meal Tracker

Log meals from a photo or a text description, track calories and macros against the user's daily budget, and keep a dated markdown food log.

## Setup (ask once, then remember)

- **Daily calorie target** and optional macro targets (protein/fat/carbs in grams).
- **Log location** — the user's notes app or a folder (for example an Obsidian vault, `~/Food Logs`, or their notes directory). Ask once; do not assume a path.
- If the user later changes the target, update the stored value and the current log header.

## Meal logging workflow

### Photo input (user sends image)
1. Use `vision_analyze` with the image — ask: "Identify each food item, estimate portion sizes in common units (oz, cups, pieces), and provide calorie + macro breakdown per item."
2. If the photo is clearly a **Nutrition Facts label**, skip broad estimation and use the exact visible label values: serving size, calories, protein, fat, carbs, and useful notes (sodium/fiber/sugar). Treat one visible bag/container as one serving unless the user says otherwise.

# Hermes Desktop Plugins Skill

Write plugins for the Hermes desktop app: statusbar items, layout panes,
command-palette commands, keybinds, routes, and themes. A plugin is a single
plain-JavaScript ESM file the app loads at runtime — no build step, no repo
changes. A plugin can also talk to its own Python backend namespace
(`ctx.rest`/`ctx.socket` → `/api/plugins/<id>`); the general Python plugin
system (`~/.hermes/plugins/`) is otherwise documented separately.

Full human reference (every export, area payloads, backend, security):
`website/docs/developer-guide/desktop-plugin-sdk.md`.

## When to Use

- The user asks for a new desktop UI element (a pane, a statusbar widget, a

# Hermes Nightly Self-Check — Decisions Log

Purpose: Record decisions made from hermes-nightly-self-check findings so behavior is consistent across sessions.

## How to record

Each entry captures one finding and the decision it produced. Use this format:

```markdown
### YYYY-MM-DD — Short issue title (Issue #N)
- Issue: What the self-check flagged — the symptom, where it came from, and why it happened.
- Decision: The rule or fix chosen, stated so a future session can apply it without re-litigating.
```

Rules:

# Hermes Plugin Development

Use when: creating, debugging, or integrating Hermes Agent plugins, including Python backend plugins (tools, hooks, routers, middleware) and JavaScript Hermes Desktop runtime plugins.

## Core patterns

- Choose the extension surface first:
 - Backend plugins live under `~/.hermes/plugins/<name>/` and add tools, hooks, commands, providers, or middleware.
 - Desktop runtime plugins live under `$HERMES_HOME/desktop-plugins/<name>/plugin.js` and add native UI contributions through `@hermes/plugin-sdk`. For model-picker specifics, including a Desktop-local `/switch` command plus backend command-inventory bridge, use `references/desktop-model-picker-plugin.md`.
- Resolve the requested interaction surface before building anything. “TUI,” “terminal,” “over SSH,” or “from Windows over SSH” means the prompt_toolkit CLI, not Hermes Desktop. Never substitute a Desktop popover or a backend text-response command.
- Backend plugin slash handlers return text; they cannot open a prompt_toolkit modal. For a TUI command that opens an existing picker, prefer a central command alias or an update-safe `quick_commands` alias. If the user requires an explicit Session/Global step, aliasing to bare `/model` is insufficient because the standard picker follows its persistence default; extend the TUI picker state with a scope stage and verify that scope reaches the final switch call. For live verification, use a fresh CLI under tmux, synchronize on the visible composer, capture each modal stage, then repeat through the user's real SSH path; do not mistake raw PTY repaint fragments for a product failure. See `references/tui-model-picker-slash-command.md`.
- Desktop-only slash-like UI commands may use a two-surface integration: composer middleware opens/cancels locally, while an enabled Python backend plugin registers inventory/autocomplete and a non-Desktop fallback. Middleware receives a `{ text, attachments }` draft object—never test it with raw strings. This pattern does not satisfy TUI/SSH requests.
- Backend plugins use:
 - `__init__.py`: Python code + hook implementations
 - `plugin.yaml`: metadata + hook declarations

# Hermes Themes Skill

Author a Hermes **skin** — one YAML file that themes the CLI, the TUI, and the
desktop GUI at once. The skin engine (`hermes_cli/skin_engine.py`) resolves the
active skin and the gateway pushes it to every surface, so a file dropped in
`~/.hermes/skins/` is the theme analogue of a plugin: no code, all surfaces. This
skill covers writing a good skin and activating it; it does not build GUI theme
editors or ship built-in presets.

## When to Use

- The user asks for a custom look ("make me a synthwave theme", "dark forest
 vibes", "match my brand colors") for Hermes itself.
- The user wants the CLI/TUI/desktop to share one coordinated palette.
- The user wants to iterate live ("that coral is too loud, make it teal") — edit

# Hermes Mnemosyne Memory Provider

Mnemosyne is Hermes' primary local-first memory engine — SQLite with vector + FTS5 hybrid search, 19+ tools, auto-consolidation, and a standalone CLI. It's a pip-installed plugin (not a built-in toolset) discovered via `$HERMES_HOME/plugins/mnemosyne/`.

## Quick Reference

When comparing memory stacks for the user, use `references/memory-tool-selection-mem0-vs-mnemosyne.md`: Mnemosyne is preferred for Hermes local-first profile memory; Mem0 is the safer productized choice for external/customer-facing apps.

For migrations from overlapping stacks such as LCM + built-in memory + gBrain, use `references/memory-stack-migration-pilot.md`. Prefer a staged simplification: preserve LCM, pilot Mnemosyne as the external memory provider, keep the incumbent system read-only for rollback, and retire redundant writers after measured acceptance.

| What | How |
|---|---|
| Check if active | `hermes memory status` or check `memory.provider` in config.yaml |
| Memory stats | `mnemosyne stats` (CLI) or `mnemosyne_stats` (tool) |
| Manual consolidation | `mnemosyne sleep` (current session) or `mnemosyne sleep --all-sessions` |

# Hermes Self-Evaluation

Use this skill when the user asks to audit, review, or optimize Hermes's own performance — analyzing session data, skills, configuration, costs, and usage patterns to identify improvements, automation opportunities, and system optimizations.

**Don't use for:** skill content quality grading (use skill-auditor instead), one-off task analysis, or session artifact indexing after a work session (use session-artifact-indexing).

## Overview

The core workflow: gather live evidence about Hermes's state and history → validate each finding against the subsystem's actual semantics and control surface → either produce a direct evidence-backed review or compose a structured analyst prompt for an independent model → verify recommendations before implementation.

External models are useful anomaly detectors and critics, but they are not automatically reliable root-cause analysts. Separate the observed symptom, supported interpretation, confirmed producer/root cause, and proposed change. Before acting on any self-check finding,

## When to Use

Triggers:

# Hermes Starter Onboarding

## Overview

Use this skill to turn a blank or lightly configured Hermes profile into a setup chosen by its owner. The workflow is conversational and consent-gated: learn the user's identity and priorities, recommend a small capability bundle, show the proposed changes, apply only what the user approves, and verify the result.

This is a **capability planner**, not a blind installer. A Hermes toolset exposes a capability, a skill provides operating instructions, a plugin or MCP server provides an integration, and a desktop application such as Obsidian is a separate dependency. Explain that distinction in plain language when it matters.

The setup must work for a public starter profile. Never assume the user's name, location, timezone, businesses, accounts, vault paths, tickers, health history, credentials, or preferred assistant name. Ask instead.

## When to Use

- A new user starts a Donna or other Hermes starter profile.
- The user says "set me up," "configure my assistant," "what tools should I enable," or asks what Hermes can connect to.
- The user wants to choose memory, notes, browser, terminal, voice, calendar, reminders, email, or other integrations.

# Messaging Gateway Troubleshooting

Use this when Hermes messaging platforms are installed/configured but messages do not arrive, are ignored, do not reply, or appear to risk reply loops.

## Operating principles

1. Verify the live path end to end before assuming config is wrong:
 - Gateway service is running.
 - Platform server/client is running.
 - Local webhook/listener is bound.
 - Health endpoint responds if available.
 - Platform has the webhook registered.
 - Gateway logs show the adapter connected.
2. Separate transport, authorization, and adapter filtering:
 - Transport failure: no webhook hit / listener closed.

# Mnemosyne Maintenance

Use when: upgrading Mnemosyne, diagnosing slow/hung consolidation (mnemosyne_sleep), fixing missing embeddings, or troubleshooting import/version mismatches.

## Triggers

- mnemosyne_sleep hanging for >2 minutes
- Diagnose reports "fastembed not available" or "sqlite_vec not available" despite being installed
- Version mismatch: pip shows newer version than runtime
- Embeddings_available=NO when deps are present

## Core troubleshooting (in order)

1. Run diagnostics:
 - mnemosyne_diagnose

# Skill Auditor — Quality Grading System (A–F)

Audit any Hermes skill file and assign a quality grade based on clarity, completeness, tool guidance, and shareability. Returns specific fix suggestions ranked by impact.

## When to Use

- User asks you to review, audit, or grade a skill
- You're about to create a new skill and want to validate the draft
- A skill is behaving unreliably (agent skips it, calls wrong tools, misses steps)
- User shares a skill file or path for feedback
- You're preparing skills for sharing with others

**Don't use for:** general Hermes troubleshooting, model selection, config review — those have their own skills.

## Grading Criteria

# Daily Note Wrap-Up Workflow

Use this skill for evening wrap-up work that creates tomorrow's daily note and updates the monthly daily-note index.

## Core rules
- Treat the requested daily-note structure as a contract; preserve section order exactly.
- Carry forward incomplete work into tomorrow's note.
- On weekends, omit any work-specific section (for example `### [Work]`) entirely rather than leaving an empty heading or placeholder bullet.
- If a section has nothing to place, follow the user's exact omission rule for that section rather than inventing filler text.
- Keep today's note untouched; only create or update tomorrow's note and the monthly index.
- Serialize all mutations to the same file. Never launch parallel patches against one note or monthly index; combine related edits into one cohesive patch when practical, or patch sequentially with a read-back between changes.

## Structure gotchas
- The daily note template is not a generic form: match the user's requested headings and ordering exactly, including weekend-only omissions.
- Do not leave a blank `### [Work]` heading on weekends; remove the section entirely.

# Obsidian Vault

Use this skill for filesystem-first Obsidian vault work: reading notes, listing notes, searching note files, creating notes, appending content, and adding wikilinks.

## Vault path

Use a known or resolved vault path before calling file tools.

The documented vault-path convention is the `OBSIDIAN_VAULT_PATH` environment variable, for example from `~/.hermes/.env`. If it is unset, use `~/Documents/Obsidian Vault`.

File tools do not expand shell variables. Do not pass paths containing `$OBSIDIAN_VAULT_PATH` to `read_file`, `write_file`, `patch`, or `search_files`; resolve the vault path first and pass a concrete absolute path. Vault paths may contain spaces, which is another reason to prefer file tools over shell commands.

If the vault path is unknown, `terminal` is acceptable for resolving `OBSIDIAN_VAULT_PATH` or checking whether the fallback path exists. Once the path is known, switch back to file tools.

## Read a note

# Vault Organization

Audit and reorganize the user's Obsidian vault. Run when asked to organize, clean up, or audit the vault structure — or to set up a sensible structure for a new/empty vault.

## Vault path

Confirm the actual vault location first — do not assume `~/Documents/Obsidian Vault`. Ask or check Obsidian's settings if the path is not known.

## Structuring a vault (new or from scratch)

When the user asks "how should I organize my vault?" or is starting fresh, recommend a structure before touching anything. Use **PARA** as the default taxonomy — it maps cleanly onto how an assistant actually uses a vault:

- **Projects/** — short-lived efforts with a goal and an end (a trip, a launch, a repair). One folder per project; archive when done.
- **Areas/** — ongoing responsibilities with no end date (Health, Finance, Home, a business, a role). These persist and get maintained.
- **Resources/** — reusable reference material not tied to one project: research, guides, templates, snippets, "how I do X."

# Notes Automation Workflows

Use this skill for scripted, repeatable Apple Notes operations that go beyond single-note edits.

## When to use

- "Review my notes from last N days" or periodic cleanup/triage tasks.
- Adding structured summaries to notes that contain links.
- Adding summaries for image/photo notes.
- Updating notes programmatically without manual, one-by-one edits.
- Creating a translated or otherwise transformed copy of a rich-text note while preserving its structure.

## When *not* to use

- Single small edits: use the `memo`/`Notes` interactive flow directly.

# Product Competitor Analysis

## What this skill covers
Use this skill when asked to compare a local app/product to mainstream alternatives from local evidence only (or with explicit permission to use external research). It is intentionally structured for **code-first competitive assessments** where output should cite files, line ranges, and concrete implementation details.

## Core principle
Every claim in the final analysis must be traceable to one of:
- concrete local code artifacts (files + line ranges)
- local config/docs
- command output that is itself grounded in local files

## Category separation: native integration versus standalone replacement
When comparing an in-host integration to a standalone AI application, classify the products before scoring features. Do not treat “AI edits Office files” as the category; distinguish:

- **Standalone replacement:** owns its document, spreadsheet, or presentation engine; typically wins on convenience, breadth, cross-platform independence, and zero host-app requirements.

# Destination Trip Planning

Plan themed trips to specific attractions or destinations with real pricing, logistics, and a tight itinerary focused on the theme — not a generic city guide.

## When to Use

- User wants to plan a trip to a specific attraction, event, or themed destination (e.g., Graceland, a national park, a festival, a resort)
- User asks for "what to do there" at a given destination
- User needs a go/no-go recommendation on trip length and budget
- User wants to know what's nearby that fits the same theme

## Core Workflow

### Phase 1: Lock the Destination and Constraints

# Discord Connection Guide

## Quick Setup Flow

1. **Create a bot application** — go to [Discord Developer Portal](https://discord.com/developers/applications), create a new application (or use an existing one).
2. **Generate a bot token** — under Bot → Reset Token, copy the token.
3. **Enable intents** — in Bot settings:
 - **Message Content Intent** (required for reading messages)
 - **Presence Intent** (optional, for online status)
4. **Generate OAuth2 invite URL** — use [OAuth2 URL Generator](https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=3558496) and paste into browser.
5. **Invite to server** — pick your guild from the dropdown.
6. **Configure in Hermes** — `hermes gateway setup` or manually configure via config.yaml.

## Bot Permissions (Minimal)

# Domestic Trip Planning

Research and plan a multi-day domestic trip — hotels, attraction tickets, itineraries, driving distances, local tips, and budget estimates. Designed for family/personal trips where the user wants a clear, actionable overview before committing to anything.

## When to Use

- User wants a multi-day trip plan with attractions, hotel, and logistics
- Trip involves a mix of booking elements (hotel + tickets + transport)
- User asks for pricing, tips, itineraries, and "what to know" from multiple sources
- User asks "Step 1 — Research" before making decisions

## Core Workflow

1. **Lock the trip frame before pricing**
 - Record exact check-in and checkout dates, calendar days, and nights. Preserve the user's stated checkout date exactly; never silently substitute a shorter stay because an earlier search used different dates. If the duration or dates change, announce the change and recompute every dependent line item; do not carry forward the earlier night count.

# Google Workspace

> **Installed-script caveat:** The current `scripts/setup.py` in this environment does **not** accept a `--services` argument. Its configured scope list is broad (including Gmail read/send/modify plus Calendar, Drive, Contacts, Sheets, and Docs). Do not run a new OAuth authorization until the requested service scope has been reviewed or a narrower setup path is implemented.

Gmail, Calendar, Drive, Contacts, Sheets, and Docs — through Hermes-managed OAuth and a thin CLI wrapper. When `gws` is installed, the skill uses it as the execution backend for broader Google Workspace coverage; otherwise it falls back to the bundled Python client implementation.

## References

- `references/gmail-search-syntax.md` — Gmail search operators (is:unread, from:, newer_than:, etc.)

## Scripts

- `scripts/setup.py` — OAuth2 setup (run once to authorize)
- `scripts/google_api.py` — compatibility wrapper CLI. It prefers `gws` for operations when available, while preserving Hermes' existing JSON output contract.

# Maps Skill

Location intelligence using free, open data sources. 8 commands, 44 POI
categories, zero dependencies (Python stdlib only), no API key required.

Data sources: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.

This skill supersedes the old `find-nearby` skill — all of find-nearby's
functionality is covered by the `nearby` command below, with the same
`--near "<place>"` shortcut and multi-category support.

## When to Use

- User sends a Telegram location pin (latitude/longitude in the message) → `nearby`
- User wants coordinates for a place name → `search`

# Notion

Talk to Notion two ways. Same integration token works for both — pick by what's available.

◆ **`ntn` CLI** — Notion's official CLI. Shorter syntax, one-line file uploads, required for Workers. macOS + Linux only as of May 2026 (Windows support "coming soon"). **Default when installed.**
◆ **HTTP + curl** — works everywhere including Windows. **Default fallback** when `ntn` isn't installed.

## Setup

### 1. Get an integration token (required for both paths)

1. Create an integration at https://notion.so/my-integrations
2. Copy the API key (starts with `ntn_` or `secret_`)
3. Store in `${HERMES_HOME:-~/.hermes}/.env`:

# Office Document Review

Use this skill when the user wants you to inspect a OneDrive/SharePoint-style folder tree, locate a subfolder by name/date, and proofread all documents in it for spelling and grammar.

This is a workflow skill, not a single-app skill: it covers local file-system browsing, document text extraction, and batch proofreading notes.

## Triggers

- "go to the OneDrive folder"
- "look in folder X and then folder Y"
- "proofread all those documents"
- "check for spelling/grammar errors in the docs"
- "review the files in this folder"

## Core workflow

# Session Artifact Indexing

Use this skill when a session creates or references several documents, trackers, plans, templates, source links, or skills that the user may need later.

Primary trigger phrases:
- “I lose track of things”
- “put the links somewhere”
- “make a note”
- “save the documents from this session”
- “where are the files from this?”
- Any multi-step work that creates 3+ durable files and ends with a natural handoff/checkpoint

The goal is not to duplicate all work. The goal is to create one clean index that the user can open later.

## Default Destination

# Daily News Digests

Use this skill when the user asks for a recurring local news/research monitor that pulls fresh items from X/Twitter, GitHub, Reddit, Hacker News, RSS, release notes, forums, or other public sources and saves a Markdown digest locally.

The deliverable is a working collector plus verified scheduling, not a suggestion list.

## Default outcome

Create:

1. A deterministic script under `~/scripts/` or an explicitly requested project folder.
2. A dated Markdown output directory under the relevant vault area.
3. A `latest.md` copy for quick viewing.
4. A scheduler:
 - macOS local/background: `launchd` LaunchAgent.

# Dynamic Content Extraction

Extract structured data (prices, listings, product details) from JavaScript-heavy sites where key data is rendered by React/Vue/Angular and doesn't appear in compact accessibility snapshots.

## When to Use

- Extracting prices, inventory, or listings from booking/retail/travel sites (IHG, Marriott, Booking.com, Amazon, etc.)
- Data is visible on screen but absent from `browser_snapshot` (compact mode)
- `web_extract` times out or returns empty content
- Direct API calls are blocked by CDN/WAF (Akamai, Cloudflare)
- Vision model reads are inconsistent for exact numeric data
- the user asks for browser/search/internet tool inventory, fallback order, or says to check the vault for web tooling
- Estimating market-wide keyword demand when the request is phrased as “check Google Analytics” or a chart/API is rendered only in page JavaScript

References:

# Evidence-Based Replies

Use this skill when the user wants to:
- compare someone's claim to a research paper, benchmark, article, or repo README
- draft a reply that corrects a misunderstanding of the evidence
- separate "the source supports X" from "the source does not support Y"
- turn a source-comparison into a Reddit/X/forum-ready response

## Core principle
Do **not** stop at summarizing the source. The deliverable is usually the **distinction**:
1. what the source actually establishes
2. what stronger conclusion the other person is trying to import into it
3. why that leap does not follow

If the user is asking for a reply, the misunderstanding of the evidence must be addressed explicitly, not left implicit.

# External Model Review

## When to use

Use this skill when the user asks a named external model or provider to:

- critique an implementation plan, architecture, specification, major article, README, or release candidate;
- pressure-test a consequential decision;
- provide an independent spec/security/quality pass;
- review something through OpenRouter, Claude, Gemini, Fable, or another specific model;
- revise the original artifact after the critic pass.

This is a review workflow, not general brainstorming. Load `multi-model-brainstorming` instead when the goal is divergent idea generation across several models.

## Core rule

# HF Model Card Research

Extract structured metadata — downloads, likes, benchmark claims, file sizes, author statements — from HuggingFace model cards. Used when the user asks you to "check these models on HF", "pull benchmarks for these variants", or "compare what authors claim."

## When to Use

- User provides a list of authors and model families (e.g. "pull metadata for these Qwen3.6 variants")
- You need to compare benchmark claims across multiple fine-tunes of the same base model
- You need up-to-date download counts, likes, or file sizes for model variants
- Verifying what a model card claims vs what other sources say
- Surveying the ecosystem around a new base model release

## Workflow

# Local & National Discovery

Find events, activities, venues, and things happening in the user's area (default: the user's local area) or anywhere nationally. Covers two subdomains:

1. **Events** — concerts, festivals, comedy, things to do tonight/this weekend
2. **Venues** — bars, lounges, restaurants, nightlife spots matching specific criteria (vibe, amenities, atmosphere)

## When to Use

- User asks about local events, things to do tonight/this weekend
- "What's happening around here?" or similar discovery requests
- User asks for venue recommendations with specific criteria (e.g., "cigar lounge," "speakeasy," "classy bar") — local OR national
- User asks "find me X somewhere" without specifying a city — treat as national search
- Need to surface relevant activities based on user interests

# Marketplace Purchase Vetting

Use this when the user asks whether a local listing is a scam, "too good to be true," worth looking at, or a good deal. Also use this when he asks you to **find** options — search/discover candidates, then vet the best ones. The goal is not a generic buying guide; it is a practical risk read with clear next steps.

Two modes: **Discovery** (find me options) and **Vetting** (check this listing). Run them in sequence when the user hasn't identified a specific listing.

---

## Mode 1: Discovery — Search for candidates in the area

Run this first when the user says "find me a car/suv/truck for $X in our area" without a specific link. The output is a ranked shortlist of the best live options.

### Facebook Marketplace search procedure

Read before a broad or tightly constrained vehicle hunt; it documents radius conversion, ignored filters, regional partitioning, feed virtualization, and dealer/down-payment traps.

# Site Mapping

Map the complete structure of a website: extract all URLs from sitemaps, analyze navigation hierarchy, classify content by section, and produce a structured overview.

## When to Use

- User asks to "map out," "audit," or "review" a website's structure
- Need to understand a site's URL taxonomy, content sections, or SEO footprint
- Preparing competitive analysis, content gap assessment, or migration planning

## Workflow

### 1. Discover sitemaps

Check these in order:

# Source Verification

Use this when the user asks to verify an article, claim, controversy, company/news item, or web page. The deliverable is a grounded verdict, not a generic summary.

## Operating pattern

1. Extract the article text and metadata first:
 - Title, date, author if available, publication/source, outbound links, and the exact claims being made.
 - If `web_extract` times out or returns empty, do not keep retrying the same path. Switch to browser automation or terminal HTTP requests with a normal User-Agent, then parse with BeautifulSoup/readability-style extraction.
2. Break the article into checkable claims:
 - Timeline/date claims.
 - Quantitative claims: counts, stars, funding, releases, benchmark scores.
 - Attribution/provenance claims: who said what, where, when.
 - Technical claims: architecture, features, implementation details.
3. Verify against primary or near-primary sources before relying on commentary:

# Meta / Facebook Page Posting

Publish posts to a Facebook Page using the user's own account. Two paths: the
**browser session** (primary — works for everyone) and the **Graph API**
(power users with a Meta app).

## Hard rules

- **Never ask the user to paste a Facebook password, 2FA code, or token into chat.** The user logs in through the browser themselves; tokens live in `.env`.
- **Posting is an irreversible publish action.** Draft the full post (text, link, image), show the user exactly what will be published and to which Page, and get explicit approval before submitting.
- **Post as the Page, not as the user's personal profile**, unless the user explicitly says otherwise.
- **Never delete or edit a published post without explicit approval.**
- Respect platform policies: no engagement bait, spam, or misleading claims; no posting to Pages the user does not administer.
- If a login, 2FA, or app-review wall appears, stop and hand it to the user — never work around security checkpoints.

# Publication Link Audit

Use this when the user has a Reddit post, megathread, guide, wiki page, or any README that is about to be published — and needs every outbound URL verified before going live. Also use when a published post is reported to have broken links.

This skill exists because HTTP 200 is necessary but not sufficient: a link can return 200 and still resolve to the wrong destination when the URL's opaque identifier was transcribed incorrectly.

## When to use

Use when:
- A megathread or Reddit post is being finalized for publication.
- A guide/README/wiki references external model cards, GitHub repos, or other Reddit threads.
- the user reports "some links are wrong" after publication.
- A document contains more than ~5 outbound URLs (below that, spot-checking is usually enough).

# Reddit Browse & Post

Let an agent read Reddit and publish posts using the user's own Reddit account. Everything here is account-agnostic: the user supplies their credentials through environment variables or a browser login, never through chat.

## Hard rules

- **Never ask the user to paste a Reddit password, token, or cookie into chat.** Credentials go into environment variables (profile `.env`) or the user logs in via the browser themselves.
- **Posting is an irreversible publish action.** Draft the title and body, show the user exactly what will be posted and where, and get explicit approval before submitting. No exceptions for "the user already asked."
- **Never edit, delete, vote, or mod-queue anything without explicit approval.**
- Respect subreddit rules: read the sidebar / rules (or `about/rules.json`) before posting to a subreddit you have not posted to.
- Respect rate limits: keep requests under ~1/second for reads; wait at least a minute between post attempts. Respect 429/403 responses and back off.
- Do not post spam, affiliate links, or promotional content unless the user explicitly directs it.
- Vote manipulation, ban evasion, and buying/selling accounts are off-limits.

## Reading Reddit

# xurl — X (Twitter) API via the Official CLI

`xurl` is the X developer platform's official CLI for the X API. It supports shortcut commands for common actions AND raw curl-style access to any v2 endpoint. All commands return JSON to stdout.

Use this skill for:
- posting, replying, quoting, deleting posts
- searching posts and reading timelines/mentions
- liking, reposting, bookmarking
- following, unfollowing, blocking, muting
- direct messages
- media uploads (images and video)
- raw access to any X API v2 endpoint
- multi-app / multi-account workflows

This skill replaces the older `xitter` skill (which wrapped a third-party Python CLI). `xurl` is maintained by the X developer platform team, supports OAuth 2.0 PKCE with auto-refresh, and covers a substantially larger API surface.

# Application Security Review

Perform a practical source-level security review of an application repository. Favor confirmed issues over speculative ones. The goal is a useful operator-facing report: severity, file/line references, exploit path, impact, and remediation.

## Use when
- The user asks to "scan for security issues", "review for security", or "audit this repo/app".
- The user asks whether a native app or realtime AI/voice prototype is ready to sell, ship, distribute, or submit to an app store.
- Reviewing AI-integrated apps, browser/UIs, add-ins, extensions, native mobile apps, or local proxies.
- Evaluating whether a prototype is safe for local-only use vs real deployment.

For native iOS commercial-readiness reviews, load and follow the readiness checklist. It expands the audit beyond security into StoreKit, App Store compliance, realtime audio reliability, consumer UX, unit economics, and release gates.

## Review priorities
1. Trust boundaries first.
 - What input is untrusted?

# Coding Worktree Recovery

Use this skill when coding-agent work is interrupted, an agent exits without a clean commit, multiple controllers target the same checkout, or the checkout produces inconsistent file/Git behavior.

This skill is about preserving valid work and restoring one trustworthy writer. It does not authorize pushing, merging, publishing, or destructive cleanup.

## Core invariants

1. **One checkout, one writer.** Read-only reviewers may overlap; write-capable agents may not.
2. **The live filesystem is authoritative.** Agent summaries and successful process exits are evidence leads, not proof.
3. **Never clean another writer's work.** Do not reset, stash, checkout, delete, or overwrite unexplained changes.
4. **Commits are checkpoints, not completion.** Re-run controller gates after the final commit.
5. **Mechanical status and reasoning are separate.** A deterministic watchdog may report process/Git state; acceptance still requires a controller review.

## Recovery workflow

# Cross-Browser Typography QA

## Purpose

Use this skill when web text looks clipped, flattened, wrapped incorrectly, misaligned, or materially different between Chromium and WebKit/Safari. Treat text rendering as both a geometry problem and a visual paint problem: passing DOM bounds does not prove that every glyph is intact.

## Triggers

- Lowercase descenders such as **g**, **j**, **p**, **q**, or **y** appear cut off.
- Gradient or transparent text looks flattened at the baseline.
- A heading fits within its element but still looks clipped.
- Safari and Chromium disagree on line height, wrapping, button labels, or heavy font weights.
- A deployed fix appears absent despite a successful upload or publish message.

## Workflow

# Authoring Hermes-Agent Skills (in-repo)

## Overview

There are two places a SKILL.md can live:

1. **User-local:** `~/.hermes/skills/<maybe-category>/<name>/SKILL.md` — personal, not shared. Created via `skill_manage(action='create')`.
2. **In-repo (this skill is about this case):** `<repo>/skills/<category>/<name>/SKILL.md` — committed, shipped with the package. Use `write_file` + `git add`. `skill_manage(action='create')` does NOT target this tree.

## When to Use

- User asks you to add a skill "in this branch / repo / commit"
- You're committing a reusable workflow that should ship with hermes-agent
- You're editing an existing skill under `<repo>/skills/` (use `patch` for small edits, `write_file` for rewrites; `skill_manage` still works for patch on in-repo skills, but not for `create`)

# Inspecting the live Hermes desktop DOM

## Overview

When you are developing `apps/desktop` and the user is running that same app
(`hgui` / `npm run dev`), you can read the **live rendered DOM** of the window
they are looking at — computed styles, geometry, which CSS rule actually won,
console output — instead of inferring it from `.tsx` and being wrong.

Dev-server runs open a Chrome DevTools Protocol port on `127.0.0.1:9222`
automatically. The renderer is a Chromium page, so everything DevTools can read,
a script can read.

**This does not replace looking at it.** CDP answers *factual* questions ("what
is the computed padding", "did this element render", "which selector matches").

# Specification-Compliance Review

## Overview

Use this skill when an implementation is described as partial, passing, or complete and the task is to determine whether it actually satisfies an explicit specification. This is not a generic code review and not a re-run of the test suite. The central question is: **does every normative requirement have both a correct implementation path and a meaningful proof?**

A green build proves syntax, compilation, and perhaps the tested examples. It does not prove race behavior, cancellation semantics, exact backpressure policy, integration parity, or compliance with explicit non-goals.

## Workflow

### 1. Establish the review baseline

Read, in order:

1. The task specification and surrounding plan/release gates.

# Stale Patch Reconciliation

Use when a patch/diff must be compared with, repaired against, or refreshed for a moving checkout — "is this patch still needed", "does upstream already contain it", "what changed since it was written", "reconcile X.diff with HEAD", or "make apply-patches pass again".

This skill has two explicit modes:

- **Analysis mode (default):** read-only archaeology and a minimal repair plan. Do not edit, reset, stash, clean, update, or restart.
- **Repair mode (only when authorized):** implement the invariant in an isolated worktree, run focused gates, regenerate the patch from the current baseline and an explicit file allowlist, then apply it to the live checkout only after clean/reverse checks pass. Preserve unrelated dirty work exactly.

Deliverable shape: (1) behavioral invariant, (2) exact gaps/call sites, (3) upstream status, (4) drift cause, (5) minimal repair, (6) focused gate evidence, and (7) artifact/applicator verification. Coordinate writer ownership through `shared-worktree-agent-orchestration`.

## Core sequence

1. **Read the full patch first.** Paginate the whole diff; note every file touched and the old-file line numbers of each hunk. The hunks are the map for later drift attribution.