From bf0abe57249b5d0a227d03214aac90004aa39e73 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Sat, 11 Apr 2026 11:44:57 -0400 Subject: [PATCH 1/4] docs(skills): rewrite tri-* descriptions to eliminate cross-triggering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All four tri-* skills shared near-identical synonym soup ("triple/three-way/ multi-agent/parallel/consensus") which caused the description layer to offer no differentiation. A query like "tri security audit" could plausibly pull in tri-review, and "compare three models on this" could swallow work that belongs to tri-debug or tri-security. Each description now: - opens with its unique function (not a generic "Triple-agent X" stamp) - names the specific trigger phrases that fit only that skill - gives a "worth-it" signal so the model doesn't fire on trivial tasks (3x model cost only pays off on high-stakes / hard / exploratory work) - explicitly hands off to siblings by function, killing the collision - excludes routine single-pass tasks that don't need triple ceremony tri-dispatch repositioned as the general-purpose/exploratory tri-* for greenfield tasks that don't fit review/debug/security — it was the most dangerous one previously because "triple dispatch" is vague enough to swallow anything. Bodies untouched. Underlying workflow YAMLs confirmed structurally sound (engine.go:111 correctly dispatches parallel: [ids] steps). --- skills/tri-debug/SKILL.md | 2 +- skills/tri-dispatch/SKILL.md | 2 +- skills/tri-review/SKILL.md | 2 +- skills/tri-security/SKILL.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/tri-debug/SKILL.md b/skills/tri-debug/SKILL.md index 9cc9e84..e61255d 100644 --- a/skills/tri-debug/SKILL.md +++ b/skills/tri-debug/SKILL.md @@ -1,6 +1,6 @@ --- name: tri-debug -description: Triple-agent debugging — use when asked for tri debug, triple debug, three-way debugging, multi-agent diagnosis, parallel debug, or consensus root-cause analysis. Three model tiers diagnose the bug independently and compare theories. Triggers the deterministic tri-debug workflow. +description: Three independent root-cause analyses of a hard bug or failure — smart + general + fast model tiers diagnose in parallel, then theories are compared and reconciled. Use when the user asks for tri-debug, triple debug, three-way debugging, multi-model diagnosis, parallel debug, consensus root-cause analysis, or is stuck on a hard bug and wants divergent hypotheses. Worth the extra cost when: the bug is hard (heisenbug, intermittent, cross-system), logs are ambiguous, the obvious fixes have already failed, or the user explicitly wants three independent theories before committing to one. Do NOT use for code review (use tri-review), security audits (use tri-security), or comparing greenfield implementation approaches (use tri-dispatch). Do NOT use for simple "what does this error mean" or routine null-check / typo bugs — a single pass is faster. --- # Tri-Debug diff --git a/skills/tri-dispatch/SKILL.md b/skills/tri-dispatch/SKILL.md index 5997f48..60f41f4 100644 --- a/skills/tri-dispatch/SKILL.md +++ b/skills/tri-dispatch/SKILL.md @@ -1,6 +1,6 @@ --- name: tri-dispatch -description: Triple-tier task dispatch — use when asked for tri dispatch, triple dispatch, three-way comparison, "send this to three models", or "compare model approaches". Sends the same task to three model tiers in parallel and compares their approaches. Triggers the deterministic tri-dispatch workflow. +description: Three model tiers (smart + general + fast) each tackle the SAME open-ended task independently, then their divergent approaches are compared — this is the GENERAL-PURPOSE tri-* skill for tasks that don't fit the specialized siblings. Use when the user asks for tri-dispatch, triple dispatch, three-way comparison of model approaches, says "send this to three models and show me their takes", or wants to see divergent solutions before picking one. Worth the extra cost when: the task is exploratory or greenfield (design, architecture, new implementation, optimization), the user wants to compare model strengths on a novel problem, or is deliberately seeking diversity of approach before committing. Do NOT use for code review of existing code (use tri-review), debugging a specific failure (use tri-debug), or security audits (use tri-security). Do NOT use when the user already knows which approach they want — tri-dispatch is for exploration, not execution. --- # Tri-Dispatch diff --git a/skills/tri-review/SKILL.md b/skills/tri-review/SKILL.md index 407904c..f46d34b 100644 --- a/skills/tri-review/SKILL.md +++ b/skills/tri-review/SKILL.md @@ -1,6 +1,6 @@ --- name: tri-review -description: Triple-agent code review — use when asked for a tri review, triple review, three-way review, multi-agent review, parallel review, or consensus review. Dispatches Claude/Codex/Gemini in parallel and consolidates findings. Triggers the deterministic tri-review workflow. +description: Three independent code reviews (smart + general + fast model tiers running Claude, Codex, and Gemini) with consolidated findings — use when the user asks for tri-review, triple code review, three-way code review, multi-model code review, consensus code review, or says "get three opinions on this diff/PR/change before I ship". Worth the extra cost when the change is high-stakes, the user doesn't trust a single-model review, or they want breadth of perspectives over depth. Do NOT use for bug diagnosis (use tri-debug), security audits (use tri-security), or comparing implementation approaches on greenfield work (use tri-dispatch). Do NOT use for routine "can you review this PR" requests where a single-model pass is fine. --- # Tri-Review diff --git a/skills/tri-security/SKILL.md b/skills/tri-security/SKILL.md index 2261676..3b084a4 100644 --- a/skills/tri-security/SKILL.md +++ b/skills/tri-security/SKILL.md @@ -1,6 +1,6 @@ --- name: tri-security -description: Triple-agent security audit — use when asked for tri security, triple security audit, three-way security review, multi-agent vulnerability scan, or parallel security audit. Three-tier parallel review focused on injection, auth, and config. Triggers the deterministic tri-security workflow. +description: Three-tier parallel security audit (injection + auth + config, each examined by a different model tier) with severity-ranked consolidation — use when the user asks for tri-security, triple security audit, three-way security review, multi-model vulnerability scan, or parallel security audit of a code change, branch, module, or endpoint. Worth the extra cost when: touching auth/payments/user-uploads/admin surfaces, before prod deploy of security-sensitive code, after a security incident, or when the user is paranoid about a specific attack class. Do NOT use for general code quality review (use tri-review), bug diagnosis (use tri-debug), or approach comparison on greenfield work (use tri-dispatch). Do NOT use for a single-line "is this XSS safe" question, or for running pre-existing scanners like npm audit / gosec / semgrep — those are single-tool tasks, not a tri workflow. --- # Tri-Security From 32b78f1ac947955b4bf46f000c9660b4cb7a3b10 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Sat, 11 Apr 2026 11:45:50 -0400 Subject: [PATCH 2/4] docs(skills): rewrite research / deep-research descriptions with stakes-based routing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous research description used brittle negative-keyword routing ("NOT for 'deep research' or 'validate' — those go to deep-research"). That pattern breaks as soon as a user rephrases. Replaced with stakes-based positioning: research is the default/exploratory tier, deep-research is the high-stakes / ACH / disconfirmation tier. research now explicitly says "default to this over deep-research unless the user signals stakes" — which is the right bias since research is cheaper and covers 80% of real queries. deep-research now opens with "needs to be SURE, not just well-informed" and lists the consequence categories that justify the 400k token budget (architecture commitment, vendor choice, security claim, compliance question, public-facing claim). Each description also carves out what it is NOT for, by function rather than keyword, so rephrasing doesn't break routing. --- skills/deep-research/SKILL.md | 2 +- skills/research/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/deep-research/SKILL.md b/skills/deep-research/SKILL.md index 27526cf..c4bc6bc 100644 --- a/skills/deep-research/SKILL.md +++ b/skills/deep-research/SKILL.md @@ -1,6 +1,6 @@ --- name: deep-research -description: Deep research with Analysis of Competing Hypotheses — use when asked to do deep research, deeply investigate, validate claims, or when correctness is critical and the user wants rigorous analysis with disconfirmation testing. +description: High-stakes research with Analysis of Competing Hypotheses, disconfirmation testing, evidence matrices, and sensitivity checks (~400k token budget) — use when the user needs to be SURE, not just well-informed. Trigger phrases include "deep research", "deeply investigate", "validate that X", "prove/disprove", "we're making a big decision", "correctness is critical", "I need to trust this answer", or "actively try to disprove this". Worth the extra cost when: the wrong answer has real consequences (architecture commitment, vendor choice, security claim, compliance question, public-facing claim), the user has already seen shallow answers and doesn't trust them, they explicitly ask for rigor or disconfirmation, or they're defending a position to stakeholders. Do NOT use for exploratory "what's out there" questions (use research), routine library comparisons where a single good answer suffices (use research), or quick factual lookups. This is the bias-catching, evidence-calibrating tier — overkill for casual exploration but essential when you can't afford to be wrong. --- # Deep Research diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index c071979..a150994 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -1,6 +1,6 @@ --- name: research -description: Research workflow — use when asked to research a topic, investigate options, compare approaches, or find the best solution to a technical question. NOT for "deep research" or "validate" requests — those go to deep-research. For complex or high-stakes questions where correctness is critical, use deep-research instead. +description: Fast, standard research workflow (clarify → decompose → parallel search → summarize → synthesize) for exploratory questions where the user wants a good answer quickly. Use when the user asks to research a topic, investigate options, compare libraries/tools/approaches, find the best solution to a technical question, scope out a space they don't know yet, or get a grounded starting point before deciding. Worth using when the user is gathering context or narrowing down options — not when they've already committed and need validation. Do NOT use for high-stakes decisions where a wrong answer is expensive (use deep-research), validating specific claims under scrutiny (use deep-research), or simple factual lookups that don't need web searches (answer directly). Default to this over deep-research unless the user explicitly signals stakes with phrases like "we're making a big bet", "need to be sure", "validate", "deeply investigate", or "correctness is critical". --- # Research From bab79a9c44a2aeba3e618d5368191c3ebf607345 Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Sat, 11 Apr 2026 11:48:16 -0400 Subject: [PATCH 3/4] docs(skills): rewrite audit / self-audit descriptions to separate scanner vs ranking Both descriptions used the word "audit" with no functional differentiation, so the user (and Claude's triggering) had no way to tell them apart. The names alone ("audit" vs "self-audit") don't hint at the real distinction: - audit runs EXTERNAL scanners (npm audit, eslint, govulncheck, semgrep) and reports what the tools say. Stateless, tool-driven. - self-audit is INTROSPECTIVE evidence ranking (karpathy-style): measure quality/security/git signals, then produce a prioritized "what's wrong here ranked by evidence" improvement plan. Judgment-driven. Each description now leads with that distinction, gives worth-it conditions, and carves out the sibling by function. "What scanners say" vs "what a human should prioritize" is now explicit. --- skills/audit/SKILL.md | 2 +- skills/self-audit/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/audit/SKILL.md b/skills/audit/SKILL.md index f7faf72..41cc321 100644 --- a/skills/audit/SKILL.md +++ b/skills/audit/SKILL.md @@ -1,6 +1,6 @@ --- name: audit -description: Audit a project for health — use when asked to audit this project, check project health, run a project audit, look for issues, or assess code/dep/lint/security state. Triggers the deterministic audit workflow (detect ecosystem → deps → lint → security → report). +description: External-scanner-driven project health check — runs the actual ecosystem tools (npm audit, eslint, govulncheck, semgrep, pip-audit, etc.) to surface what the standard scanners flag: outdated or vulnerable dependencies, lint violations, known CVEs, and config drift. Use when the user asks to "audit this project", "check project health", "run a project audit", "check deps/lint/security state", "is this repo up to date", or wants a stateless rundown of what the standard tools report. Worth using when kicking off work on an unfamiliar project, before a release, after a dependency bump, or when triaging a long-neglected repo. Do NOT use for introspective "what's wrong with this repo and what should I fix first" questions (use self-audit — that ranks issues by evidence), security-focused review of a specific code change (use tri-security), or debugging specific failures (use tri-debug or bugfix). This skill reports what scanners say, not what a human should prioritize. --- # Project Audit diff --git a/skills/self-audit/SKILL.md b/skills/self-audit/SKILL.md index 470252f..29e3d3a 100644 --- a/skills/self-audit/SKILL.md +++ b/skills/self-audit/SKILL.md @@ -1,6 +1,6 @@ --- name: self-audit -description: Self-audit the codebase — use when asked to self-audit, audit the codebase against its own metrics, run a karpathy-style audit, measure and rank issues by evidence, or "what's wrong with this repo". Triggers the deterministic self-audit workflow (detect → measure quality/security/git → analyze → synthesize). +description: Evidence-ranked codebase self-assessment (karpathy-style) — measures quality, security, and git signals in parallel then produces a prioritized list of what's actually wrong here, ranked by how much evidence supports each finding, with an actionable improvement plan. Use when the user asks to "self-audit", "audit the codebase against its own metrics", "run a karpathy-style audit", "what's wrong with this repo and what should I fix first", "rank issues by evidence", or wants a synthesized improvement plan rather than a scanner dump. Worth using when the user wants judgment and prioritization (where should I invest effort?), not raw warnings; when they're choosing the next big refactor; or when they want the biggest issues surfaced first with evidence showing why. Do NOT use for a plain scanner rundown of deps/lint/CVEs (use audit — that just runs the tools), security review of a specific code change (use tri-security), or debugging a specific failure (use tri-debug or bugfix). This skill is about ranking and judgment, not tool execution. --- # Self-Audit From c25822ce873ba27d8d519b4f41ca0a3b014cb48a Mon Sep 17 00:00:00 2001 From: Tym Rabchuk Date: Sat, 11 Apr 2026 12:37:10 -0400 Subject: [PATCH 4/4] docs(skills): rewrite dispatcher skill descriptions to prevent overtriggering on common phrases Five dispatcher skills whose descriptions collided either with native Claude behavior ("fix this bug", "refactor this") or with other plugins (feature-dev:feature-dev, commit-commands:commit-push-pr, pr-review-toolkit:review-pr). Previous descriptions listed trigger phrases without carve-outs, so the workflow ceremony risked firing on trivial tasks. - bugfix: explicit "not for typos / null-checks / simple fixes" carve-out, plus hand-offs to tri-debug (hard bugs) and self-perf (performance). - feature: clarified boundary with feature-dev:feature-dev plugin (devkit is deterministic engine-driven; feature-dev is agent-guided collaboration), with "just write the code" exclusion for one-file additions. - refactor: added the crucial exclusion "no tests = do it manually, safety net is the entire point", plus a rename-one-var exclusion. - pr-ready: clear separation from commit-commands:commit-push-pr (that is the lighter commit+push+PR path; pr-ready runs full gated pipeline), and explicit "heaviest PR workflow in devkit" positioning. - mega-pr: repositioned as a FAN-OUT skill that delegates to both tri-review and pr-review-toolkit, so it doesn't compete with its own sub-skills. Made the "deliberate overkill" nature explicit so it won't fire on routine PRs. Every description now includes worth-it conditions (when the workflow ceremony is justified) and negative carve-outs (when a lighter path or a sibling skill is the right choice). Bodies untouched. --- skills/bugfix/SKILL.md | 2 +- skills/feature/SKILL.md | 2 +- skills/mega-pr/SKILL.md | 2 +- skills/pr-ready/SKILL.md | 2 +- skills/refactor/SKILL.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/bugfix/SKILL.md b/skills/bugfix/SKILL.md index c4697bc..7c831aa 100644 --- a/skills/bugfix/SKILL.md +++ b/skills/bugfix/SKILL.md @@ -1,6 +1,6 @@ --- name: bugfix -description: Fix a bug end-to-end — use when asked to fix a bug, debug an issue, resolve an error, patch a defect, or "this is broken, fix it". Triggers the deterministic bugfix workflow (triage → reproduce → diagnose → fix → regression test → run tests). +description: Deterministic full-lifecycle bugfix workflow — triage → reproduce → diagnose → fix → regression-test → run-tests, with a reproduction gate that must fail before the fix and pass after. Use when the user asks to "fix a bug", "debug this issue", "resolve this error", "patch a defect", "this is broken, fix it", or reports a specific failure they want systematically fixed with a regression test added. Worth the ceremony when: the bug is non-trivial, reproduction isn't obvious, a regression test would prevent recurrence, or the fix needs the full test suite to verify nothing else broke. Do NOT use for one-line typos, missing imports, or obvious null-checks (just fix them directly — the workflow has a fast path but the lookup is still overhead). Do NOT use for hard bugs where the user wants divergent hypotheses before committing to one (use tri-debug). Do NOT use for "something's slow" performance work (use self-perf) or for fixing failing tests specifically (use self-test). --- # Bug Fix diff --git a/skills/feature/SKILL.md b/skills/feature/SKILL.md index 46016f2..6a25d3d 100644 --- a/skills/feature/SKILL.md +++ b/skills/feature/SKILL.md @@ -1,6 +1,6 @@ --- name: feature -description: Build a new feature end-to-end — use when asked to add a feature, build X, implement Y, ship a new capability, or "new feature ...". NOT for /feature-dev:feature-dev which is a separate plugin. Triggers the deterministic feature workflow (triage → brainstorm → plan → implement → test → lint → review). +description: Deterministic full-lifecycle feature workflow (engine-driven, gated, looped) — triage → brainstorm → plan → implement → gen-tests → run-tests → lint → review → final-report. Use when the user asks to "add a feature", "build X", "implement Y", "ship a new capability", "new feature: ...", or wants an end-to-end pass from rough spec to PR-ready implementation with lint and test gates enforced. Worth the ceremony when: the feature is non-trivial (touches multiple files, needs tests, needs a plan), the user wants a structured walk from idea to working code, or wants gated iteration instead of free-form building. Do NOT use for the separate `/feature-dev:feature-dev` plugin — that is an agent-guided collaborative workflow; if the user explicitly invokes that command, respect it. Do NOT use for one-file quick additions (just write the code), bug fixes (use bugfix), or pure refactoring of existing behavior (use refactor). Includes a fast path for trivial changes so the workflow self-adjusts to scale. --- # Feature diff --git a/skills/mega-pr/SKILL.md b/skills/mega-pr/SKILL.md index 4047b94..3b74dde 100644 --- a/skills/mega-pr/SKILL.md +++ b/skills/mega-pr/SKILL.md @@ -1,6 +1,6 @@ --- name: mega-pr -description: Run tri-review and pr-review-toolkit review-pr in parallel for maximum coverage — use when asked for mega PR review, mega-pr, mega review, full PR review, or both review tools at once. +description: Fan-out PR review that runs BOTH `/devkit:tri-review` AND `/pr-review-toolkit:review-pr` in parallel for maximum coverage, then presents unified results — this skill does not compete with its sub-skills, it delegates to both simultaneously. Use when the user asks for "mega PR review", "mega-pr", "mega review", "full PR review with everything", "both review tools", "maximum coverage review", or explicitly wants every available reviewer looking at a change at once (Claude + Codex + Gemini model diversity PLUS specialized aspect reviewers like silent-failure-hunter, type-design-analyzer, test-analyzer, code-reviewer). Worth the extra cost when: the PR is high-stakes and the user wants every angle covered, or before merging a critical or hard-to-revert change. Do NOT use when the user only wants one review system (use tri-review or pr-review-toolkit:review-pr directly). Do NOT use for routine code review where a single reviewer suffices. This is deliberate overkill for when you want absolutely everything. --- # Mega PR Review diff --git a/skills/pr-ready/SKILL.md b/skills/pr-ready/SKILL.md index d7cfc8f..8dcf404 100644 --- a/skills/pr-ready/SKILL.md +++ b/skills/pr-ready/SKILL.md @@ -1,6 +1,6 @@ --- name: pr-ready -description: Full PR pipeline — use when asked to submit a PR, create a pull request, ship this, open a PR, or "make this PR-ready". Runs lint, tests, security scan, generates changelog, creates the PR, and monitors CI + reviewer comments until merge-ready. +description: Full end-to-end PR pipeline — validate → necessity-check → lint (loop) → test (loop) → security scan → doc-check → changelog → create-pr → monitor reviews (loop). Takes a branch from "code done" to "merged" with every gate enforced. Use when the user asks to "submit a PR", "open a pull request", "ship this", "make this PR-ready", "finalize this branch", or wants the full pipeline run end-to-end with CI monitoring and reviewer-comment handling automated. Worth the ceremony when: lint and test gates must pass before the PR opens, docs need syncing alongside code (README, ROADMAP, SKILL.md, workflows), security scan is required, or the user wants reviewer comments automatically classified and responded to. Do NOT use for a quick commit+push+PR without gates — use `/commit-commands:commit-push-pr` for that lighter path. Do NOT use when already mid-PR and just handling existing review comments in isolation. Do NOT use on the main branch or with uncommitted changes — the validate step will block you. This is devkit's heaviest PR workflow; pick it when you want everything run. --- # PR Ready diff --git a/skills/refactor/SKILL.md b/skills/refactor/SKILL.md index 0b86360..09aa9e7 100644 --- a/skills/refactor/SKILL.md +++ b/skills/refactor/SKILL.md @@ -1,6 +1,6 @@ --- name: refactor -description: Refactor code safely — use when asked to refactor, restructure, clean up, reorganize, extract, rename, or modernize a piece of code. Triggers the deterministic refactor workflow (analyze → plan → restructure → verify nothing broke). +description: Deterministic refactor workflow with tests as the safety net — analyze → plan → refactor → run-tests → fix-tests → comparison. The workflow will not exit until tests pass, guaranteeing behavior preservation. Use when the user asks to "refactor", "restructure", "reorganize", "clean up", "extract", "rename across files", or "modernize" existing code that has test coverage. Worth the ceremony when: the refactor spans multiple files, behavior must be preserved exactly, test coverage exists to prove nothing broke, or the user explicitly wants a safety-netted transformation. Do NOT use for renaming a single variable or function in one file (just do it — the workflow overhead isn't worth it). Do NOT use for adding new behavior (use feature) or fixing broken behavior (use bugfix). Do NOT use when there are no tests — the safety net is the entire point; without tests, do the refactor manually with careful review. If the user wants refactoring advice or a discussion (not the transformation), answer directly instead of dispatching the workflow. --- # Refactor