stave diagnose

Diagnose evaluation inputs and results to identify likely causes of unexpected findings.

Diagnose analyzes controls, observations, and optional prior output to explain
why an evaluation produced (or did not produce) certain findings. It is useful
for troubleshooting threshold mismatches, clock skew, and predicate logic.

Inputs:
  --controls      Directory containing YAML control definitions
  --observations    Directory containing JSON observation snapshots
  --previous-output Optional path to existing apply output JSON

Outputs:
  stdout            Diagnostic report (text or JSON with --format json)
  stderr            Error messages (if any)

What it explains:
  - Expected violations but got none (threshold too high, time span too short)
  - Unexpected violations (clock skew, streak reset)
  - Empty findings (no predicate matches, under threshold)
  - Configuration mismatches

Subcommands:
  finding    Deep-dive analysis of a single control/asset violation

Exit Codes:
  0   - No diagnostic issues found
  2   - Invalid input or error
  3   - Diagnostic issues detected
  130 - Interrupted (SIGINT)

Offline-only: reads local files; makes zero network connections; no cloud credentials.

Usage:
  stave diagnose [flags]
  stave diagnose [command]

Aliases:
  diagnose, diag

Examples:
  # Basic diagnosis
  stave diagnose --controls ./controls --observations ./obs

  # Automation/CI mode (exit code only)
  stave diagnose --controls ./controls --observations ./obs --quiet

  # Troubleshooting an existing apply output
  stave diagnose --previous-output previous-run.json --controls ./controls --observations ./obs

  # JSON output for scripting
  stave diagnose --controls ./controls --observations ./obs --format json

  # Show only threshold/span diagnostics
  stave diagnose --controls ./controls --observations ./obs --case expected_violations_none

  # Diagnose from stdin (pipe evaluation output)
  stave apply --controls ./controls --observations ./obs | stave diagnose --previous-output - --controls ./controls --observations ./obs

  # Deep dive into a single finding (subcommand)
  stave diagnose finding --control-id CTL.S3.PUBLIC.001 --asset-id my-bucket \
    --controls ./controls --observations ./obs

Available Commands:
  explain     Generate guided remediation playbook for a finding
  finding     Deep-dive analysis of a single finding
  report      Generate a plain-text report from evaluation output
  trace       Trace predicate evaluation for a single control against a single asset

Flags:
      --case strings             Filter to one or more diagnostic case values
  -i, --controls string          Path to control definitions directory (inferred from project root if omitted) (default "controls")
  -f, --format string            Output format: text or json (default "text")
  -h, --help                     help for diagnose
      --max-unsafe string        Maximum allowed unsafe duration (e.g., 24h, 7d) Resolved default may come from STAVE_* env vars, stave.yaml, user config, or built-in.
      --now string               Override current time (RFC3339). Required for deterministic output
  -o, --observations string      Path to observation snapshots directory (inferred from project root if omitted) (default "observations")
  -p, --previous-output string   Path to existing apply output JSON (optional; if omitted, runs apply internally)
      --signal-contains string   Filter diagnostics by signal substring (case-insensitive)
      --template string          Template string for custom output formatting (supports {{.Field}}, {{range}}, {{json}})

Global Flags:
      --allow-symlink-output   Allow writing output through symlinks (default: refuse)
      --force                  Allow overwriting existing output files
      --log-file string        Write logs to file (default: stderr)
      --log-format string      Log format: text|json (default "text")
      --log-level string       Log level: debug|info|warn|error (overrides -v)
      --log-timestamps         Include timestamps in logs (breaks determinism)
      --log-timings            Include timing information (breaks determinism)
      --no-color               Disable ANSI colors in output
      --path-mode string       Path rendering in errors/logs: base (basename only) or full (absolute paths) Resolved default may come from STAVE_* env vars, stave.yaml, user config, or built-in.
      --quiet                  Suppress output (exit code only) Resolved default may come from STAVE_* env vars, stave.yaml, user config, or built-in.
      --require-offline        Assert offline operation: fail if proxy env vars (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY) are set
      --sanitize               Sanitize infrastructure identifiers (bucket names, ARNs, policies) from output Resolved default may come from STAVE_* env vars, stave.yaml, user config, or built-in.
      --strict                 Enable strict integrity checks for embedded registries and references
  -v, --verbose count          Increase verbosity (-v=INFO, -vv=DEBUG)
  -y, --yes                    Auto-confirm all interactive prompts (distinct from --force which controls file overwriting)

Use "stave diagnose [command] --help" for more information about a command.