trigger-diagnostics

name: trigger-diagnostics namespace: process description: 'Use WHEN a Supervibe trigger, command route, or skill handoff did not match, matched the wrong flow, or needs explanation TO diagnose intent, missing artifacts, confidence, blockers, and the next safe action.' allowed-tools: - Read - Grep - Glob - Bash phase: review prerequisites: [] emits-artifact: agent-output confidence-rubric: confidence-rubrics/agent-delivery.yaml gate-on-exit: false version: 1 last-verified: 2026-05-02T00:00:00.000Z

Trigger Diagnostics

WorkflowGateV1 Write Hard Rule

No durable writes before intake summary approval. This is a blocking condition for skill execution: WorkflowGateV1 and the active workflow must show a user-visible intake or pre-artifact summary and receive explicit approval before this skill creates or mutates durable artifacts, source files, PRDs, plans, graphs, tasks, prototypes, previews, receipts, or release files. Action phrases such as "do it", "start now", "skip questions", "go ahead", or "use swarm" are intent only and never approval.

Overview

Trigger Diagnostics owns the trigger-diagnostics workflow for the review phase. It reads the triggering request, source artifacts, local runtime state, and required command or receipt proof, then emits agent-output with a concrete decision and handoff. Use it to turn trigger-diagnostics input into a bounded action; return BLOCKED when the source artifact, owner approval, validator output, or runtime receipt is missing.

When to Use

Use this skill when the user asks why a Supervibe phrase, command, trigger, skill selection, or next-step handoff behaved unexpectedly.

Invoke it for:

A phrase did not route to the expected command.
A phrase routed to the wrong skill.
A route was blocked because required artifacts were missing.
A route was blocked by safety gates.
The user asks "why this skill?" or "why did this trigger fail?"
A command, agent, or skill author needs evidence before changing trigger metadata.

Do not use it as a substitute for execution. This is a read-only diagnostic and explanation skill.

Expert Operating Standard

Follow <resolved-supervibe-plugin-root>/docs/references/skill-expert-operating-standard.md: start from source of truth, preserve context evidence, apply scope safety, use real producers with runtime receipts for durable delegated outputs, verify before completion claims, and keep confidence below gate when evidence is partial.

Step 0 - Read Source Of Truth

Read these files before recommending a route change:

<resolved-supervibe-plugin-root>/scripts/lib/supervibe-trigger-intent-corpus.mjs
<resolved-supervibe-plugin-root>/scripts/lib/supervibe-trigger-router.mjs
<resolved-supervibe-plugin-root>/scripts/lib/supervibe-workflow-router.mjs
<resolved-supervibe-plugin-root>/scripts/lib/supervibe-trigger-diagnostics.mjs
<resolved-supervibe-plugin-root>/tests/supervibe-trigger-diagnostics.test.mjs
The command or skill file referenced by the reported route, if any.

If the user provided recent assistant output, include it as evidence. Trigger diagnostics often depends on whether the previous assistant message emitted a NEXT_STEP_HANDOFF block, a plan path, a brainstorm artifact, or an explicit stop condition.

Decision Tree

Did no route match?
  -> classify as corpus gap or keyword gap
  -> recommend adding a fixture only if the phrase is common and unambiguous

Did a route match but artifacts are missing?
  -> report the missing artifact names
  -> ask for exactly one missing artifact or point to its expected path

Did a route match but safety blockers exist?
  -> report each blocker
  -> ask for the explicit gate needed before mutation or execution

Did the wrong skill match?
  -> compare top likely route vs expected route
  -> inspect trigger descriptions and corpus overlaps
  -> propose a metadata or corpus fix with a replay test

Did the route look correct?
  -> explain confidence, command, skill, prerequisites, and next question

Practice Matrix

Diagnostic lane	Evidence	Safe action
No route	exact phrase, corpus search, nearest intent	propose corpus fixture only when phrase is common
Wrong route	top matched route, expected route, overlapping triggers	metadata or corpus fix plus replay test
Missing artifacts	route result and missing artifact list	ask for one artifact or point to expected path
Safety blocker	blocker ids and gate source	explain stop condition; do not bypass
Correct route	confidence, command/skill, prerequisites	answer why it matched and next safe action

Procedure

