bug: expand ignores recommendedSubtasks: 0 from the complexity report and creates 5 subtasks instead

[gibelium]

Description

When analyze-complexity assigns recommendedSubtasks: 0 to a task — its way of saying "this task is simple enough, it does not need expansion" — expand and expand --all discard that value and generate defaultSubtasks (5) subtasks instead.

The cause is a truthy check on a value that is legitimately 0.

File: scripts/modules/task-manager/expand-task.js#L186-L207

const explicitNumSubtasks = parseInt(numSubtasks, 10);
if (!Number.isNaN(explicitNumSubtasks) && explicitNumSubtasks >= 0) {
    finalSubtaskCount = explicitNumSubtasks;                       // correct: >= 0
} else if (taskAnalysis?.recommendedSubtasks) {
    // 0 is falsy -> this branch is skipped when recommendedSubtasks === 0
    finalSubtaskCount = parseInt(taskAnalysis.recommendedSubtasks, 10);
} else {
    finalSubtaskCount = getDefaultSubtasks(session);               // 0 lands here -> 5
}
if (Number.isNaN(finalSubtaskCount) || finalSubtaskCount < 0) {
    finalSubtaskCount = 3;
}

Note that the branch directly above gets this right: the explicit --num flag is accepted via >= 0, so --num=0 behaves differently from a complexity report saying 0. The Number.isNaN || < 0 guard below does not catch the case either, because by then the value is a perfectly valid 5.

The schema explicitly permits zero — recommendedSubtasks: z.number().int().nonnegative() — so 0 is a value the analysis step is expected to produce, not a malformed one.

This is not the same bug as #1287. That PR (merged 2025-10-11, shipped well before 0.43.1) fixed expand_all never computing and passing complexityReportPath, so taskAnalysis was undefined for every task and the report was ignored wholesale. The report now arrives correctly; this issue is about the report arriving, containing 0, and that specific value being dropped. The user-visible symptom is the same ("5 subtasks instead of the recommendation"), which makes the two easy to confuse.

Steps to Reproduce

Deterministic version, without needing an AI call to produce a 0:

1. Run task-master analyze-complexity on a project.
2. Edit .taskmaster/reports/task-complexity-report.json and set "recommendedSubtasks": 0 for one task.
3. Run task-master expand --id=<that task id>.

Alternatively, run task-master analyze-complexity on a project containing trivial tasks and wait for the model to assign 0 on its own, then run task-master expand --all.

Expected Behavior

recommendedSubtasks: 0 is honoured. The task is left unexpanded and, ideally, reported as skipped — that is what the analysis step meant by 0.

Actual Behavior

The value is ignored, the default of 5 is used, and the task is expanded into 5 subtasks. The log states:

Using default number of subtasks: 5

which is misleading — a recommendation was present and was silently discarded, and the message reads as if no report existed at all.

Suggested Fix

