# Validator Help

> Diagnoses and explains validator behavior from runtime evidence for requests such as "why did validator fail", "explain validator behavior", "diagnose validator logs", or "what went wrong in the validator run".

- Skill: `codagent-ai/validator-help` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add codagent-ai/validator-help`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codagent-ai/validator-help/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codagent-ai (https://skillmd.com/u/codagent-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/codagent-ai/validator-help

---


# /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:

1. **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>/`.
2. **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
3. **Active evidence when needed**: Run CLI commands only when passive evidence is insufficient for a confident diagnosis.
4. **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`.