Capture the exact user phrase. Do not paraphrase it before diagnostics.
Capture available artifacts:
- brainstorm summary
- plan path or plan content
- reviewed-plan marker
- epic id or work item id
- recent NEXT_STEP_HANDOFF
- dirty git state, if it affects safety
Run a diagnostic:
```
node <resolved-supervibe-plugin-root>/scripts/lib/supervibe-trigger-diagnostics.mjs
```
If the library is being called from a command wrapper, pass the phrase and artifacts to diagnoseTriggerRequest().
Read the returned route:
- intent
- command
- skill
- confidence
- matchedPhrase
- missingArtifacts
- safetyBlockers
- nextQuestion
Explain the result in user language. Use one compact evidence block; do not dump the whole corpus.
If the user asked to fix the route, make the smallest metadata or corpus change and add/update a replay test.

Run:

node --test <resolved-supervibe-plugin-root>/tests/supervibe-trigger-diagnostics.test.mjs
npm run validate:trigger-replay
npm run validate:artifact-links

Do not claim the trigger is fixed unless those commands pass.
For repeated trigger replay or route corpus changes, use <resolved-supervibe-plugin-root>/scripts/lib/supervibe-trigger-diagnostics.mjs and npm run validate:trigger-replay; do not maintain manual pass/fail tables across many phrases.
Read the source artifact, owned file paths, graph/task scope, and current project convention; record the evidence path, command, receipt, or runtime state that proves the starting point.
If required source, owner, dependency, runtime boundary, or approval is missing, stop and return BLOCKED with the missing field, impacted artifact, and next action instead of guessing.
After edits or reviewer findings, repair the smallest changed slice, rerun the same scoped command, and record command, exit code, pass/fail status, artifact path, confidence, and remaining blocker before completion.

Output contract

{
  "status": "PASS|FAIL|PARTIAL|BLOCKED|ADVISORY",
  "phrase": "<exact user phrase>",
  "route": {
    "intent": "<intent or none>",
    "command": "<command or none>",
    "skill": "<skill or none>",
    "confidence": "<score or label>",
    "matchedPhrase": "<corpus phrase or fallback>"
  },
  "evidence": {
    "commands": ["<diagnostic or replay command plus exit code>"],
    "artifacts": ["<handoff, plan, corpus, or router files>"]
  },
  "missingArtifacts": ["<artifact names>"],
  "safetyBlockers": ["<blocker ids>"],
  "nextAction": "<ask one artifact question, add replay fixture, repair metadata, or stop>",
  "receipts": ["<runtime receipt ids or none>"]
}

Examples

Worked example: phrase why did this go to plan review? matches a plan route, but diagnostics shows missingArtifacts: ["reviewedPlan"]; ask for the plan path rather than changing the trigger.
Anti-example: a no-development audit phrase routes toward execution and the diagnostic hides the hard stop; return status: FAIL, cite route evidence, and recommend corpus or metadata repair with replay tests.

User Dialogue Discipline

If more information is needed, ask one question per message:

Step N/M: Which artifact should I use to reproduce the route?

Why: Trigger routing depends on the exact available artifact state, not only the phrase. Decision unlocked: This decides whether the issue is a corpus gap, missing-artifact block, or safety gate. If skipped: I will diagnose using only the raw phrase and mark artifact-sensitive conclusions as tentative.

Use recent handoff (recommended) - Best when the issue happened right after a plan, brainstorm, or review output.

Use a file path - Best when a saved plan, spec, or work item should drive the route.

Phrase only - Fastest, but cannot prove artifact-sensitive blockers.

Stop here - Save no changes and return the current uncertainty.

Free-form answer also accepted.

Anti-patterns

Changing triggers without replay evidence: route metadata changes must have a fixture or test.
Ignoring missing artifacts: a matched route with missing prerequisites is not a router bug.
Hiding confidence: users need to know whether the route was exact, fuzzy, or fallback.
Overfitting one phrase: do not add a narrow phrase that damages adjacent intents.
Mutating project state: diagnostics is read-only unless the user explicitly asks for a fix.

When not to use

Do not use this skill to bypass the command or workflow that owns durable artifacts.
Do not use it when source evidence, CodeGraph, or required verification is missing.
Do not use it to replace a specialist producer, worker, or reviewer that must issue runtime evidence.

Common rationalizations

