Add actionable suggestions to "workflow not found" errors

[Copilot]

Task: Add actionable suggestions to "workflow not found" errors

Status: ✅ Complete

All acceptance criteria have been met. The implementation adds helpful, actionable suggestions to all "workflow not found" errors across the CLI.

Recent Changes

Formatting fix (per review feedback)

• Ran make fmt to fix trailing whitespace in pkg/console/console.go
• All linting checks pass

Removed "components" terminology (per review feedback)

• Updated error message in pkg/cli/commands.go to remove "or components"
• Updated error message in pkg/cli/run_command.go to remove "or components"
• Updated log message to use ".github/workflows" instead of "components"

Changes Summary

1. Console Package Enhancement

• ✅ Added FormatErrorWithSuggestions function to pkg/console/console.go
• ✅ Added comprehensive unit tests in pkg/console/console_test.go
• Function formats errors with bullet-pointed suggestions for better UX

2. CLI Commands Updated (7+ locations)

• ✅ pkg/cli/commands.go (line 82) - Workflow resolution errors
• ✅ pkg/cli/resolver.go (line 43) - Workflow file not found errors
• ✅ pkg/cli/logs.go (line 362) - Logs command workflow lookup
• ✅ pkg/cli/workflows.go (line 137) - GitHub workflow lookup errors
• ✅ pkg/cli/run_command.go (lines 125, 670) - Run command workflow errors
• ✅ pkg/cli/enable.go (line 170) - Enable/disable command errors
• ✅ pkg/cli/compile_command.go - Fixed error formatting to preserve suggestions

3. Workflow Package Updated

• ✅ pkg/workflow/resolve.go (lines 45, 54, 74) - All three error locations
• ✅ Updated test to match new error format

4. Main Command Updated

• ✅ cmd/gh-aw/main.go - Smart error detection to avoid double formatting
• Detects pre-formatted errors with suggestions and preserves their formatting

5. Testing

• ✅ All unit tests pass (make test-unit)
• ✅ All linting checks pass (make lint)
• ✅ Manual testing confirms suggestions appear correctly
• ✅ Normal workflow compilation still works
• ✅ Error messages are contextual and helpful

Example Output

Current:

✗ workflow 'my-workflow' not found in local .github/workflows

Suggestions:
  • Run 'gh aw status' to see all available workflows
  • Create a new workflow with 'gh aw new my-workflow'
  • Check for typos in the workflow name

Contextual Suggestions

Different commands provide contextually appropriate suggestions:

• Compile errors: Suggest running gh aw status, gh aw new, checking for typos
• Lock file missing: Suggest running gh aw compile or gh aw compile <workflow-id>
• GitHub workflows: Suggest checking if workflow has been compiled and pushed
• Enable/disable: Suggest running status and checking for typos
• Logs command: Suggest using workflow ID or GitHub Actions name format

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[task] Add actionable suggestions to "workflow not found" errors</issue_title>
<issue_description>## Objective
Enhance "workflow not found" error messages across the CLI to include specific recovery actions and helpful suggestions for next steps.

Context

Currently, when users encounter "workflow not found" errors, they receive a minimal error message without guidance on how to resolve the issue. This creates friction during onboarding and workflow discovery. Part of discussion #3888.

Current Behavior

✗ workflow 'my-workflow' not found in local .github/workflows or components

Expected Behavior

✗ workflow 'my-workflow' not found in local .github/workflows or components

Suggestions:
  • Run 'gh aw status' to see all available workflows
  • Create a new workflow with 'gh aw new my-workflow'
  • Check for typos in the workflow name

Implementation Details

Files to Modify

• pkg/cli/commands.go (line 82): Main workflow resolution error
• pkg/cli/resolver.go (lines 42-43): Workflow file not found error
• pkg/cli/logs.go (line 362): Workflow lookup in logs command
• pkg/cli/workflows.go (line 137): GitHub workflow lookup error
• pkg/cli/run_command.go (lines 125, 670): Run command workflow errors
• pkg/cli/enable.go (line 170): Enable command workflow errors
• pkg/workflow/resolve.go (lines 45, 54, 74): Core workflow resolution errors

Pattern to Follow

Create a helper function in pkg/console/console.go:

// FormatErrorWithSuggestions formats an error message with actionable suggestions
func FormatErrorWithSuggestions(message string, suggestions []string) string {
    var output strings.Builder
    output.WriteString(FormatErrorMessage(message))
    output.WriteString("\n\nSuggestions:\n")
    for _, suggestion := range suggestions {
        output.WriteString("  • " + suggestion + "\n")
    }
    return output.String()
}

Then update error messages to use this pattern:

// Before
return fmt.Errorf("workflow '%s' not found in local .github/workflows or components", fileOrWorkflowName)