The condition needs a null check rather than a truthy check:

} else if (taskAnalysis?.recommendedSubtasks != null) {
    finalSubtaskCount = parseInt(taskAnalysis.recommendedSubtasks, 10);

That alone makes 0 reach finalSubtaskCount, and the < 0 guard already lets it pass. What should happen next is a design decision I would rather leave to you: sending a "generate 0 subtasks" request to the model is wasteful and its result is not obvious, so skipping expansion for that task entirely — and counting it as skipped in the expand --all summary — seems the more useful behaviour. Happy to open a PR for whichever variant you prefer.

Worth checking as part of the same fix: whether expand --all has a matching filter, so that tasks recommended at 0 are skipped before any AI call is made rather than after.

Environment

• Task Master version: 0.43.1 (current latest on npm). Also verified present in 1.1.0-rc.0 and in the current main branch source.
• Node.js version: 24.19.0
• Operating system: Ubuntu 24.04 LTS (devcontainer)
• IDE (if applicable): VS Code

Additional Context

Verified against three artifacts: the published 0.43.1 bundle, the 1.1.0-rc.0 prerelease bundle, and the unminified source on main — the condition is identical in all three.

[gibelium]

I dug into the source on next and found something that settles the design question I raised at the end of the report — the project already documents what 0 means.

The active prompt template asks the model for it explicitly. From src/prompts/analyze-complexity.json:

recommendedSubtasks: Number of subtasks recommended (non-negative integer; 0 if no expansion needed)

Together with recommendedSubtasks: z.number().int().nonnegative() in src/schemas/analyze-complexity.js, that makes 0 the sanctioned way for the analysis step to say "do not expand this task". The value is requested in one place and discarded in another. So the intended behaviour isn't really open to interpretation: a task recommended at 0 should be left alone, and expand --all shouldn't spend an AI call on it.

There's a convenient hook for that. scripts/modules/task-manager/expand-all-tasks.js still returns a skippedCount, but it has been pinned to 0 since the eligibility pre-filter was introduced:

// Skipped count is always 0 now due to pre-filtering

Filtering tasks recommended at 0 out of tasksToExpand would both fix the bug before any model call happens and give that field a meaning again.

One contradiction worth knowing about

scripts/modules/ui.js:2041 still contains an older inline prompt builder, generateComplexityAnalysisPrompt, which asks for a very different range:

"recommendedSubtasks": number (${Math.max(3, defaultSubtasks - 1)}-${Math.min(8, defaultSubtasks + 2)}),

That instructs the model to never emit anything below 3, directly contradicting the active template. It appears to be dead code — the only references are its definition and its export at line 2858 — so it doesn't affect the bug, but it does mean the two prompts in the tree disagree about whether 0 is legal. Removing it is a cleanup call for you rather than part of a fix.

The same falsy pattern in two other places

While grepping for the field I hit two more spots where a legitimate 0 gets dropped. Both are outside the scope of this bug and I'm noting them only so they're on record:

• packages/tm-core/src/testing/task-fixtures.ts:75 and :151 — ...(overrides.recommendedSubtasks && { recommendedSubtasks: overrides.recommendedSubtasks }). A fixture cannot be built with 0, which is mildly awkward for anyone writing a regression test for this very issue.
• packages/tm-core/src/modules/tasks/services/task-loader.service.ts:177 — if (task.complexity || task.recommendedSubtasks). Cosmetic: a task with recommendedSubtasks: 0 and no complexity score gets the "analyze task complexity first" hint even though it has been analysed.

Offering a PR

Happy to put up a PR against next covering just this issue: the null check in expand-task.js, the pre-filter plus a real skippedCount in expand-all-tasks.js, tests in the two existing expand-*.test.js files, and a changeset. I'd leave the tm-core spots and the dead prompt out so the change stays reviewable — let me know if you'd rather have them folded in, or if you'd prefer to take this one yourselves.

[gibelium]

Correction to my previous comment: the prompt settles only half of the design question. While building the fix I found that 0 already carries a second, conflicting meaning in the expand path, and it is a deliberate one.

In expand, a subtask count of 0 means "you decide how many". From src/prompts/expand-task.json, present in all four variants:

Generate {{#if (gt subtaskCount 0)}}exactly {{subtaskCount}}{{else}}an appropriate number of{{/if}} subtasks

scripts/modules/task-manager/expand-task.js matches it in the loading indicator (Generating ${finalSubtaskCount || 'appropriate number of'} subtasks...), and two existing tests in tests/unit/scripts/modules/task-manager/expand-task.test.js pin the behaviour down:

• should accept 0 as valid numSubtasks value for dynamic generation
• should use dynamic prompting when numSubtasks is 0

Both assert that generateObjectService is called when numSubtasks is 0.

So the same value means opposite things depending on where it comes from:

Source	Meaning of 0
analyze-complexity report	"no expansion needed" (per analyze-complexity.json, schema nonnegative())
explicit --num=0	"dynamic generation — pick an appropriate number"

Both land in the same finalSubtaskCount variable, which is why the distinction disappears.

What this changes about the fix

The one-line null check I proposed is not sufficient on its own — it makes a report value of 0 reach finalSubtaskCount, and expansion would then proceed in dynamic mode, still ignoring the recommendation. Adding an unconditional "skip when 0" on top would break the two tests above.

Keeping the provenance of the value is what resolves it. In my working branch:

• taskAnalysis?.recommendedSubtasks != null instead of the truthy check, with a flag recording that the count came from the report
• skip expansion only when the count is 0 and came from the report, returning before any AI call and reporting skipped: true
• explicit --num continues to outrank the report, --num=0 keeps its dynamic-generation meaning untouched
• expand --all counts those tasks under its existing skippedCount, which has been pinned to 0 since the eligibility pre-filter landed

Full unit suite passes (112 suites / 1343 tests) and the new regression test fails without the fix, generating the 5 default subtasks as reported.

One practical consequence worth stating explicitly, since it is easy to assume otherwise: there is currently no user-side workaround via the flag. --num=0 does not skip a task, it hands the count to the model.

An unrelated note on the test suite

While verifying, I noticed the unit suite is only reliable with a cold Jest cache. On an unmodified next checkout, jest --clearCache followed by a run gives 112 suites / 1340 tests green, while an immediately following run reports 27 suites failing with ReferenceError: You are trying to import a file after the Jest environment has been torn down, alongside A worker process has failed to exit gracefully. Same behaviour with and without my changes, so it is independent of this issue — but it costs a contributor some time to work out that the failures aren't theirs. Happy to open a separate issue if that is useful.

I have the fix ready on a branch and will open a PR against next.