debug-task

name	debug-task
description	Diagnose and fix moon tasks that are broken, misconfigured, or behaving unexpectedly. Use this skill when a moon task is failing, not running, skipped, hanging, producing stale or wrong output, cached when it shouldn't be, re-running every time when it should be cached, or when outputs are empty or missing after a cache hit. Also covers pipeline hangs and freezes, tasks that only work in CI but not locally (or vice versa), tasks skipped by --affected, and task inheritance not applying to a project. Activate on any mention of "moon run" or "moon task" combined with a problem — errors, stale cache, missing outputs, wrong results, "nothing to do", or unexpected behavior. Also use for task options like persistent, runInCI, allowFailure, affectedFiles, mutex, timeout, or cacheLifetime, and for task checks (requirement, condition, fingerprint) that make a task fail, skip, or re-run, and project-level taskOptions defaults. This skill is for diagnosing existing tasks, not for creating new tasks, setting up workspaces, configuring toolchains, or learning moon concepts.
license	MIT
allowed-tools	Bash(moon:*) Read
compatibility	Requires moon >= 2.0.0 CLI installed and a configured moon workspace.
metadata	{"moon-version-min":"2.0.0","moon-version-tested":"2.5.0","category":"debugging","ecosystem":"moonrepo"}

moon task debugger

A workflow-oriented diagnostic skill for troubleshooting moon tasks. This is not a reference manual — it guides you through a structured debugging flow so you can isolate the problem quickly.

For conceptual background, see the moon documentation.

Before you start: Ask the user for the <project>:<task> target to debug. If they haven't provided a specific target, prompt them for it — the diagnostic flow requires a concrete target to inspect.

---

Quick-start: 5-step diagnostic flow

Work through these steps in order. Most issues resolve by step 3.

Step 1: Inspect the resolved task configuration

The first thing to check is whether the task is configured the way the user expects. moon merges configuration from multiple sources (global tasks, project config, inheritance), so the resolved result can surprise people.

# Show the fully resolved task config (with inheritance applied)
moon task <project>:<task>

# Machine-readable version for programmatic inspection
moon task <project>:<task> --json

What to verify:

• command vs script — if the command contains pipes (|), redirects (>), chained commands (&&), or complex syntax, it must use script, not command.
• inputs — are they too broad (**/* captures everything) or too narrow (missing source files)? Check state.defaultInputs (true = using default **/*) and state.emptyInputs (true = explicitly set to []). Both keys are omitted from the JSON entirely when false, as is state.setRunInCi.
• outputs — are they declared for build tasks? Missing outputs means the cache can never hydrate artifacts. In v2.3+, outputs also affect the default cacheStrategy of any task that depends on this one (see Step 4).
• toolchains — is the correct toolchain(s) assigned? An incorrect toolchain means wrong tool versions.
• deps — are task dependencies correct and complete? In v2.3+, each dep entry can carry a cacheStrategy (hash / ignored / ) that controls whether the dep contributes to this task's cache hash. If omitted, the default depends on whether the dep declares outputs.