Reference

Diagnostic skill

A forward-deployed Argus expert you run inside your own agentic tool. Point it at your Argus artifacts and it explains what happened, whether it's working as designed or a real bug, and writes a report you can share with your team.

What it is

Argus is deterministic, so everything it did is written down: in report.json, the logs, the generated patches, and the PDF. The hard part is reading those artifacts with expert knowledge of the exact Argus version you’re running, so you can tell “working as designed” apart from a genuine bug. That’s what the argus-diagnostic skill does.

It’s a skill you load into your own agentic coding tool (anything that supports Claude skills). It runs entirely in your environment, reads the files you give it, asks you a few targeted questions, and produces a shareable diagnostic report. It ships versioned to a specific Argus release (currently 4.2.1) so its analysis matches the binary you run.

Install the skill

The skill ships alongside the Argus binaries for each release, as argus-diagnostic-skill.zip. Download it from the release, then add it to your agentic tool the same way you add any Claude skill: drop it into your tool’s skills directory (for Claude Code, ~/.claude/skills/, or the project’s .claude/skills/). Your tool will pick it up automatically; there is nothing to configure.

Prep: gather the files

The more artifacts you provide, the sharper the diagnosis. If you can re-run Argus, do so with diagnostics turned up first. The debug anchor.log is often what settles “why did it pick that version?”. You don’t need every file to start: report.json, config.yml, and the full CI job log are enough for most questions.

terminal

# Re-run with full diagnostics on (safe; --no-publish writes locally only)
ARGUS_PDF_REPORT=1 argus run \
  --pom pom.xml --config config.yml \
  --out patches --report report.json \
  --no-publish --log-level debug

# The files the skill will want:
#   report.json            the plan (strategies, residuals, resolved_transitives)
#   report-anchor.log      per-candidate anchor/parent upgrade reasoning
#   config.yml             your libraries / couplings / registries policy
#   patches/               the generated patch POM(s)
#   patches/report.pdf     the PDF report (from ARGUS_PDF_REPORT=1)
#   bom.json               the CycloneDX SBOM Argus resolved (if you have it)
#   <your CI job log>       the full job log, not a snippet

# Re-run with full diagnostics on (safe; --no-publish writes locally only)
ARGUS_PDF_REPORT=1 argus run \
  --pom pom.xml --config config.yml \
  --out patches --report report.json \
  --no-publish --log-level debug

# The files the skill will want:
#   report.json            the plan (strategies, residuals, resolved_transitives)
#   report-anchor.log      per-candidate anchor/parent upgrade reasoning
#   config.yml             your libraries / couplings / registries policy
#   patches/               the generated patch POM(s)
#   patches/report.pdf     the PDF report (from ARGUS_PDF_REPORT=1)
#   bom.json               the CycloneDX SBOM Argus resolved (if you have it)
#   <your CI job log>       the full job log, not a snippet

Invoke it

Open your agentic tool in a folder containing the artifacts, then describe what you saw and what you expected, and mention the skill by name. Be concrete: the coordinate, the strategy you saw, the strategy you expected. The skill will read the files, ask any follow-up questions it needs, and work toward an evidence-backed conclusion.

prompt

Use the argus-diagnostic skill. Argus opened an OVERRIDE for
tools.jackson.core:jackson-databind but I expected it to upgrade the
json-utils dependency instead. I've attached report.json, report-anchor.log,
config.yml and the CI job log. What happened, and is it a bug?

Use the argus-diagnostic skill. Argus opened an OVERRIDE for
tools.jackson.core:jackson-databind but I expected it to upgrade the
json-utils dependency instead. I've attached report.json, report-anchor.log,
config.yml and the CI job log. What happened, and is it a bug?

It will reason from your artifacts (the plan in report.json, the per-candidate trial log in anchor.log, your config.yml policy, the SBOM, and the run log), cross-reference them, and tell you the most likely explanation with the exact lines that support it. Often the answer is “working as designed, and here’s how to get the outcome you wanted”; sometimes it’s “this looks like a bug, here’s the evidence.”

The skill produces a self-contained report (summary, environment, evidence, analysis, verdict, and any still-missing information) written to stand on its own. To act on it:

Review the report and confirm the redaction checklist the skill applied (tokens, internal registry URLs, and private coordinates should already be masked, but double-check).
Share it with your team or security owner. A minimal pom.xml + config.yml that reproduces it (redacted) alongside the report turns a “maybe” into a fix.

Privacy

The skill runs entirely inside your agentic tool and reads only the files you give it. It never sends your code or artifacts anywhere. The only thing that leaves your environment is the report you choose to share, and only after you’ve reviewed the redactions. Nothing is uploaded automatically.