/validator-help

Evidence-based diagnosis of validator behavior. This skill is diagnosis-only — it explains what happened and why, but does not auto-fix issues. It operates from runtime artifacts and CLI outputs, not source code.

Diagnostic Workflow

Follow this order for every diagnostic question:

Resolve
log_dir
: Read
```
.validator/config.yml
```
and extract the
```
log_dir
```
field (default:
```
validator_logs
```
). All log paths below are relative to
```
<log_dir>/
```
.
Passive evidence first: Read files before running commands.
- ```
<log_dir>/.debug.log
```
  — timestamped event log (commands, gate results, state changes, errors)
- ```
<log_dir>/.execution_state
```
  — JSON with
```
last_run_completed_at
```
  ,
```
branch
```
  ,
```
commit
```
  ,
```
working_tree_ref
```
  , and
```
unhealthy_adapters
```
  (adapter name →
```
{marked_at, reason}
```
  )
- ```
<log_dir>/console.*.log
```
  — console output per run (highest number = latest)
- ```
<log_dir>/check_*.log
```
  — check gate output
- ```
<log_dir>/review_*.json
```
  — review gate results with violations (
```
file
```
  ,
```
line
```
  ,
```
issue
```
  ,
```
fix
```
  ,
```
priority
```
  ,
```
status
```
  )
- ```
.validator/config.yml
```
  — project configuration
Active evidence when needed: Run CLI commands only when passive evidence is insufficient for a confident diagnosis.
Explain with evidence: Clearly distinguish confirmed findings from inference.

Evidence Sources

Source	What It Confirms
`.validator/config.yml`	`log_dir` , `base_branch` , `entry_points` , `cli.default_preference` , `max_retries` , `rerun_new_issue_threshold`
`<log_dir>/.debug.log`	Timestamped event history: commands executed, gate results, state transitions, errors
`<log_dir>/.execution_state`	Last successful run timestamp, branch/commit at that time, working tree stash ref, unhealthy adapter cooldowns
`<log_dir>/console.*.log`	Human-readable output from each run iteration
`<log_dir>/check_*.log`	Raw output from check gate commands (linters, test runners, etc.)
`<log_dir>/review_*.json`	Structured review violations with file, line, issue, priority, and resolution status
`<log_dir>/.validator-run.lock`	Lock file (contains PID) — present only during active execution
`<log_dir>/.ci-wait-attempts`	CI wait attempt counter

CLI Command Quick-Reference

Use these only when passive evidence is insufficient:

Command	When to Use
`agent-validate list`	See configured gates and entry points
`agent-validate health`	Check adapter availability and health status
`agent-validate detect`	See which files changed and which gates would apply
`agent-validate validate`	Validate config.yml syntax and schema
`agent-validate clean`	Archive current logs and reset state (destructive — confirm with user first)

Routing Logic

Based on the user's question, load the appropriate reference file for detailed guidance:

Question Domain	Reference File
Missing config, YAML errors, misconfiguration, init problems	`references/config-troubleshooting.md`
Check failures, review failures, no_changes, no_applicable_gates, rerun mode	`references/gate-troubleshooting.md`
Lock conflict, stale locks, parallel runs, cleanup	`references/lock-troubleshooting.md`
Adapter health, missing tools, usage limits, cooldown	`references/adapter-troubleshooting.md`

If the question spans multiple domains, load each relevant reference.

Output Contract

Every diagnostic response MUST include these sections:

Diagnosis

What happened and why, stated clearly.

Evidence

Specific files read, field values observed, and command outputs that support the diagnosis. Quote relevant log lines or config values.

Confidence

One of:

High — diagnosis is fully supported by direct evidence
Medium — diagnosis is likely but some evidence is missing or ambiguous
Low — diagnosis is inferred; key evidence is unavailable

Downgrade confidence when:

```
.debug.log
```
or
```
.execution_state
```
is missing or empty
Log files referenced in output don't exist
Config values can't be verified
CLI commands fail or return unexpected output

Next Steps

Actionable recommendations for the user. If confidence is not high, suggest what additional evidence would confirm the diagnosis.

Bug Filing

After completing your diagnosis, apply the following routing logic to determine whether to file a GitHub issue:

High confidence + bug indicated (evidence points to a defect in agent-validator, not a configuration issue, user error, or expected behavior): Automatically invoke
```
validator-issue
```
with
```
--auto-file <diagnosis summary>
```
as arguments. This passes the diagnosis summary as the bug description and skips the interactive confirmation — the issue is filed immediately after showing the draft.
High confidence + not a bug (diagnosis concludes configuration issue, user error, or expected behavior): Do nothing. Do not invoke
```
validator-issue
```
.
Medium confidence + possible bug (evidence suggests a possible validator defect but is not conclusive): Ask the user: "This may be a validator bug. Want me to file a GitHub issue?" If the user confirms, invoke
```
validator-issue
```
with the diagnosis summary as the bug description. If the user declines, exit without filing.
Low confidence: Do nothing. Do not prompt the user and do not invoke
```
validator-issue
```
.

validator-help

NPX Install

Tags

SKILL.md Content