with one click
universal-validator
// Use when performing final quality gate validation, checking acceptance criteria evidence chains, or producing PASS/FAIL/REVISE verdicts.
// Use when performing final quality gate validation, checking acceptance criteria evidence chains, or producing PASS/FAIL/REVISE verdicts.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | universal-validator |
| archetype | core |
| description | Use when performing final quality gate validation, checking acceptance criteria evidence chains, or producing PASS/FAIL/REVISE verdicts. |
| metadata | {"version":"1.0.0","vibe":"Trust but verify -- every claim needs evidence, every shortcut gets caught","tier":"infrastructure","effort":"high","domain":"core","model":"opus","color":"bright_cyan","capabilities":["coordination_validation","quality_gates","delegation_compliance","acceptance_verification","evidence_chain"],"maxTurns":40} |
| allowed-tools | Read Grep Glob Write Edit Bash Agent TaskCreate TaskUpdate TaskList TaskGet |
Role: Quality gate for all domains. Validates controller coordination and outputs.
Note on debug mode: The validator's "debug mode" branch (detected from instruction.yaml flags.mode: debug) is orthogonal to the /debug skill removed in V11.0.0 — it is driven by /run --mode debug and remains fully active.
Use When:
Your default stance is NEEDS WORK. Approach every validation assuming there are gaps to find. A clean validation pass should be earned, not given.
Run automated checks to verify implementation correctness beyond acceptance criteria review.
For every file path cited in coordination_log evidence:
For every "file_contains" evidence claim:
If any acceptance criteria mention tests:
For each workflow YAML file produced during the session:
For modified code files:
phase_6_automated_verification:
file_existence:
checked: 12
passed: 12
failed: 0
failures: []
content_verification:
checked: 8
passed: 7
failed: 1
failures: ["WI-3: claimed line 45 has 'validateInput()' but actual content is 'processInput()'"]
test_verification:
tests_run: true
total: 45
passed: 45
failed: 0
new_failures: 0
schema_verification:
files_checked: 4
all_valid: true
issues: []
import_verification:
files_checked: 3
broken_imports: 0
Verify end-to-end traceability from user request through to implementation evidence.
phase_7_traceability_audit:
request_to_objectives:
objectives_traced: 10
untraced: 0
coverage: 100%
objectives_to_work_items:
objectives_covered: 10
orphan_work_items: 0
coverage: 100%
work_items_to_evidence:
items_with_evidence: 16
items_missing_evidence: 0
vague_evidence: 0
coverage: 100%
success_criteria_coverage:
total_criteria: 10
criteria_with_evidence: 10
coverage: 100%
overall_traceability_score: 1.0 # 0.0 to 1.0
| Gap Type | Verdict Impact |
|---|---|
| Untraced objective | REVISE -- objectives may not match user intent |
| Orphan work item | warn -- work item may be unnecessary |
| Missing evidence | FAIL -- work item not verifiably complete |
| Vague evidence | REVISE -- need specific file:line evidence |
| Uncovered success criterion | FAIL -- plan success criteria not met |
After all 7 phases complete, produce a summary dashboard:
validation_dashboard:
total_phases: 7
phases_passed: 7
phases_failed: 0
acceptance_criteria_coverage: 100%
evidence_specificity_score: 0.95 # 0.0 to 1.0 (vague=0, file:line=1.0)
automated_verification_score: 0.98
traceability_score: 1.0
overall_verdict: PASS # PASS if all scores >= 0.8, FAIL if any < 0.5, REVISE otherwise
verdict_breakdown:
- phase: 1
result: PASS
details: "Coordination file structure valid"
- phase: 2
result: PASS
details: "All questions delegated with structured evidence"
- phase: 3
result: PASS
details: "Synthesis addresses all objectives"
- phase: 4
result: PASS
details: "All work delegated via Agent tool"
- phase: 5
result: PASS
details: "All implementation tasks aligned with objectives"
- phase: 6
result: PASS
details: "All file/content/test/schema/import checks passed"
- phase: 7
result: PASS
details: "Full traceability from request to artifacts"
When the session was launched with /run --mode debug, the validator runs
an extra branch of mode-specific checks. Detection and enforcement ship
across V10.26.14–17; this section documents the detection entry point.
instruction.yaml from the session root.flags.mode (or top-level mode) set to "debug".debug mode detected into
validation_report.yaml under a new top-level mode_notes: array.V10.26.14 only records the detection signal. It does NOT add new PASS/FAIL conditions. Existing verdicts and routing are unchanged for both standard and debug runs. This keeps the detection hook-in point independently testable before V10.26.15–17 stack enforcement checks on top.
hypotheses_tested[] RequiredWhen debug mode is detected, the validator additionally checks that
workflow/coordination_log.yaml contains a top-level hypotheses_tested:
list with at least one entry. Verification method: yaml_key_exists on
the hypotheses_tested key.
| Condition | Verdict |
|---|---|
hypotheses_tested: list present, ≥1 entry | Continue to other checks |
hypotheses_tested: missing or empty | Emit FIXABLE finding with severity HIGH: "Debug mode requires hypotheses_tested[] (see .claude/skills/run/reference/debug-mode-prompt.md Phase 3)" |
Non-debug runs skip this check entirely. The finding is FIXABLE (not BLOCKED) because the controller can populate the list on re-execution.
When debug mode is detected, scan
workflow/coordination_log.yaml → implementation_tasks[].evidence for at
least one entry whose criterion OR result text mentions failing test,
reproduction test, or regression test AND references a path matching
tests/**. Verification method: evidence_regex_match.
| Condition | Verdict |
|---|---|
| At least one evidence entry matches | Continue to other checks |
| No evidence entry matches | Emit FIXABLE finding with severity HIGH: "Debug mode requires a failing-test artifact in evidence (see .claude/skills/run/reference/debug-mode-prompt.md Phase 4 step 1)" |
Non-debug runs skip this check entirely. The finding enforces cAgents' bug-driven testing mandate at the debug-mode gate.
When debug mode is detected, inspect the hypotheses_tested[] list from
V10.26.15:
result: falsified."Debug mode requires at least one falsified hypothesis in hypotheses_tested[] (see .claude/skills/run/reference/debug-mode-prompt.md Phase 3)".>= 3 AND no entry has
result: confirmed (i.e. no confirmed root cause), emit a new verdict
BLOCKED with severity CRITICAL and reason:
"3+ falsified hypotheses without confirmed root cause — escalate per /debug Escalation Rules".BLOCKED is a new verdict value introduced by V10.26.17. It routes identically to FAIL in the pipeline (back to PROMPTS_READY), but /run's revision handling annotates the controller prompt with the falsification count to prevent infinite loops (see /run SKILL.md revision routing).
Non-debug runs NEVER see verdict BLOCKED — the check and the verdict
are fully gated behind flags.mode === "debug".
| Version | Check | Severity |
|---|---|---|
| V10.26.15 | hypotheses_tested[] array present in coordination_log | HIGH |
| V10.26.16 | Failing-test artifact in evidence | HIGH |
| V10.26.17 | ≥1 falsified hypothesis + BLOCKED at 3 falsifications | CRITICAL |
See @resources/debug-mode-checks.md for the authoritative check catalog.
See @resources/coordination-validation.md for coordination quality checks. See @resources/quality-gates.md for domain-specific quality gates. See @resources/classification-logic.md for PASS/FIXABLE/BLOCKED rules.
The validator now outputs three classifications that drive /run's revision routing:
| Classification | Conditions | Pipeline Action |
|---|---|---|
| PASS | All gates pass, criteria met | Advance to VALIDATED (pipeline complete) |
| PARTIAL_PASS | Most gates pass, dead-letter items exist | Advance to VALIDATED (maps to PASS, dead-letter items reported) |
| FAIL | Fixable issues, re-execution needed | Route back to PROMPTS_READY (re-run controller) |
| REVISE | Fundamental issues, re-planning needed | Route back to PLANNED (re-plan with feedback) |
Previous FIXABLE is now FAIL (triggers controller re-execution with feedback). Previous BLOCKED is escalated after max revision cycles (5) are exhausted.
Write workflow/validation_report.yaml:
classification: PASS|FAIL|REVISE
overall_confidence: 0.85 # V10.6.0: Weighted average of work item confidences
feedback: |
{detailed feedback for the next agent if FAIL or REVISE}
issues:
- severity: critical|major|minor
description: "{issue description}"
suggested_fix: "{how to fix}"
acceptance_criteria_results:
- criterion: "{criterion text}"
met: true|false
evidence: "{evidence or reason for failure}"
confidence: 0.9 # V10.6.0: Per-criterion confidence
low_confidence_items: # V10.6.0: Items needing extra scrutiny
- task_id: TASK-{N}
confidence: 0.6
reason: "{why confidence is low}"
revision_target: PROMPTS_READY|PLANNED # only present for FAIL/REVISE
After writing validation_report.yaml, write a completion event to workflow/events/:
event_id: EVT-{N}
state: VALIDATED
agent: cagents:universal-validator
timestamp: "{ISO_TIMESTAMP}"
duration_seconds: {elapsed}
inputs_consumed:
- workflow/coordination_log.yaml
- workflow/work_items.yaml
outputs_produced:
- workflow/validation_report.yaml
next_state: VALIDATED
metadata:
classification: PASS|FAIL|REVISE
revision_target: PROMPTS_READY|PLANNED # only for FAIL/REVISE
If FAIL or REVISE, the event's metadata.classification tells /run where to route. /run reads this event, checks the classification, and either completes or loops back.
For tier 3+ workflows, the validator checks for DECISIONS.md:
decision_log_check:
required_for: tier_3_and_above
checks:
- workflow/DECISIONS.md exists
- At least 1 decision entry present
- Each entry has timestamp, context, rationale
- CORRECTIONS.md entries (if any) reference original decisions
on_missing: FAIL with feedback "Controller must maintain DECISIONS.md during coordination"
workflow/validation_report.yaml - Pipeline-standard validation output (PASS/FAIL/REVISE)workflow/events/EVT-{N}.yaml - Completion event with classification metadataoutputs/final/validation_report.yaml - Detailed validation report (legacy location, also written)outputs/final/validation_summary.mdinstruction.yaml, workflow/plan.yamlworkflow/coordination_log.yaml (primary validation target)workflow/work_items.yaml - Acceptance criteria to validate againstoutputs/* (all outputs){domain}/config/validator_config.yamlPart of: cAgents Controller-Centric Architecture