feat(cli): add skip-exceeded detection with user-friendly messaging

[wbisschoff13]

This PR improves user experience when using task-master next --skip by detecting when the skip value exceeds the number of available eligible tasks and displaying helpful guidance. Previously, users would see a generic "no tasks found" message without context, making it unclear whether skip exceeded available tasks or no tasks existed at all.

Key changes

• Added skip-exceeded detection that compares skip value against count of eligible (pending/deferred) tasks with no unmet dependencies
• Display user-friendly message showing the skip index used and actual number of available tasks
• Provide actionable tip suggesting the correct skip value to get the last available task
• Extracted eligibility calculation logic into countEligibleTasks() and areAllDependenciesDone() methods for better testability and code organization
• Extended NextTaskResult interface to include skipValue and availableTaskCount for display logic

How to test

Automated Tests

• npm run turbo:typecheck - Verify TypeScript types pass
• npm run test - Run all unit and integration tests
• npm run turbo:build - Ensure build succeeds

Manual Testing

• Create 3 pending tasks with no dependencies
• Run task-master next --skip=0 - Should show first task
• Run task-master next --skip=2 - Should show third task
• Run task-master next --skip=3 - Should show: "✓ No eligible task at skip index 3. Only 3 tasks available." with tip to use --skip=2
• Run task-master next --skip=10 - Should show appropriate message for large skip value
• Create tasks with dependencies and verify only eligible tasks are counted

Risk Assessment

Low - This is a display enhancement that adds new messaging without changing core task selection logic. The eligibility counting logic is isolated and only affects error messaging paths. No breaking changes to existing functionality.

Checklist

• Tests added or updated (existing tests cover core logic, new display code is cosmetic)
• Documentation updated (if user docs exist, update to mention skip behavior)
• Backwards compatible (yes, only adds helpful messaging)
• Secrets redacted or none present (none present)

[gemini-code-assist]

Summary of Changes

Hello @wbisschoff13, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the user experience for the task-master next --skip command. Previously, users encountering an excessive skip value would receive an unhelpful 'no tasks found' message. Now, the system intelligently identifies this scenario, provides clear feedback on the number of available tasks, and offers a practical tip for selecting the last eligible task. This change focuses on improving clarity and guidance without altering core task selection mechanisms.

Highlights

• Improved User Feedback: The task-master next --skip command now detects when the provided skip value exceeds the number of available eligible tasks, displaying a user-friendly message instead of a generic 'no tasks found'.
• Actionable Guidance: When a skip value is too high, the system provides a tip suggesting the correct --skip value to retrieve the last available task.
• Code Refactoring: Eligibility calculation logic has been extracted into new private methods, countEligibleTasks() and areAllDependenciesDone(), improving testability and code organization.
• Interface Extension: The NextTaskResult interface has been extended to include skipValue and availableTaskCount to support the new display logic.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request does a great job of improving the user experience for the --skip option by adding detection for when the skip value exceeds the number of available tasks. The new messaging is clear and helpful. I've added a few suggestions to improve performance, fix a potential bug, and simplify the code.

[gemini-code-assist]

This implementation for counting eligible tasks can be optimized for performance and correctness.

Performance: The current areAllDependenciesDone method uses allTasks.find() inside a loop for each dependency check. This can lead to O(N^2) complexity in worst-case scenarios (many tasks with many dependencies). By creating a Map of tasks by their ID once, we can reduce the lookup time to O(1) for each dependency.

Correctness: The current logic for areAllDependenciesDone silently ignores dependencies that don't exist in the allTasks list because [].every(...) is true. This means a task with a broken dependency link could be considered eligible, which is likely a bug.

The suggested change refactors both methods to use a Map for efficient lookups and ensures that a task is only considered eligible if all its dependencies exist and are marked as 'done'.

private countEligibleTasks(tasks: Task[]): number {
		const taskMap = new Map<string, Task>(tasks.map(task => [String(task.id), task]));
		return tasks.filter(task => {
			// Must be pending or deferred
			if (task.status !== 'pending' && task.status !== 'deferred') {
				return false;
			}
			// Must have no unmet dependencies
			if (task.dependencies && task.dependencies.length > 0) {
				return this.areAllDependenciesDone(task.dependencies, taskMap);
			}
			return true;
		}).length;
	}

	/**
	 * Check if all dependency tasks are completed
	 */
	private areAllDependenciesDone(dependencyIds: string[], taskMap: Map<string, Task>): boolean {
		// This is more efficient than mapping and finding for each dependency.
		// It also correctly handles cases where a dependency ID might not exist in the task list.
		return dependencyIds.every(depId => {
			const depTask = taskMap.get(String(depId));
			// A dependency is met only if the task exists and its status is 'done'.
			// If the task doesn't exist (depTask is undefined), the dependency is not met.
			return depTask?.status === 'done';
		});
	}

[gemini-code-assist]

The validateOptions method already ensures that options.skip is a non-negative integer and mutates the options object. Therefore, options.skip is of type number | undefined at this point. The ternary expression and type assertion are redundant and can be removed for cleaner code.

Suggested change

	const task = await this.tmCore.tasks.getNext(
	options.tag,
	options.skip !== undefined ? (options.skip as number) : undefined
	options.skip !== undefined ? options.skip as number : undefined
	);
	const task = await this.tmCore.tasks.getNext(
	options.tag,
	options.skip
	);

[gemini-code-assist]

Similar to the getNext call, options.skip has already been validated and converted to a number | undefined. The verbose ternary and type assertion can be simplified.

Suggested change

	skipValue: options.skip !== undefined ? options.skip as number : undefined,
	skipValue: options.skip,