"Trigger Diagnostics can proceed from a vague trigger" fails because the trigger-diagnostics packet must name the triggering request, source artifact, owner, and expected agent-output before durable work starts.
"Skipping trigger-diagnostics command proof is fine" fails when the output affects graph, release, design, security, memory, or user-visible workflow state; collect the named command, receipt, or artifact first.
"Trigger Diagnostics can finish with a general summary" fails because the handoff must include status, evidence, confidence, blockers, and nextAction tied to the trigger-diagnostics decision.

Red flags

Trigger Diagnostics receives a trigger but no source artifact, owner, approval, validator output, or receipt; return BLOCKED and request the missing proof.
Trigger Diagnostics changes or approves agent-output while status, evidence, confidence, or nextAction is absent; rerun the skill and repair the output contract.
Trigger Diagnostics crosses graph, release, design, security, provider, or memory boundaries without the owning command or reviewer receipt; stop and hand off to that owner.

Checklist

Source of truth read.
Scope and owner confirmed.
CodeGraph/memory requirement decided.
Evidence artifact or command recorded.
Stop condition and next handoff clear.

Failure modes

Inline emulation replaces a required producer or reviewer.
Broad use of the skill slows delivery without improving evidence.
Missing verification lets stale assumptions pass as production-ready.

Verification

node --test <resolved-supervibe-plugin-root>/tests/supervibe-trigger-diagnostics.test.mjs
npm run validate:trigger-replay
npm run validate:artifact-links
After a route metadata or corpus repair, rerun the same diagnostic phrase plus the replay validator and record exit code, matched route, confidence, blockers, and next action.

Guard rails

Do not mutate files, provider state, network resources, or external tools unless this skill's procedure and the user approval path allow it.
Do not skip prerequisites, confidence gates, policy gates, or explicit approval gates.
Do not claim completion without concrete verification evidence.
Preserve user-owned content and unrelated worktree changes.

Supporting references

scripts: <resolved-supervibe-plugin-root>/scripts/lib/supervibe-trigger-diagnostics.mjs, <resolved-supervibe-plugin-root>/scripts/lib/supervibe-trigger-router.mjs, <resolved-supervibe-plugin-root>/scripts/lib/supervibe-workflow-router.mjs.
references: <resolved-supervibe-plugin-root>/docs/command-router-ambiguity-policy.md, <resolved-supervibe-plugin-root>/skills/using-supervibe-skills/references/canonical-lifecycle-skill-map.md.
evaluation harness: <resolved-supervibe-plugin-root>/tests/supervibe-trigger-diagnostics.test.mjs, <resolved-supervibe-plugin-root>/tests/supervibe-trigger-router.test.mjs, <resolved-supervibe-plugin-root>/tests/supervibe-commands-routing.test.mjs.
Example/template evidence: worked example and anti-example above; <resolved-supervibe-plugin-root>/templates/skill.md.tpl.
Domain practice pack: no-route, wrong-route, missing-artifact, safety-blocker, and correct-route lanes in the Practice Matrix.

supervibe:workflow-router internal route sentinel
supervibe:requirements-intake for ambiguous new requests
supervibe:requesting-code-review for plan-review handoffs
supervibe:plan for brainstorm-to-plan transitions
<resolved-supervibe-plugin-root>/scripts/lib/supervibe-trigger-intent-corpus.mjs
<resolved-supervibe-plugin-root>/scripts/lib/supervibe-trigger-diagnostics.mjs

Supporting references

Resource tree hardening

references/practice-pack.md - Read when trigger-diagnostics needs deeper load rules, local evidence anchors, gotchas, or a final checklist.
scripts/self-check.mjs - Run with --check before claiming the trigger-diagnostics resource tree is complete; add --json when machine-readable evidence is needed.
evals/regression.json - Use when tuning trigger-diagnostics trigger boundaries or checking should-trigger and should-not-trigger prompts.
examples/workflow.md - Load when a concrete trigger-diagnostics workflow example or anti-example would clarify the next action.
templates/output-contract.md - Use when emitting agent-output so status, evidence, blockers, confidence, and nextAction stay consistent.
<resolved-supervibe-plugin-root>/skills/trigger-diagnostics/schemas/supervibe-trigger-intent.schema.json - Use for owner-local trigger intent corpus validation.