Add dedicated debug loggers to 5 pkg files for improved traceability (#20984)

Author: github-actions[bot]

pkg/parser/tools_merger.go

@@ -6,8 +6,12 @@ import (
 	"fmt"
 	"maps"
 	"strings"
+
+	"github.com/github/gh-aw/pkg/logger"
 )
 
+var toolsMergerLog = logger.New("parser:tools_merger")
+
 // mergeToolsFromJSON merges multiple JSON tool objects from content
 func mergeToolsFromJSON(content string) (string, error) {
 	log.Printf("Merging tools from JSON: content_size=%d bytes", len(content))
@@ -158,6 +162,7 @@ func MergeTools(base, additional map[string]any) (map[string]any, error) {
 
 // mergeAllowedArrays merges two allowed arrays and removes duplicates
 func mergeAllowedArrays(existing, new any) []any {
+	toolsMergerLog.Print("Merging allowed arrays")
 	var result []any
 	seen := make(map[string]bool)
 
@@ -190,6 +195,7 @@ func mergeAllowedArrays(existing, new any) []any {
 
 // mergeMCPTools merges two MCP tool configurations, detecting conflicts except for 'allowed' arrays
 func mergeMCPTools(existing, new map[string]any) (map[string]any, error) {
+	toolsMergerLog.Printf("Merging MCP tool configs: existing_keys=%d, new_keys=%d", len(existing), len(new))
 	result := make(map[string]any)
 
 	// Copy existing properties

pkg/workflow/compiler_string_api.go

@@ -6,13 +6,17 @@ import (
 	"path/filepath"
 	"time"
 
+	"github.com/github/gh-aw/pkg/logger"
 	"github.com/github/gh-aw/pkg/parser"
 	"github.com/github/gh-aw/pkg/stringutil"
 )
 
+var compilerStringAPILog = logger.New("workflow:compiler_string_api")
+
 // CompileToYAML compiles workflow data and returns the YAML as a string
 // without writing to disk. This is useful for Wasm builds and programmatic usage.
 func (c *Compiler) CompileToYAML(workflowData *WorkflowData, markdownPath string) (string, error) {
+	compilerStringAPILog.Printf("CompileToYAML: markdownPath=%s", markdownPath)
 	c.markdownPath = markdownPath
 	c.skipHeader = true
 	// Clear contentOverride after compilation (set by ParseWorkflowString)
@@ -94,6 +98,8 @@ func (c *Compiler) ParseWorkflowString(content string, virtualPath string) (*Wor
 		return nil, err
 	}
 
+	compilerStringAPILog.Printf("ParseWorkflowString: frontmatter validated, frontmatter_fields=%d", len(frontmatterForValidation))
+
 	// Build parse result to reuse the rest of the orchestrator pipeline
 	parseResult := &frontmatterParseResult{
 		cleanPath:                cleanPath,

pkg/workflow/mcp_renderer_builtin.go

@@ -5,8 +5,11 @@ import (
 	"strings"
 
 	"github.com/github/gh-aw/pkg/constants"
+	"github.com/github/gh-aw/pkg/logger"
 )
 
+var mcpRendererBuiltinLog = logger.New("workflow:mcp_renderer_builtin")
+
 // RenderPlaywrightMCP generates the Playwright MCP server configuration
 func (r *MCPConfigRendererUnified) RenderPlaywrightMCP(yaml *strings.Builder, playwrightTool any) {
 	mcpRendererLog.Printf("Rendering Playwright MCP: format=%s, inline_args=%t", r.options.Format, r.options.InlineArgs)
@@ -27,6 +30,7 @@ func (r *MCPConfigRendererUnified) RenderPlaywrightMCP(yaml *strings.Builder, pl
 // Per MCP Gateway Specification v1.0.0 section 3.2.1, stdio-based MCP servers MUST be containerized.
 // Uses MCP Gateway spec format: container, entrypointArgs, mounts, and args fields.
 func (r *MCPConfigRendererUnified) renderPlaywrightTOML(yaml *strings.Builder, playwrightConfig *PlaywrightToolConfig) {
+	mcpRendererBuiltinLog.Print("Rendering Playwright MCP in TOML format")
 	customArgs := getPlaywrightCustomArgs(playwrightConfig)
 
 	// Use official Playwright MCP Docker image (no version tag - only one image)
@@ -82,6 +86,7 @@ func (r *MCPConfigRendererUnified) RenderSerenaMCP(yaml *strings.Builder, serena
 // - "docker" (default): Uses Docker container with stdio transport
 // - "local": Uses local uvx with HTTP transport
 func (r *MCPConfigRendererUnified) renderSerenaTOML(yaml *strings.Builder, serenaTool any) {
+	mcpRendererBuiltinLog.Print("Rendering Serena MCP in TOML format")
 	customArgs := getSerenaCustomArgs(serenaTool)
 
 	yaml.WriteString("          \n")
@@ -221,6 +226,7 @@ func (r *MCPConfigRendererUnified) RenderAgenticWorkflowsMCP(yaml *strings.Build
 // renderAgenticWorkflowsTOML generates Agentic Workflows MCP configuration in TOML format
 // Per MCP Gateway Specification v1.0.0 section 3.2.1, stdio-based MCP servers MUST be containerized.
 func (r *MCPConfigRendererUnified) renderAgenticWorkflowsTOML(yaml *strings.Builder) {
+	mcpRendererBuiltinLog.Printf("Rendering Agentic Workflows MCP in TOML format: action_mode=%s", r.options.ActionMode)
 	yaml.WriteString("          \n")
 	yaml.WriteString("          [mcp_servers." + constants.AgenticWorkflowsMCPServerID.String() + "]\n")
 

pkg/workflow/safe_outputs_call_workflow.go

@@ -4,9 +4,12 @@ import (
 	"fmt"
 	"sort"
 
+	"github.com/github/gh-aw/pkg/logger"
 	"github.com/github/gh-aw/pkg/stringutil"
 )
 
+var safeOutputsCallWorkflowLog = logger.New("workflow:safe_outputs_call_workflow")
+
 // ========================================
 // Safe Output Call Workflow Handling
 // ========================================
@@ -70,6 +73,8 @@ func populateCallWorkflowFiles(data *WorkflowData, markdownPath string) {
 // The agent calls this tool to select which worker to activate; the handler writes
 // call_workflow_name and call_workflow_payload outputs for the conditional `uses:` jobs.
 func generateCallWorkflowTool(workflowName string, workflowInputs map[string]any) map[string]any {
+	safeOutputsCallWorkflowLog.Printf("Generating call-workflow tool: workflow=%s, inputs=%d", workflowName, len(workflowInputs))
+
 	// Normalize workflow name to use underscores for tool name
 	toolName := stringutil.NormalizeSafeOutputIdentifier(workflowName)
 
@@ -158,5 +163,6 @@ func generateCallWorkflowTool(workflowName string, workflowInputs map[string]any
 		tool["inputSchema"].(map[string]any)["required"] = required
 	}
 
+	safeOutputsCallWorkflowLog.Printf("Generated call-workflow tool: name=%s, properties=%d, required=%d", toolName, len(properties), len(required))
 	return tool
 }

pkg/workflow/safe_outputs_dispatch.go

@@ -4,9 +4,12 @@ import (
 	"fmt"
 	"sort"
 
+	"github.com/github/gh-aw/pkg/logger"
 	"github.com/github/gh-aw/pkg/stringutil"
 )
 
+var safeOutputsDispatchWorkflowLog = logger.New("workflow:safe_outputs_dispatch")
+
 // ========================================
 // Safe Output Dispatch Workflow Handling
 // ========================================
@@ -68,6 +71,8 @@ func populateDispatchWorkflowFiles(data *WorkflowData, markdownPath string) {
 // The tool will be named after the workflow (normalized to underscores) and accept
 // the workflow's defined workflow_dispatch inputs as parameters.
 func generateDispatchWorkflowTool(workflowName string, workflowInputs map[string]any) map[string]any {
+	safeOutputsDispatchWorkflowLog.Printf("Generating dispatch-workflow tool: workflow=%s, inputs=%d", workflowName, len(workflowInputs))
+
 	// Normalize workflow name to use underscores for tool name
 	toolName := stringutil.NormalizeSafeOutputIdentifier(workflowName)
 
@@ -160,5 +165,6 @@ func generateDispatchWorkflowTool(workflowName string, workflowInputs map[string
 		tool["inputSchema"].(map[string]any)["required"] = required
 	}
 
+	safeOutputsDispatchWorkflowLog.Printf("Generated dispatch-workflow tool: name=%s, properties=%d, required=%d", toolName, len(properties), len(required))
 	return tool
 }