name	nix-build-debug
description	Diagnose Nix/NixOS build and evaluation failures in the Marchyo flake. Use when a `nix build`, `nixos-rebuild`, or `nix flake check` fails — to read the error trace, locate the offending expression, and propose a fix.

Nix Build Debug Skill

Systematic debugging of Nix evaluation and build failures.

Read the trace bottom-up. The last error: line is the proximate cause; the … while frames above it show the path that led there.
Classify the failure:
- Evaluation error (infinite recursion, attribute missing, type error, assertion) — happens before any build; fix the expression.
- Build error (compiler/test failure, hash mismatch, missing dependency) — a derivation failed to realise.
Re-run narrowly: nix eval the failing attr, or nix build .#<attr> --show-trace -L for full logs.

attribute 'X' missing — a typo or an option/package that doesn't exist. For nixpkgs attrs, verify the real name (use the mcp-nixos tool if available).
infinite recursion encountered — usually a config referring to itself, or a missing lib.mkIf/mkDefault causing a cycle. Bisect by commenting blocks.
Hash mismatch (got: / specified:) — copy the got: SRI hash into the derivation's hash/cargoHash/npmDepsHash.
Assertion failure — read the message; Marchyo uses assertions for removed options and required fields (e.g. marchyo.ai.openrouter.apiKeyFile).
Darwin eval breakage — an options/*.nix default referenced a Linux-only package. Keep option files platform-neutral; put package refs in impl modules.

Tests are eval-only (tests/eval/*.nix via testNixOS/withTestUser); a failing test is an evaluation error, not a build.
just check runs nix flake check; just fmt runs treefmt. Both must pass.
The reference build is nix build .#nixosConfigurations.x86_64.config.system.build.toplevel.

name	nix-build-debug
description	Diagnose Nix/NixOS build and evaluation failures in the Marchyo flake. Use when a `nix build`, `nixos-rebuild`, or `nix flake check` fails — to read the error trace, locate the offending expression, and propose a fix.

Systematic debugging of Nix evaluation and build failures.

Read the trace bottom-up. The last error: line is the proximate cause; the … while frames above it show the path that led there.
Classify the failure:
- Evaluation error (infinite recursion, attribute missing, type error, assertion) — happens before any build; fix the expression.
- Build error (compiler/test failure, hash mismatch, missing dependency) — a derivation failed to realise.
Re-run narrowly: nix eval the failing attr, or nix build .#<attr> --show-trace -L for full logs.

attribute 'X' missing — a typo or an option/package that doesn't exist. For nixpkgs attrs, verify the real name (use the mcp-nixos tool if available).
infinite recursion encountered — usually a config referring to itself, or a missing lib.mkIf/mkDefault causing a cycle. Bisect by commenting blocks.
Hash mismatch (got: / specified:) — copy the got: SRI hash into the derivation's hash/cargoHash/npmDepsHash.
Assertion failure — read the message; Marchyo uses assertions for removed options and required fields (e.g. marchyo.ai.openrouter.apiKeyFile).
Darwin eval breakage — an options/*.nix default referenced a Linux-only package. Keep option files platform-neutral; put package refs in impl modules.

Tests are eval-only (tests/eval/*.nix via testNixOS/withTestUser); a failing test is an evaluation error, not a build.
just check runs nix flake check; just fmt runs treefmt. Both must pass.
The reference build is nix build .#nixosConfigurations.x86_64.config.system.build.toplevel.

nix-build-debug