// After
suggestions := []string{
    fmt.Sprintf("Run '%s status' to see all available workflows", constants.CLIExtensionPrefix),
    fmt.Sprintf("Create a new workflow with '%s new %s'", constants.CLIExtensionPrefix, fileOrWorkflowName),
    "Check for typos in the workflow name",
}
return errors.New(console.FormatErrorWithSuggestions(
    fmt.Sprintf("workflow '%s' not found in local .github/workflows or components", fileOrWorkflowName),
    suggestions,
))

Acceptance Criteria

• New FormatErrorWithSuggestions function added to pkg/console/console.go
• All 7+ "workflow not found" error locations updated to use suggestions
• Suggestions are contextual (e.g., logs command suggests checking workflow status)
• Error messages maintain consistent formatting with existing console package
• Unit tests added for FormatErrorWithSuggestions in pkg/console/console_test.go
• All existing tests pass after changes

Testing Approach

1. Test each modified error path manually with invalid workflow names
2. Verify suggestions appear in terminal output
3. Ensure suggestions are helpful and actionable
4. Run full test suite: make test-unit

Related Files

• Error formatting system: pkg/console/console.go
• Console formatting tests: pkg/console/console_test.go
• Workflow resolution: pkg/workflow/resolve.go
• CLI commands: pkg/cli/*.go

AI generated by Plan Command for discussion #3888</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [task] Add actionable suggestions to "workflow not found" errors #3890

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[pelikhan]

@copilot avoid components terminology

[Copilot]

Removed "or components" terminology from error messages in commit 9717db0.

Updated error message:

✗ workflow 'nonexistent-workflow' not found in local .github/workflows

Suggestions:
  • Run 'gh aw status' to see all available workflows
  • Create a new workflow with 'gh aw new nonexistent-workflow'
  • Check for typos in the workflow name

[pelikhan]

@copilot Lint

[Copilot]

Pull Request Overview

This PR enhances the user experience by adding actionable, contextual suggestions to "workflow not found" errors throughout the CLI. A new FormatErrorWithSuggestions function is introduced in the console package to provide consistent formatting for error messages with bullet-pointed suggestions. The implementation spans 12 files, updating error handling in commands like compile, run, logs, enable/disable, and workflow resolution, ensuring users receive helpful guidance when workflows cannot be found.

Key changes:

• New FormatErrorWithSuggestions helper function in console package with comprehensive test coverage
• Contextually-appropriate error suggestions across 7+ CLI commands (compile, run, logs, enable, workflows, resolver)
• Smart error detection in main command to prevent double-formatting of errors already containing suggestions

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pkg/console/console.go	Added FormatErrorWithSuggestions function to format errors with bullet-pointed actionable suggestions
pkg/console/console_test.go	Added comprehensive unit tests covering multiple scenarios for error formatting with suggestions
pkg/workflow/resolve.go	Updated three error locations in ResolveWorkflowName with contextual suggestions for missing markdown files, lock files, and workflow names
pkg/workflow/resolve_test.go	Updated test expectation to match new error format containing suggestions
pkg/cli/commands.go	Enhanced resolveWorkflowFile error with suggestions and updated log message to remove "components" terminology
pkg/cli/resolver.go	Added suggestions to workflow file not found errors in ResolveWorkflowPath
pkg/cli/logs.go	Updated workflow lookup error in logs command with contextual suggestions for workflow ID vs GitHub Actions name
pkg/cli/workflows.go	Added suggestions to GitHub workflow lookup errors in getWorkflowStatus
pkg/cli/run_command.go	Enhanced two error locations with suggestions: lock file missing and remote workflow validation
pkg/cli/enable.go	Added suggestions to workflow not found errors in enable/disable toggle functionality
pkg/cli/compile_command.go	Modified error handling to print errors directly, preserving pre-formatted suggestions
cmd/gh-aw/main.go	Added smart detection to avoid double-formatting errors that already contain suggestions

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

[nitpick] The trailing newline in the formatted error with suggestions output may cause inconsistent spacing. When this error is later printed with fmt.Fprintln(), it will add an additional newline, resulting in a blank line after the suggestions section. Consider removing the trailing \n on line 447 to maintain consistent spacing.

Suggested change

	for _, suggestion := range suggestions {
	output.WriteString(" • " + suggestion + "\n")
	}
	formatted := make([]string, len(suggestions))
	for i, suggestion := range suggestions {
	formatted[i] = " • " + suggestion
	}
	output.WriteString(strings.Join(formatted, "\n"))

[pelikhan]

@copilot lint

[Copilot]

@copilot Lint

Ran make fmt and make lint - all checks pass. Fixed trailing whitespace in commit 6e43d45.