[plan] Add GoDoc comments for exported GitHub CLI functions

[github-actions]

Objective

Add comprehensive GoDoc comments to the 5 undocumented exported functions in pkg/workflow/github_cli.go to clarify usage, token configuration, authentication requirements, and behavioral differences between variants.

Context

Issue #14844 identified a documentation gap: key exported functions lack GoDoc comments, forcing developers to reverse-engineer behavior from implementation. The file has inline comments (lines 17-19) with good content that should be expanded into proper GoDoc format.

Functions to Document

1. ExecGH (line 25) - Basic gh CLI execution with token handling
2. ExecGHContext (line 59) - Context-aware variant
3. ExecGHWithOutput (line 91) - Captures and returns output
4. RunGH (line 103) - Different execution semantics
5. RunGHCombined (line 125) - Combined stdout/stderr handling

Approach

Follow documentation patterns from pkg/stringutil/stringutil.go and pkg/sliceutil/sliceutil.go:

1. Function Purpose: What does this function do?
2. When to Use: Guidance on choosing between variants
3. Token Handling: How GH_TOKEN/GITHUB_TOKEN affects behavior
4. Parameters: Clear explanation of each parameter
5. Return Values: What's returned and error conditions
6. Example Usage: Simple code example showing common use case
7. Security Notes: Authentication requirements and token precedence

Files to Modify

• Update: pkg/workflow/github_cli.go - Add GoDoc comments above each exported function

Example Structure

// ExecGH wraps gh CLI calls with automatic token configuration.
//
// It attempts to use go-gh/v2 when GH_TOKEN or GITHUB_TOKEN environment
// variables are available, falling back to direct exec.Command for
// backward compatibility when tokens are absent.
//
// Token precedence: GH_TOKEN > GITHUB_TOKEN > unauthenticated mode
//
// Use ExecGH for commands that:
//   - Don't need context cancellation
//   - Don't need to capture output
//   - Should use default stderr/stdout streams
//
// For context-aware execution, use ExecGHContext instead.
// For capturing output, use ExecGHWithOutput instead.
//
// Example:
//   cmd := ExecGH("issue", "list", "--repo", "github/gh-aw")
//   if err := cmd.Run(); err != nil {
//       return fmt.Errorf("failed to list issues: %w", err)
//   }
//
// Authentication: Requires GH_TOKEN or GITHUB_TOKEN for authenticated
// API access. Commands work without tokens but have rate limits.
func ExecGH(args ...string) *exec.Cmd {
    // ...
}

Acceptance Criteria

• All 5 exported functions have GoDoc comments
• Comments explain when to use each variant
• Token configuration behavior is documented
• Each function has a usage example
• Authentication requirements are clear
• Documentation follows Go conventions (starts with function name)
• Differences between ExecGH/RunGH/ExecGHWithOutput are clear
  Related to [sergo] Sergo Report: Documentation-Security-Naming - 2026-02-10 #14844

AI generated by Plan Command for #14844

• expires on Feb 13, 2026, 12:43 AM UTC