README
¶
Jobman-Diagnose explains why a Jobman job failed and what to do next. The optional, read-only companion turns bounded Jobman evidence into a cited diagnosis with confidence, limitations, recommended actions, and explicit retry advice.
It works locally without configuration, credentials, Python, network access, or a model. Optional AI augmentation adds schema-validated hypotheses through pluggable local or hosted providers without overriding deterministic facts.
[!TIP] Start with
jobman diagnose JOB; no model or configuration is required. See the documentation for installation, AI setup, troubleshooting, and stable data contracts.
Features
| Capability | Jobman-Diagnose provides... |
|---|---|
| Actionable diagnoses | Controlled findings, likely causes, next actions, and retry recommendations |
| Cited evidence | Every factual finding points to exact evidence supplied and sealed by Jobman |
| Deterministic defaults | Useful, reproducible, network-free analysis without a model |
| Guarded AI augmentation | Strict structured generation whose proposals are validated before inclusion |
| Controlled disclosure | Per-profile evidence allowlists, bounded projections, and an exact disclosure manifest |
| Portable reports | Stable JSON, private evidence export, offline diagnosis, and reproducible support bundles |
| Pluggable providers | OpenAI-compatible endpoints, local Ollama, and a bounded command bridge |
| Safe operation | Read-only advice that never signals, retries, mutates, or repairs a job |
[!NOTE] Jobman-Diagnose is currently pre-v1. Check the compatibility contract before combining versions. Generated hypotheses are advisory and uncalibrated; deterministic facts, actions, and retry policy remain authoritative.
Command overview
| Task | Command |
|---|---|
| Diagnose locally | jobman diagnose JOB |
| Add AI hypotheses | jobman diagnose --ai JOB |
| Share intelligently selected redacted causal log context with AI | jobman diagnose --ai-logs JOB |
| Add source near the failing line | jobman diagnose --ai-logs --ai-source limited JOB |
| Add one complete source file | jobman diagnose --ai-logs --ai-source full JOB |
| Include local system constraints | jobman diagnose --system JOB |
| Produce stable machine output | jobman diagnose --json JOB |
| Expand the human audit or control color | jobman diagnose --details JOB, jobman diagnose --color=never JOB |
| Export or replay evidence | jobman-diagnose --export-evidence FILE JOB, jobman-diagnose --from-evidence FILE |
| Create a private support archive | jobman diagnose --support-bundle FILE JOB |
| Inspect AI configuration | jobman diagnose config show, jobman diagnose profiles |
| Test a configured provider/model | jobman diagnose doctor --profile NAME |
Install both binaries on PATH; Jobman's external-command protocol provides
the natural jobman diagnose form. Direct invocation also works:
jobman-diagnose --jobman /absolute/path/to/jobman JOB
Human output is designed for scanning; automation should consume the sealed
jobman.diagnosis_report schema 1 JSON value. Human aliases
such as [E2] and [F1] are report-local, while JSON retains canonical IDs
and digests.
Installation
Install Jobman v1.4.0 or newer first, then choose the package or archive for your system:
| Environment | Recommended installation |
|---|---|
| macOS | brew install ryancswallace/tap/jobman-diagnose |
| Debian or Ubuntu | Configure Cloudsmith, then sudo apt install jobman jobman-diagnose |
| Fedora, RHEL, Rocky, AlmaLinux, Amazon Linux | Configure Cloudsmith, then sudo dnf install jobman jobman-diagnose |
| Alpine Linux | Configure Cloudsmith, then sudo apk add jobman jobman-diagnose |
| Other Linux or Windows | Install a verified archive from the latest release |
Releases include signed APK, DEB, and RPM packages for Linux 386, amd64, and arm64, plus portable CGO-free archives for Linux, macOS, and Windows. See the installation guide for repository setup, exact asset names, upgrades, and checksum, signature, and attestation verification.
Optional AI augmentation
AI mode uses the default profile in the strict per-user diagnosis.yml:
jobman diagnose --ai JOB
jobman diagnose --ai-logs JOB
jobman diagnose --ai-logs --ai-source limited JOB
jobman diagnose config paths
jobman diagnose config validate
jobman diagnose doctor
Use --profile NAME to select another configured model. Supported provider
boundaries are:
| Provider | Intended use |
|---|---|
| OpenAI-compatible Chat Completions | Hosted APIs, vLLM, and other strict-schema compatible servers |
Ollama /api/chat |
Local structured generation |
| Absolute command bridge | A bounded local adapter for another runtime |
Profiles fix the endpoint, model, locality, timeout, credentials by reference,
and allowed evidence classes. AI activation shares bounded metadata, command
arguments, paths, environment variable names—never values—and typed execution
context when the profile permits them. Log bytes remain a separate opt-in via
--ai-logs or --share log_content. Current source text is another separate
opt-in: enable it persistently for a profile with source_context, or override
that profile for one run with --ai-source none|limited|full. Source sharing
always requires a profile that allows source_content.
When log sharing is explicit, Jobman Diagnose ranks exact causal and structured
diagnostic ranges across the collected streams and sends continuous context
windows within the profile ceiling. With no recognized range it uses bounded
terminal output. An implicit live search may examine up to Jobman's 1 MiB
diagnostic limit locally; --log-bytes supplies a smaller explicit bound.
Before relying on a profile, jobman diagnose doctor --profile NAME sends a
fixed synthetic causal probe through the configured provider/model and checks
strict schema support, provenance, citations, semantic validation, and causal
recognition. It sends no job evidence or logs and returns nonzero on failure.
Limited mode sends the profile's configured number of lines before and after
an explicit --source-line, a matching location inferred from the selected runtime log,
or line 1 as a visible fallback; an explicit CLI limited mode retains the
20-lines-per-side default when the profile has no limited source policy. Full
mode sends the exact complete file and fails rather than truncating it. Jobman
Diagnose infers a file only when the recorded direct command names exactly one
supported source path; use --source-file PATH otherwise. Source text is not
redacted and may contain secrets. It is a point-in-time snapshot of the current
file, not proof of the code executed by the recorded run, so pair it with
--ai-logs for grounded diagnosis.
When target output records a source path and line, Jobman Diagnose compares
that location with the selected current file. A different file, an out-of-range
runtime line, or a differing Python traceback source line produces a
source_context_mismatch warning and the current source is withheld from the
provider. A compatible location is still only consistent, not revision proof.
Provider responses are untrusted proposals. Jobman-Diagnose validates their schema, taxonomy, citations, contradictions, actions, and request identity; optional provider failure still returns the deterministic report. See the configuration guide, generation protocol, and security model.
Evidence, offline use, and support
Evidence can be reviewed, transported, and diagnosed without a live Jobman state store:
jobman-diagnose --export-evidence evidence.json JOB
jobman-diagnose --from-evidence evidence.json
jobman-diagnose --from-evidence evidence.json --json --output report.json
Explicit exports use private permissions, atomic publication, and no-overwrite semantics. Support bundles contain selected sealed evidence, reports, disclosure, capabilities, and build metadata—never credentials, environment values, database files, or Jobman's fingerprint key. Review logs and exported evidence before sharing them; configured redaction cannot recognize every possible secret.
Documentation
| Topic | Resource |
|---|---|
| Installation and upgrades | Installation guide |
| AI profiles and providers | Configuration guide |
| Common failures | Troubleshooting guide |
| Privacy and trust boundaries | Security model |
| Stable machine output | Report schema |
| Model request and response contract | Generation protocol |
| Private diagnostic archives | Support bundles |
| Jobman version support | Compatibility contract |
| Component boundaries | Architecture |
| Quality corpus and model evaluation | Evaluation guide |
| Executable multi-language failure lab | Failure labs |
| Release artifacts and verification | Release guide |
Use the issue tracker for reproducible bugs and feature proposals. Report suspected vulnerabilities privately according to the security policy.
Development
Use the included devcontainer or a local Go installation:
make setup
make quick-check
make check
make help lists development, evaluation, documentation, packaging, and
release targets. Production code has no provider SDK dependency, and tests use
copied evidence fixtures, local fake servers, and helper processes rather than
live models or credentials.
See CONTRIBUTING.md for contribution requirements.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
jobman-diagnose
command
Command jobman-diagnose diagnoses bounded evidence exported by Jobman.
|
Command jobman-diagnose diagnoses bounded evidence exported by Jobman. |
|
devel
|
|
|
docscheck
command
Command docscheck verifies relative links and documented contract versions.
|
Command docscheck verifies relative links and documented contract versions. |
|
evaluate
command
Command evaluate runs Jobman Diagnose's checked-in quality corpus.
|
Command evaluate runs Jobman Diagnose's checked-in quality corpus. |
|
evaluationfixtures
command
Command evaluationfixtures regenerates synthetic, nonsecret evaluation evidence.
|
Command evaluationfixtures regenerates synthetic, nonsecret evaluation evidence. |
|
homebrewformula
command
Command homebrewformula generates the Jobman Diagnose Homebrew formula from a release checksum manifest.
|
Command homebrewformula generates the Jobman Diagnose Homebrew formula from a release checksum manifest. |
|
Package diagnosis defines the stable, provider-independent diagnosis report contract emitted by jobman-diagnose.
|
Package diagnosis defines the stable, provider-independent diagnosis report contract emitted by jobman-diagnose. |
|
examples
|
|
|
evaluation-context
Package evaluationcontext supplies non-executable, synthetic source context for evaluation.
|
Package evaluationcontext supplies non-executable, synthetic source context for evaluation. |
|
internal
|
|
|
buildinfo
Package buildinfo contains companion release metadata injected at build time.
|
Package buildinfo contains companion release metadata injected at build time. |
|
cli
Package cli implements the jobman-diagnose executable boundary.
|
Package cli implements the jobman-diagnose executable boundary. |
|
config
Package config loads strict, versioned generated-diagnosis profiles.
|
Package config loads strict, versioned generated-diagnosis profiles. |
|
coreclient
Package coreclient obtains sealed evidence from the Jobman process boundary.
|
Package coreclient obtains sealed evidence from the Jobman process boundary. |
|
doctor
Package doctor verifies one configured provider/model through the complete bounded structured-generation contract without reading job evidence.
|
Package doctor verifies one configured provider/model through the complete bounded structured-generation contract without reading job evidence. |
|
engine
Package engine implements the deterministic diagnosis pipeline.
|
Package engine implements the deterministic diagnosis pipeline. |
|
enrichment
Package enrichment derives bounded, attributed structure from artifacts that Jobman already selected and sealed.
|
Package enrichment derives bounded, attributed structure from artifacts that Jobman already selected and sealed. |
|
evaluation
Package evaluation runs checked-in, nonsecret diagnosis cases and reports safety and correctness metrics.
|
Package evaluation runs checked-in, nonsecret diagnosis cases and reports safety and correctness metrics. |
|
generation
Package generation builds explicit disclosure projections and reconciles untrusted generated proposals with deterministic diagnosis reports.
|
Package generation builds explicit disclosure projections and reconciles untrusted generated proposals with deterministic diagnosis reports. |
|
generationprompt
Package generationprompt owns the trusted provider-facing diagnosis task.
|
Package generationprompt owns the trusted provider-facing diagnosis task. |
|
portablepath
Package portablepath validates path values embedded in persisted documents.
|
Package portablepath validates path values embedded in persisted documents. |
|
presentation
Package presentation renders diagnosis reports without raw artifact content.
|
Package presentation renders diagnosis reports without raw artifact content. |
|
providerhttp
Package providerhttp contains the shared fail-closed HTTP transport policy for structured generator adapters.
|
Package providerhttp contains the shared fail-closed HTTP transport policy for structured generator adapters. |
|
securefile
Package securefile writes explicit exports privately with atomic publication.
|
Package securefile writes explicit exports privately with atomic publication. |
|
sourcecontext
Package sourcecontext collects explicitly approved, point-in-time source snapshots for generated diagnosis.
|
Package sourcecontext collects explicitly approved, point-in-time source snapshots for generated diagnosis. |
|
supportbundle
Package supportbundle creates deterministic, private diagnosis archives.
|
Package supportbundle creates deterministic, private diagnosis archives. |
|
testevidence
Package testevidence builds deterministic contract fixtures for tests.
|
Package testevidence builds deterministic contract fixtures for tests. |
|
Package provider defines the narrow structured-generation seam used by optional model adapters.
|
Package provider defines the narrow structured-generation seam used by optional model adapters. |
|
commandbridge
Package commandbridge implements the bounded local structured-generator protocol over one child process stdin/stdout exchange.
|
Package commandbridge implements the bounded local structured-generator protocol over one child process stdin/stdout exchange. |
|
ollama
Package ollama implements Ollama's local non-streaming /api/chat structured-output contract.
|
Package ollama implements Ollama's local non-streaming /api/chat structured-output contract. |
|
openaicompat
Package openaicompat implements the explicit OpenAI-compatible Chat Completions structured-output transport without an SDK dependency.
|
Package openaicompat implements the explicit OpenAI-compatible Chat Completions structured-output transport without an SDK dependency. |