/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.
1---2name: validator-help3description: 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".4---56# /validator-help78Evidence-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.910## Diagnostic Workflow1112Follow this order for every diagnostic question:13141. **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>/`.152. **Passive evidence first**: Read files before running commands.16 - `<log_dir>/.debug.log` — timestamped event log (commands, gate results, state changes, errors)17 - `<log_dir>/.execution_state` — JSON with `last_run_completed_at`, `branch`, `commit`, `working_tree_ref`, and `unhealthy_adapters` (adapter name → `{marked_at, reason}`)18 - `<log_dir>/console.*.log` — console output per run (highest number = latest)19 - `<log_dir>/check_*.log` — check gate output20 - `<log_dir>/review_*.json` — review gate results with violations (`file`, `line`, `issue`, `fix`, `priority`, `status`)21 - `.validator/config.yml` — project configuration223. **Active evidence when needed**: Run CLI commands only when passive evidence is insufficient for a confident diagnosis.234. **Explain with evidence**: Clearly distinguish confirmed findings from inference.2425## Evidence Sources2627| Source | What It Confirms |28|--------|-----------------|29| `.validator/config.yml` | `log_dir`, `base_branch`, `entry_points`, `cli.default_preference`, `max_retries`, `rerun_new_issue_threshold` |30| `<log_dir>/.debug.log` | Timestamped event history: commands executed, gate results, state transitions, errors |31| `<log_dir>/.execution_state` | Last successful run timestamp, branch/commit at that time, working tree stash ref, unhealthy adapter cooldowns |32| `<log_dir>/console.*.log` | Human-readable output from each run iteration |33| `<log_dir>/check_*.log` | Raw output from check gate commands (linters, test runners, etc.) |34| `<log_dir>/review_*.json` | Structured review violations with file, line, issue, priority, and resolution status |35| `<log_dir>/.validator-run.lock` | Lock file (contains PID) — present only during active execution |36| `<log_dir>/.ci-wait-attempts` | CI wait attempt counter |3738## CLI Command Quick-Reference3940Use these only when passive evidence is insufficient:4142| Command | When to Use |43|---------|-------------|44| `agent-validate list` | See configured gates and entry points |45| `agent-validate health` | Check adapter availability and health status |46| `agent-validate detect` | See which files changed and which gates would apply |47| `agent-validate validate` | Validate config.yml syntax and schema |48| `agent-validate clean` | Archive current logs and reset state (destructive — confirm with user first) |4950## Routing Logic5152Based on the user's question, load the appropriate reference file for detailed guidance:5354| Question Domain | Reference File |55|----------------|---------------|56| Missing config, YAML errors, misconfiguration, init problems | `references/config-troubleshooting.md` |57| Check failures, review failures, no_changes, no_applicable_gates, rerun mode | `references/gate-troubleshooting.md` |58| Lock conflict, stale locks, parallel runs, cleanup | `references/lock-troubleshooting.md` |59| Adapter health, missing tools, usage limits, cooldown | `references/adapter-troubleshooting.md` |6061If the question spans multiple domains, load each relevant reference.6263## Output Contract6465Every diagnostic response MUST include these sections:6667### Diagnosis68What happened and why, stated clearly.6970### Evidence71Specific files read, field values observed, and command outputs that support the diagnosis. Quote relevant log lines or config values.7273### Confidence74One of:75- **High** — diagnosis is fully supported by direct evidence76- **Medium** — diagnosis is likely but some evidence is missing or ambiguous77- **Low** — diagnosis is inferred; key evidence is unavailable7879Downgrade confidence when:80- `.debug.log` or `.execution_state` is missing or empty81- Log files referenced in output don't exist82- Config values can't be verified83- CLI commands fail or return unexpected output8485### Next Steps86Actionable recommendations for the user. If confidence is not high, suggest what additional evidence would confirm the diagnosis.8788## Bug Filing8990After completing your diagnosis, apply the following routing logic to determine whether to file a GitHub issue:9192- **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.93- **High confidence + not a bug** (diagnosis concludes configuration issue, user error, or expected behavior): Do nothing. Do not invoke `validator-issue`.94- **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.95- **Low confidence**: Do nothing. Do not prompt the user and do not invoke `validator-issue`.
codagent-ai