[repository-quality] 🎯 Repository Quality Improvement Report - Large File Decomposition Debt (2026-08-24)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Large File Decomposition Debt

Analysis Date: 2026-08-24
Focus Area: Large File Decomposition Debt (Go source file size vs. repo's own guideline)
Strategy Type: Custom
Custom Area: Yes — the repo's own developer-code-organization skill documents a strict "100–500 lines, one file per functionality" convention with create_issue.go/create_pull_request.go as exemplars, but a scan shows 32 non-test files exceed 800 lines (2–10x the guideline), concentrated in the two largest packages (pkg/cli, pkg/workflow). This is a repo-specific process drift worth surfacing rather than a generic "code quality" pass.

Executive Summary

gh-aw's own coding conventions call for small, focused Go files (100–500 lines) organized by functionality, with named exemplars like create_issue.go (160 lines). A repository-wide scan found 32 non-test .go files exceeding 800 lines — some over double the upper guideline — with pkg/cli (15 files) and pkg/workflow (12 files) accounting for the vast majority. The largest offenders are pkg/workflow/safe_outputs_handler_registry.go (1091 lines, a single 49-entry map of handler builder closures), pkg/workflow/awf_config.go (1090 lines, 19 functions mixing schema validation, config building, and policy resolution), pkg/cli/add_command.go (1078 lines, 32 functions spanning command wiring, tracking, and validation), and pkg/cli/logs_metrics.go / pkg/cli/audit_report.go / pkg/cli/audit_diff.go (~1000–1060 lines each).

These files are actively maintained (safe_outputs_handler_registry.go and awf_config.go were both touched today), so decomposition debt is accumulating in high-churn areas rather than settling in stable legacy code — precisely where the file-size guideline provides the most value for review-ability and merge-conflict avoidance. The recommended remediation splits each flagged file along its natural functional seams (e.g., one file per handler category in the registry, schema/build/policy separation in awf_config.go) following the existing "many small files" pattern already used elsewhere in the codebase.

Full Analysis Report

Focus Area: Large File Decomposition Debt

Current State Assessment

The codebase totals 288,104 source LOC across 1,303 non-test Go files (average ~221 LOC/file), which is healthy in aggregate — but the distribution is skewed: 32 files (2.5% of files) exceed 800 lines, several approaching or exceeding 1,100.

Metrics Collected:

Metric	Value	Status
Non-test Go files	1,303	✅
Files >800 lines	32	⚠️
Files >1,000 lines	10	⚠️
Largest file	pkg/workflow/safe_outputs_handler_registry.go (1,091 lines)	⚠️
pkg/cli files >800 lines	15	⚠️
pkg/workflow files >800 lines	12	⚠️
Guideline (per developer-code-organization skill)	100–500 lines/file	—
Test-to-source LOC ratio	560,879 / 288,104 (~1.95x)	✅
TODO/FIXME markers (non-test)	~20	✅

Findings

Strengths

• Overall average file size (~221 LOC) is well within guideline; the problem is concentrated, not systemic.
• Test coverage volume is strong relative to source (nearly 2x LOC), suggesting decomposition can be done with reasonable safety net.
• Several files already follow the desired pattern precisely (e.g., create_issue.go, add_comment.go), showing the convention is known and achievable — it's a matter of applying it consistently to newer/growing files.

Areas for Improvement

• [High] pkg/workflow/safe_outputs_handler_registry.go (1,091 lines) is a single handlerRegistry map literal with 49 inline closures — this actively fights the "one file per entity" pattern used elsewhere (e.g., create_issue.go).
• [Medium] pkg/workflow/awf_config.go (1,090 lines, 19 top-level functions) mixes schema validation (validateAWFConfigJSON), config construction (BuildAWFConfigJSON), and policy/domain resolution (resolveModelPolicyForAWFConfig, intersectModelPolicyRules) in one file — these are separable concerns.
• [Medium] pkg/cli/add_command.go (1,078 lines, 32 functions) spans command flag registration, workflow resolution, file tracking, and compilation triggering — a prime candidate for splitting by responsibility.
• [Low] pkg/cli/audit_report.go (1,049) and pkg/cli/audit_diff.go (1,017) are twin large files in the audit subsystem that could share a pkg/cli/audit/ extraction pattern already partially started (audit_diff_render.go exists).

Detailed Analysis

The safe_outputs_handler_registry.go map (lines 58–1091) defines one closure per safe-output handler key (create_issue, add_comment, create_pull_request, etc.), each building a config map from typed fields via a fluent builder. This structure is naturally partitionable: splitting into files grouped by output category (e.g., handler_registry_issues.go, handler_registry_pull_requests.go, handler_registry_projects.go) with the registry itself only assembling references would bring each file under 300 lines and make future handler additions low-risk. The 4 helper functions at the top (resolveHandlerGitHubToken, etc.) already live cleanly outside the map and can stay in a slim safe_outputs_handler_registry.go core file that imports the split registries via init()-time merges or direct map literals per file.

awf_config.go's 19 functions cluster into three groups by name prefix and purpose: schema/validation (getCompiledAWFConfigSchema, validateAWFConfigJSON, normalizeTemplatableModelFallbackEnabled), the main builder (BuildAWFConfigJSON, buildAWFConfigSchemaURL), and policy/domain resolution (resolveModelPolicyForAWFConfig, intersectModelPolicyRules, unionModelPolicyRules, extractPlatformType, extractModelFallback, hasCustomLLMAPITarget, extractDefaultAiCreditsPricing, resolveAWFContainerAgentTimeoutMinutes, buildAWFTopologyAttachList, splitDomainList). Extracting the policy/domain group into awf_config_policy.go alone would remove roughly 250–300 lines from the primary file.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Split safe-output handler registry by category

Priority: High
Estimated Effort: Medium
Focus Area: Code Organization

Description: pkg/workflow/safe_outputs_handler_registry.go (1,091 lines) contains a single handlerRegistry map with 49 inline builder closures for every safe-output handler type. Split the map entries into multiple files grouped by logical category (issues/comments, pull requests, labels/reviewers, projects, misc/dispatch), keeping the shared helper functions (resolveHandlerGitHubToken, resolveApproveWorkflowRunGitHubToken, resolveHandlerGitHubTokenWithStepID, handlerSupportsPerHandlerGitHubAppToken) and the top-level handlerRegistry variable declaration in a slim core file that merges the category maps together.

Acceptance Criteria:

• safe_outputs_handler_registry.go reduced to under 300 lines (core helpers + registry assembly only)
• New files created per category (e.g., safe_outputs_handler_registry_issues.go, safe_outputs_handler_registry_pull_requests.go, safe_outputs_handler_registry_projects.go, safe_outputs_handler_registry_misc.go), each under 500 lines
• All existing tests in pkg/workflow pass unchanged (no behavior change, pure extraction)
• make fmt run after the split

Code Region: pkg/workflow/safe_outputs_handler_registry.go (lines 58–1091, the handlerRegistry map literal)

Refactor pkg/workflow/safe_outputs_handler_registry.go to split the large `handlerRegistry` map (currently ~49 entries, lines 58-1091) into multiple smaller files grouped by category, following the repo's file-organization convention documented in .github/skills/developer-code-organization/SKILL.md (100-500 line files, one concern per file). Keep the helper functions at the top of the original file (resolveHandlerGitHubToken, resolveApproveWorkflowRunGitHubToken, resolveHandlerGitHubTokenWithStepID, handlerSupportsPerHandlerGitHubAppToken) and the `handlerRegistry` variable declaration itself in the original file, but move each category's map entries into separate `var` blocks in new files (e.g., safe_outputs_handler_registry_issues.go for create_issue/close_issue/update_issue/add_labels/remove_labels/replace_label/set_issue_type/set_issue_field, safe_outputs_handler_registry_pull_requests.go for all PR-related handlers, safe_outputs_handler_registry_projects.go for project/milestone handlers, safe_outputs_handler_registry_misc.go for the rest). Merge the category maps into the single `handlerRegistry` map using Go's map literal spread via a helper function or by combining maps at package init. Run `go build ./...` and `go test ./pkg/workflow/...` to confirm no behavior changes, then run `make fmt`.

---

Task 2: Extract policy/domain resolution logic from awf_config.go

Priority: Medium
Estimated Effort: Small

Description: pkg/workflow/awf_config.go (1,090 lines) mixes three concerns: schema validation, AWF config building, and model-policy/domain resolution. Extract the policy/domain resolution functions (resolveModelPolicyForAWFConfig, intersectModelPolicyRules, unionModelPolicyRules, extractPlatformType, extractModelFallback, hasCustomLLMAPITarget, extractDefaultAiCreditsPricing, resolveAWFContainerAgentTimeoutMinutes, buildAWFTopologyAttachList, splitDomainList) into a new file pkg/workflow/awf_config_policy.go.

Acceptance Criteria:

• awf_config.go reduced by ~250-300 lines
• New pkg/workflow/awf_config_policy.go file created containing the extracted functions, package-level var/const dependencies moved or kept accessible
• go build ./... and go test ./pkg/workflow/... pass with no functional changes
• make fmt run after the split

Code Region: pkg/workflow/awf_config.go (lines 827–1029, policy/domain resolution functions)

In pkg/workflow/awf_config.go, extract the model-policy and domain-resolution helper functions (resolveAWFContainerAgentTimeoutMinutes, buildAWFTopologyAttachList, splitDomainList, resolveModelPolicyForAWFConfig, intersectModelPolicyRules, unionModelPolicyRules, extractPlatformType, extractModelFallback, hasCustomLLMAPITarget, extractDefaultAiCreditsPricing — roughly lines 827 to 1029) into a new file pkg/workflow/awf_config_policy.go in the same `workflow` package, keeping identical signatures and behavior (pure move, no logic changes). Ensure any package-level logger vars or shared helpers they depend on remain accessible (either keep them in awf_config.go and reference across files in the same package, or duplicate import statements as needed). After the move, run `go build ./...` and `go test ./pkg/workflow/... -run AWFConfig` (or the full pkg/workflow test suite) to confirm nothing broke, then run `make fmt`.

---

Task 3: Decompose add_command.go by responsibility

Priority: Medium
Estimated Effort: Medium

Description: pkg/cli/add_command.go (1,078 lines, 32 functions) spans cobra command wiring, workflow resolution/tracking, git-attributes handling, and compilation triggering. Split into focused files: command wiring/flags, workflow add orchestration (tracking + resolution), and post-add compilation/reporting.

Acceptance Criteria:

• add_command.go reduced to under 500 lines (command definition + flag registration only)
• New files created, e.g. add_workflow_tracking.go (git-attributes + FileTracker helpers: prepareGitAttributesTracking, trackGitAttributesIfCreated, addWorkflowsWithTracking, addWorkflowWithTracking) and add_workflow_compile.go (compileAddedWorkflow, reportAddWorkflowStart, validateWorkflowDestination)
• go build ./... and go test ./pkg/cli/... pass unchanged
• make fmt run after the split

Code Region: pkg/cli/add_command.go (lines 296–528, workflow tracking/compilation helpers)

Refactor pkg/cli/add_command.go (1,078 lines) by extracting cohesive groups of functions into new files within pkg/cli, following the repo convention of one file per functional concern (documented in .github/skills/developer-code-organization/SKILL.md). Move the git-attributes and file-tracking helpers (prepareGitAttributesTracking, trackGitAttributesIfCreated, addWorkflowsWithTracking, addWorkflowWithTracking — around lines 303-454) into a new file pkg/cli/add_workflow_tracking.go. Move the compilation and destination-validation helpers (reportAddWorkflowStart, validateWorkflowDestination, addResourceFileWithTracking, compileAddedWorkflow — around lines 454-590) into a new file pkg/cli/add_workflow_compile.go. Keep NewAddCommand, runAddCommand, rejectBootstrapProfileForRegularAdd, registerAddCommandFlags, AddWorkflows, AddResolvedWorkflows, and addWorkflows in add_command.go as the core command-wiring file. This is a pure code move with no behavior changes — do not alter function bodies. After moving, run `go build ./...` and `go test ./pkg/cli/... -run Add` (or the full pkg/cli suite) to confirm nothing broke, then run `make fmt`.

---

Task 4: Consolidate audit_report.go and audit_diff.go under a shared package pattern

Priority: Low
Estimated Effort: Large

Description: pkg/cli/audit_report.go (1,049 lines) and pkg/cli/audit_diff.go (1,017 lines) are two large sibling files in the audit subsystem; a third file, audit_diff_render.go (858 lines), already exists as a partial split of rendering logic out of audit_diff.go. Apply the same rendering/logic separation to audit_report.go, and review whether both files' data-model/struct definitions can move to a shared audit_types.go to reduce duplication and individual file size.

Acceptance Criteria:

• audit_report.go split so report-generation logic and rendering/formatting logic live in separate files (e.g., audit_report.go + audit_report_render.go), mirroring the existing audit_diff.go/audit_diff_render.go pattern
• Each resulting file is under 700 lines
• go build ./... and go test ./pkg/cli/... -run Audit pass unchanged
• make fmt run after the split

Code Region: pkg/cli/audit_report.go (entire file, 1,049 lines)

pkg/cli/audit_report.go (1,049 lines) has no rendering-logic split, unlike its sibling pkg/cli/audit_diff.go which already has a companion pkg/cli/audit_diff_render.go (858 lines) for output formatting. Analyze audit_report.go's functions, identify which ones handle data collection/analysis versus output formatting/rendering (look for functions with "render", "format", "print", "Table", "Markdown" in their names or that primarily build display strings), and extract the rendering-focused functions into a new pkg/cli/audit_report_render.go file, following the same split pattern already established for the audit_diff.go / audit_diff_render.go pair. This is a pure code-organization move — no logic changes. After the split, run `go build ./...` and `go test ./pkg/cli/... -run Audit` to confirm no regressions, then run `make fmt`.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-08-24	Large File Decomposition Debt	Custom	Y	First run — established baseline: 32 non-test Go files exceed 800 lines, concentrated in pkg/cli (15) and pkg/workflow (12); generated 4 decomposition tasks

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split safe_outputs_handler_registry.go by handler category — Priority: High

Short-term Actions (This Month)

1. Extract policy/domain logic from awf_config.go — Priority: Medium
2. Decompose add_command.go by responsibility — Priority: Medium

Long-term Actions (This Quarter)

1. Consolidate audit report/diff rendering split — Priority: Low
2. Establish a lint rule or CI check that flags new Go files exceeding ~600 lines to prevent future regrowth

---

📈 Success Metrics

• Files >800 lines (non-test): 32 → Target: <15
• Largest file size: 1,091 lines → Target: <600 lines
• pkg/cli files >800 lines: 15 → Target: <8

---

Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on improvement items
4. Re-evaluate this focus area in 1–2 months, or sooner via the 10% reuse path if decomposition proves high-impact

---

Generated by Repository Quality Improvement Agent
Next analysis: 2026-08-25 — Focus area selected by diversity algorithm

Generated by ⚡ Repository Quality Improvement Agent · copilot · auto · 32.3 AIC · ⌖ 6.38 AIC · ⊞ 9.9K · ◷

• expires on Aug 25, 2026, 5:15 AM UTC-08:00