refactor(cli): improve error handling and code reuse for --skip parameter

[wbisschoff13]

Improves error handling and code organization for the CLI's --skip parameter in the next command. This refactoring enhances code reusability, clarifies variable naming, and provides more descriptive validation error messages.

The changes consolidate duplicate array indexing logic into a reusable helper method and improve error messages with clearer guidance for users. The --skip parameter allows users to skip tasks in the workflow when retrieving the next available task.

Key changes

• Refactored skip indexing logic: Extracted duplicate array access patterns into getSkipIndex() helper method in task-service.ts
• Improved variable naming: Renamed skip to remainingSkip for better clarity about the decrementing counter behavior
• Enhanced error messages: Updated validation errors in CLI to include quotes around invalid values and more explicit format descriptions
• Standardized error handling: Replaced generic Error with TaskMasterError and proper error codes throughout
• Test fix: Updated type assertion in tasks-domain.spec.ts to use as unknown as ConfigManager for stricter type safety

How to test

Automated Tests

• npm run turbo:typecheck ✅ PASSED - All TypeScript type checks successful
• npm run test -w @tm/core -- --run ⚠️ PRE-EXISTING FAILURES - 30 pre-existing test failures unrelated to changes (config loader, task ID validation, runtime state manager)
• npm run test -w @tm/cli -- --run ⚠️ PRE-EXISTING FAILURES - 58 pre-existing integration test failures due to hook timeouts (unrelated to skip parameter)

Manual Testing

• Test tm next --skip 0 - Should return first available task
• Test tm next --skip 1 - Should return second available task
• Test tm next --skip invalid - Should show error: Invalid skip count: "invalid". Must be a non-negative integer (0, 1, 2, ...)
• Test tm next --skip -1 - Should show validation error about non-negative requirement
• Test tm next --format=invalid - Should show error: Invalid format: "invalid". Valid formats are: text, json

Risk Assessment

Low Risk

These are internal refactoring improvements that maintain the same external API and behavior. The changes are:

• Limited to error handling and code organization
• Non-breaking - all existing functionality preserved
• Well-isolated to the skip parameter validation and task retrieval logic
• Type-safe with proper error codes

The pre-existing test failures are unrelated to this refactoring and were already present in the codebase. The changes themselves are straightforward improvements that follow the DRY principle and enhance code maintainability.

Checklist

• Tests added or updated - Fixed type assertion in existing test
• Documentation updated - N/A (internal refactoring, no user-facing changes)
• Backwards compatible - Yes, all changes maintain existing behavior
• Secrets redacted or none present - No secrets in this PR

[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 focuses on improving the robustness and maintainability of the CLI's --skip parameter logic within the next command. It refactors the task skipping mechanism by introducing a reusable helper method, clarifies variable names for better readability, and significantly enhances the descriptiveness and standardization of validation error messages. These internal improvements are non-breaking and aim to make the codebase more resilient and easier to understand without altering external API behavior.

Highlights

• Refactored Skip Indexing Logic: Duplicate array access patterns for skipping tasks have been extracted into a reusable getSkipIndex() helper method within task-service.ts.
• Improved Variable Naming: The variable skip was renamed to remainingSkip to more accurately reflect its behavior as a decrementing counter during task retrieval.
• Enhanced Error Messages: Validation errors in the CLI for the --skip parameter now include quotes around invalid values and provide more explicit format descriptions for user clarity.
• Standardized Error Handling: Generic Error objects have been replaced with TaskMasterError and appropriate ERROR_CODES throughout the relevant code, improving error classification and handling.
• Test Fix: A type assertion in tasks-domain.spec.ts was updated to use as unknown as ConfigManager for stricter TypeScript type safety.

🧠 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 is a solid refactoring that improves error handling and code reuse for the --skip parameter. The changes are well-executed, with clearer variable names, more descriptive error messages, and standardized error types using TaskMasterError. The extraction of the array indexing logic into a getSkipIndex helper method is a great example of the DRY principle.

I have a couple of suggestions to further enhance consistency and maintainability, mainly around making error messages more uniform and refining the new helper method. Overall, these are great improvements to the codebase.

[gemini-code-assist]

For consistency with the improved error message for the --skip parameter, it would be best to also quote the invalid value in the format validation error. This makes the error messages uniform and clearer for the user.

Suggested change

	throw new TaskMasterError(
	`Invalid format: ${options.format}. Valid formats are: text, json`,
	ERROR_CODES.VALIDATION_ERROR
	);
	throw new TaskMasterError(
	`Invalid format: "${options.format}". Valid formats are: text, json`,
	ERROR_CODES.VALIDATION_ERROR
	);

[gemini-code-assist]

This new helper method is a great refactoring to keep the code DRY. It can be further improved:

1. Since it doesn't access any instance properties (it doesn't use this), it can be declared as static. This signals that it's a pure utility function that doesn't depend on the state of a TaskService instance.
2. The implementation can be made more concise by using the nullish coalescing operator (??). Accessing an array index out of bounds in JavaScript returns undefined, so items[skip] ?? null is a succinct way to return the item or null.

Suggested change

	private getSkipIndex<T>(items: T[], skip: number): T | null {
	if (skip < items.length) {
	return items[skip];
	}
	return null;
	}
	private static getSkipIndex<T>(items: T[], skip: number): T | null {
	if (skip < items.length) {
	return items[skip];
	}
	return null;
	}