Testing & Debugging Skills

Review security boundaries for agent skills and tool-using workflows. Use when a skill, hook, script, adapter, or agent workflow touches tools, shell commands, file writes, secrets, private data, external documents, network calls, permissions, or destructive actions. NOT for ordinary style edits or non-tooling docs with no data or permission boundary.

Compare viable solution paths before implementation. Use when architecture, refactors, data model changes, workflow changes, tool choices, or irreversible decisions make the first idea too sticky. NOT for one-line fixes, constrained chores, or changes with only one safe path.

Find and challenge hidden assumptions in a plan, prompt, bug report, design, or AI-generated answer. Use when claims are unverified, something is called obvious or safe, or a plan depends on external behavior. NOT for confirmed requirements or tiny mechanical edits.

Challenge unnecessary abstraction, dependencies, and indirection before adding them. Use when a solution adds modules, frameworks, queues, caches, state machines, agents, configuration layers, or hard-to-delete architecture. NOT for small local changes, deletion-only refactors, or accepted ADRs.

Debug hard failures with reproduction, hypotheses, instrumentation, experiments, and regression proof. Use when bugs are flaky, poorly understood, production-facing, performance-related, or AI starts guessing fixes. NOT for simple bugs that already have a deterministic failing test.

Review a human or AI-generated diff as an untrusted claim. Use when merging, committing, or accepting changes that may hide regressions, missing tests, security risk, data loss, or unexplained behavior. NOT for formatting-only diffs or already-reviewed changes with no new code.

Audit README, docs, comments, examples, and public copy against repository evidence. Use when merging documentation changes or public claims to ensure claims are backed by files, tests, scripts, examples, or explicit limitation language. NOT for typo-only edits or private notes that make no factual claims.

Convert qualitative repo gaps or repeated failures into deterministic tests, fixtures, validators, or checks. Use when a gap, false confidence pattern, validator miss, or repeated review failure should become executable evidence. NOT for writing implementation code before the observable failure is defined or for broad test-suite expansion without a specific gap.

Require a plain-language mechanism explanation before shipping, handoff, or review. Use when changes are largely AI-generated, learning-focused, or the developer may not understand the code. NOT for trivial edits, generated artifacts, or explanations already captured in a thinking ledger.

Require a failing signal before bug fixes or behavior changes. Use when fixing a bug, adding behavior, changing edge cases, or reviewing AI code that lacks proof. NOT for docs-only edits, generated snapshots, or emergency hotfixes with a tracked follow-up test.

Route broad or high-ambiguity requests through the smallest useful sequence of existing skills. Use when the user asks for god mode, all skills, maximum capability, end-to-end autonomous work, or a task that spans implementation, review, architecture, safety, and handoff. NOT for simple single-skill requests, literal claims of universal expertise, bypassing permissions, or skipping verification.

Check local docs, ADRs, interfaces, schemas, and primary upstream sources before guessing. Use when work depends on APIs, frameworks, repo conventions, architecture decisions, or policy. NOT for purely local refactors or cases where code is the only source of truth.

Smoke-test runtime adapter changes for shared skills. Use when publishing or merging changes to Codex, Claude, Gemini, or other adapter manifests, context files, skill paths, or runtime metadata. NOT for skill body edits that do not affect adapter discovery or for unrelated CI changes.

Gate new or changed skills before review. Use when adding, rewriting, or materially expanding a skill and the author needs to prove the skill has a real repeated problem, clear trigger, non-trigger, evidence contract, failure modes, and examples. NOT for typo-only skill edits or mechanical catalog/index updates.

Review whether a stale, overlapping, unused, or harmful skill should be kept, merged, renamed, archived, or deleted. Use when a skill overlaps with another, stops matching repo purpose, has weak usage evidence, or creates routing confusion. NOT for adding new skills or for minor edits that keep scope intact.

Audit overlap between proposed or existing skills. Use when adding a skill near an existing skill, renaming a skill, splitting a skill, or reviewing a skill set that may be drifting into duplicate prompts. NOT for standalone skill edits with no nearby skill or for catalog formatting changes.

Review thinking ledgers for substantive reasoning evidence. Use when accepting a staged or submitted thinking ledger for non-trivial work to check problem, assumptions, alternatives, evidence, verification, tradeoffs, and risk. NOT for checking only whether a ledger file exists or for reviewing unrelated prose docs.

Trace existing execution paths before changing unfamiliar behavior. Use when editing unknown code, debugging, reviewing AI-generated changes, or when a plan depends on current state, side effects, or error flow. NOT for greenfield files, pure docs, or already-traced isolated changes.

Review real agent transcripts against expected skill behavior. Use when a Codex, Claude, Gemini, or other agent session needs review to see whether the assistant followed the named skill, skipped evidence, overclaimed checks, or exposed a rubric gap. NOT for reviewing source diffs directly or for hypothetical skill design without a transcript.