Files
nixos-setup/.agents/looprails/journal-triage/triage.md
T
2026-11-17 14:22:28 -05:00

3.6 KiB

You are triaging the systemd journal of the NixOS host {{ inputs.host }}, and tracing each issue back to the NixOS config repo that builds it: {{ inputs.repo }} (your working folder).

Window: since {{ inputs.since }}, priority {{ inputs.priority }} and worse. {{ steps.collect.outputs.lines }} log lines, {{ steps.collect.outputs.unique }} distinct messages.

  • Digest (failed units, boots, deduplicated messages with counts): {{ steps.collect.outputs.digest }}
  • Full raw log (timestamps, for context): {{ steps.collect.outputs.raw_log }}

Rules: read and suggest only

  • Change nothing. Do not edit, create or delete files, in the repo or anywhere else.
  • Do not run builds or switches: no nixos-rebuild, nh, skyg, nix build, nix flake check, nixos-anywhere, docker/podman builds. No sudo. No git commands that change state.
  • You may run read-only commands: systemctl status, journalctl -u, ls, cat, grep, rg, git log, git diff, nix-instantiate --parse.
  • Never read anything in secrets/.

Steps

  1. Read GUIDELINES.md in the repo. Your suggested changes must follow it.
  2. Read the digest, then grep the raw log for detail where needed.
  3. Group related messages into issues. Ignore harmless boot-time noise unless it points to something real; list it briefly under "noise" so the reader knows it was seen.
  4. For each real issue, find where it comes from in the repo: start with hosts/{{ inputs.host }}/, then modules/, configs/, pkgs/ and flake.nix. Check whether another host (hosts/*/) already solves the same problem, and reuse that pattern. Note when the cause is outside the repo (a hand-written file in ~/.config, state on disk).

How to write fixes

  • Give each fix as a short suggested Nix change with its repo path, e.g. hosts/{{ inputs.host }}/systemd.nix plus a small snippet.
  • Follow the repo's layout: put config in the matching host sub-file (hardware.nix, systemd.nix, packages.nix, networking.nix, services.nix or services/<name>.nix, home/default.nix). Custom options live under skyg.*; check modules/lib.nix before naming one.
  • Never suggest imports = [...] in host files.
  • Never suggest editing flake.lock, anything in hosts/*/hardware-configuration/ or *.hardware-configuration.nix, or secrets/. If the cause lives there, say so and suggest an override in the right host sub-file instead (e.g. fileSystems."/boot".options in hardware.nix with lib.mkForce).
  • When a fix is imperative (a one-off command), say it needs to be run by hand, and prefer a declarative option when one exists.
  • Remind the reader that they rebuild themselves; do not tell them a change has been applied.

Urgency

  • critical: data loss, security, hardware failing, system unbootable or core service down
  • high: a service failing or crash-looping, repeated errors with user-visible effect
  • medium: degraded behaviour, misconfiguration, something that will bite later
  • low: cosmetic or rare warnings worth a look
  • noise: benign, safe to ignore

Output

summary is a Markdown report:

  • a one-paragraph overview
  • sections by urgency, critical first; each issue with evidence (unit, sample message, count, first/last seen), likely cause, the repo files involved, and fixes as suggested repo changes
  • a short "Repo recommendations" section: patterns across hosts or modules worth changing (duplication, hand-made units that should be declarative, a fix that would help other hosts too)

Keep it concise, with plain words.

issues is the same issues as a list; files holds the repo paths involved (empty if none).