[repository-quality] 🎯 Repository Quality Improvement Report - Code Organization (2026-08-12)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Code Organization

Analysis Date: 2026-08-12
Focus Area: Code Organization
Strategy Type: Standard
Custom Area: No

Executive Summary

This is the first recorded run of the Repository Quality Improvement Agent for github/gh-aw, so the focus-area selection defaults to a standard category with no reuse history to draw on. Analysis of the Go codebase (1,218 non-test source files, ~272,944 source LOC vs. 531,699 test LOC) shows a healthy overall test-to-source ratio (~1.95:1), but a notable cluster of 35 files exceeding the repository's own documented 500-line guideline for source files, several surpassing 1,000 lines. This concentrates logic in a handful of "god files" in pkg/cli/ and pkg/workflow/, increasing merge-conflict risk, cognitive load for reviewers, and coupling between unrelated responsibilities.

The largest offenders — pkg/cli/update_actions.go (1,144 lines, 18 functions), pkg/workflow/compiler_custom_jobs.go (1,142 lines, 37 functions), and pkg/cli/audit.go (1,095 lines, 28+ functions) — each mix multiple distinct concerns (e.g., action-release resolution, skill-ref updates, and workflow-file rewriting all live in update_actions.go). The developer-code-organization skill already documents a "Prefer Many Small Files Over Large Ones" principle with a 100–500 line target and a "Create Functions Pattern" precedent (one file per operation), giving a clear template to apply here.

Recommended next steps: split the three largest files along their existing functional seams (which are already well-delineated by function naming, e.g. extractCustomJob* vs. applyBuiltinJob* vs. insert*Steps*), verify no regressions via targeted unit tests, and consider adding a lightweight CI line-count lint to prevent future regrowth.

Full Analysis Report

Focus Area: Code Organization

Current State Assessment

The codebase is large and mature (1,218 non-test .go files across pkg/ and cmd/), with strong test coverage by volume. However, file-size discipline has drifted for a subset of files, most concentrated in pkg/cli (CLI command implementations) and pkg/workflow (compiler internals).

Metrics Collected:

Metric	Value	Status
Non-test Go source files	1,218	✅
Source LOC	272,944	✅
Test LOC	531,699	✅
Test:Source LOC ratio	~1.95:1	✅
Files > 800 lines	35	⚠️
Largest file (update_actions.go)	1,144 lines	❌
2nd largest (compiler_custom_jobs.go)	1,142 lines	❌
3rd largest (audit.go)	1,095 lines	❌
TODO/FIXME markers	41	✅
README.md size	428 lines	✅

Findings

Strengths

• Test coverage volume comfortably exceeds source volume (~2x), suggesting active test discipline.
• Existing developer-code-organization skill already documents clear file-size guidance (100–500 lines) and naming/functional-grouping patterns (create_issue.go, engine_helpers.go, etc.) that can be directly reused as a refactor template.
• Function names inside oversized files are already well-segmented by responsibility (e.g. extractCustomJob*, applyBuiltinJob*, getLatestActionRelease*, updateSkillRefs*), meaning splitting is mostly mechanical rather than requiring new abstractions.
• TODO/FIXME count (41) is low relative to codebase size, indicating limited unresolved technical debt markers.

Areas for Improvement

• ⚠️ 35 files exceed 800 lines, well past the documented 500-line target, concentrated in pkg/cli (23 files) and pkg/workflow (12 files).
• ❌ pkg/cli/update_actions.go (1,144 lines) mixes at least three concerns: GitHub Action version resolution/caching, cooldown logic, and skill-ref/workflow-file content rewriting — each independently testable and separable.
• ❌ pkg/workflow/compiler_custom_jobs.go (1,142 lines, 37 functions) combines custom-job property extraction, built-in job augmentation, and step-insertion utilities — three cohesive sub-domains that map cleanly to 3 separate files.
• ❌ pkg/cli/audit.go (1,095 lines) interleaves command registration/flag parsing, single-run auditing, multi-run auditing, and analysis-result collection/launching (via errgroup).
• ⚠️ No automated guardrail (lint rule or CI check) currently enforces the file-size guideline, allowing files to regrow past 500 lines undetected.

Detailed Analysis

pkg/cli/update_actions.go — Natural split points based on function grouping:

• update_actions_core.go: UpdateActions, updateActions, actionUpdateDeps helpers (lines 61–403)
• update_actions_release.go: getLatestActionRelease*, parseActionTagRefs, findCooledDownActionVersion, getActionSHAForTag (lines 403–803)
• update_actions_content.go: UpdateActionsInWorkflowFiles, updateSkillRefsInContent*, updateActionRefsInContentWithDeps (lines 804–end)

pkg/workflow/compiler_custom_jobs.go — Split by domain:

• compiler_custom_jobs_extract.go: all extractCustomJob* functions (property/runs-on/timeout/concurrency/env/container/services/outputs extraction, lines 173–433)
• compiler_custom_jobs_builtin.go: applyBuiltinJob*, extractBuiltinJob*, normalizeBuiltinJobAlias, validateRestrictedBuiltin* (lines 598–984)
• compiler_custom_jobs_steps.go: insertActivationStepsBeforeArtifactStaging, insertSetupStepsAtStart, insertPreStepsAtEarliestBoundary, extractPinnedJobSteps, checkout helpers (lines 670–end)

pkg/cli/audit.go — Split by lifecycle stage:

• audit_command.go: NewAuditCommand, flag registration, option resolution, arg resolution (lines 94–251)
• audit_run_single.go / audit_run_multi.go: single vs. multi-run orchestration (lines 208–373)
• audit_pipeline.go: AuditWorkflowRun and the analysis-collection/launch pipeline (collectAuditAnalysisResults, launchCoreAuditAnalyses, launchMetricsAnalysis, lines 373–end)

These splits preserve existing exported symbols (no API changes), keep package-level visibility intact, and align with the "Group by Functionality, Not by Type" principle already documented in the developer-code-organization skill.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Split pkg/cli/update_actions.go into focused files

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

Description: pkg/cli/update_actions.go is 1,144 lines and mixes action-release resolution, cooldown logic, and workflow/skill-ref content rewriting. Split into update_actions_core.go, update_actions_release.go, and update_actions_content.go following the existing function boundaries, with no change to exported behavior.

Acceptance Criteria:

• File split into at least 3 files, each under ~500 lines, grouped by functional responsibility (core orchestration, release resolution, content rewriting)
• All existing exported functions/types keep their signatures and package (cli)
• go build ./... and go test ./pkg/cli/... pass with no behavior changes
• Corresponding update_actions_test.go tests (if split) remain green

Code Region: pkg/cli/update_actions.go

Split pkg/cli/update_actions.go (1144 lines) into three files without changing any exported behavior:
1. update_actions_core.go: UpdateActions, updateActions, isCoreAction, isGhAwNativeAction, newCachedActionUpdateDeps, defaultActionUpdateDeps
2. update_actions_release.go: getLatestActionRelease, getLatestActionReleaseWithDeps, getLatestActionReleaseViaGit, parseActionTagRefs, findCooledDownActionVersion, getActionSHAForTag
3. update_actions_content.go: UpdateActionsInWorkflowFiles, updateActionsInWorkflowFiles, updateSkillRefsInContent, updateSkillRefsInContentWithResolver, updateSkillRefValue, updateActionRefsInContentWithDeps
Keep all functions in package `cli`, preserve doc comments, run `make fmt` and `go test ./pkg/cli/...` after the split to confirm no regressions.

---

Task 2: Split pkg/workflow/compiler_custom_jobs.go by sub-domain

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

Description: pkg/workflow/compiler_custom_jobs.go is 1,142 lines with 37 functions spanning custom-job property extraction, built-in job augmentation, and step-insertion utilities. Split into three files aligned with these sub-domains.

Acceptance Criteria:

• Extraction logic (extractCustomJob*) moved to compiler_custom_jobs_extract.go
• Built-in job augmentation logic (applyBuiltinJob*, extractBuiltinJob*, validateRestrictedBuiltin*) moved to compiler_custom_jobs_builtin.go
• Step-insertion/checkout helpers (insert*Steps*, extractPinnedJobSteps, checkout helpers) moved to compiler_custom_jobs_steps.go
• go build ./... and go test ./pkg/workflow/... pass unchanged

Code Region: pkg/workflow/compiler_custom_jobs.go

Split pkg/workflow/compiler_custom_jobs.go (1142 lines) into three files in package `workflow`, preserving all method receivers (*Compiler) and function signatures:
1. compiler_custom_jobs_extract.go: extractCustomJobNeeds, extractCustomJobProperties, extractCustomJobCoreProperties, extractCustomJobRunsOn, extractCustomJobTimeoutMinutes, extractCustomJobConcurrency, extractCustomJobEnv, extractCustomJobContainer, extractCustomJobServices, extractCustomJobContinueOnError, extractCustomJobEnvironment, extractCustomJobOutputs
2. compiler_custom_jobs_builtin.go: applyBuiltinJobPreSteps, normalizeBuiltinJobAlias, extractBuiltinJobNeedsAugmentation, extractBuiltinJobIfAugmentation, applyBuiltinJobAugmentations, applyBuiltinJobPermissionsAugmentation, guardIfAgainstStatusFuncBypass, ifExpressionContainsStatusFunc, validateRestrictedBuiltinSetupSteps, validateRestrictedBuiltinSteps
3. compiler_custom_jobs_steps.go: insertActivationStepsBeforeArtifactStaging, insertSetupStepsAtStart, insertPreStepsAtEarliestBoundary, extractPinnedJobSteps, ensureCheckoutPersistCredentials, isCheckoutAction
Keep buildCustomJobs, getCustomJobDependencySets, shouldSkipCustomJob, buildCustomJob, applyAutomaticActivationDependency, configureCustomJobExecution, configureCustomReusableWorkflow, configureCustomJobSteps, formatIndentedYAMLField in the original compiler_custom_jobs.go as the orchestration entry points. Run `make fmt` and `go test ./pkg/workflow/...` after splitting.

---

Task 3: Split pkg/cli/audit.go by lifecycle stage

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

Description: pkg/cli/audit.go (1,095 lines) interleaves command/flag setup, single-run auditing, multi-run auditing, and analysis-collection pipeline logic. Split along these existing boundaries to improve readability and reduce merge conflicts in this frequently-touched file.

Acceptance Criteria:

• Command/flag setup (NewAuditCommand, registerAuditCommandFlags, runAuditCommand, getAuditCommandOptions, resolveAuditCommandArgs) moved to audit_command.go
• Single/multi run orchestration (runAuditSingle, runAuditMulti, applyAuditRepoFlag, permission-error helpers) moved to audit_run.go
• Analysis pipeline (AuditWorkflowRun, collectAuditAnalysisResults, launchCoreAuditAnalyses, launchMetricsAnalysis, and related helper functions) moved to audit_pipeline.go
• go build ./... and go test ./pkg/cli/... pass unchanged

Code Region: pkg/cli/audit.go

Split pkg/cli/audit.go (1095 lines) into three files in package `cli`, preserving all exported symbols and behavior:
1. audit_command.go: NewAuditCommand, registerAuditCommandFlags, runAuditCommand, getAuditCommandOptions, resolveAuditCommandArgs
2. audit_run.go: runAuditSingle, runAuditMulti, applyAuditRepoFlag, isPermissionErrorStr, isPermissionError
3. audit_pipeline.go: AuditWorkflowRun, newAuditRunConfig, resolveAuditHostname, resolveAuditOutputDir, ensureAuditNotCancelled, announceAuditRun, auditRunConfig methods, renderCachedAuditIfAvailable, processedRunFromSummary, shouldSkipAuditRun, prepareAuditWorkflowRun, fetchAuditRunWithCache, downloadAuditArtifactsIfNeeded, downloadLegacyEvalsArtifactIfNeeded, cacheRecoveryError, prepareRunForAnalysis, collectAuditAnalysisResults, launchCoreAuditAnalyses, launchMetricsAnalysis
Run `make fmt` and `go test ./pkg/cli/... -run Audit` after splitting to confirm behavior parity.

---

Task 4: Add a CI guardrail for source file size

Priority: Low
Estimated Effort: Small
Focus Area: Code Organization

Description: There is currently no automated check preventing Go source files from growing past the documented 500-line guideline. Add a lightweight, non-blocking (warn-only initially) check — either a Go linter rule (see .github/skills/go-linters/SKILL.md for the custom-linter pattern) or a simple make lint shell check — that flags non-test .go files exceeding a threshold (e.g., 800 lines) so growth is caught in review rather than accumulating silently.

Acceptance Criteria:

• A check (custom linter or Makefile target) reports any non-test .go file over the chosen line threshold
• Check runs as part of an existing make lint or CI step without failing the build (warn-only for the initial rollout)
• Threshold and rationale documented in .github/skills/developer-code-organization/SKILL.md
• Existing 35 over-threshold files documented as a known baseline/allowlist to avoid immediately breaking CI

Code Region: pkg/linters/, Makefile

Add a lightweight source-file-size guardrail for the gh-aw Go codebase:
1. Prefer extending the existing pkg/linters custom analyzer framework (see .github/skills/go-linters/SKILL.md and pkg/linters/ for the established pattern) with a new analyzer that warns (does not fail) when a non-test .go file under pkg/ or cmd/ exceeds 800 lines.
2. Alternatively, if a full linter is too heavy, add a `make check-file-size` Makefile target running a simple find/wc script with the same warn-only threshold, and wire it into the existing lint pipeline as advisory output only.
3. Record the current 35 files exceeding 800 lines as a known baseline (e.g., an allowlist file or comment) so this task does not fail existing CI runs.
4. Document the guideline and threshold rationale in .github/skills/developer-code-organization/SKILL.md under "File Size Guidelines".
Do not make the check fail the build in this task — advisory/warn-only output only.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-08-12	Code Organization	Standard	N	First run — identified 35 oversized files; 4 tasks generated

---

🎯 Recommendations

Immediate Actions (This Week)

1. Split pkg/cli/update_actions.go into 3 focused files — Priority: Medium
2. Split pkg/workflow/compiler_custom_jobs.go into 3 focused files — Priority: Medium

Short-term Actions (This Month)

1. Split pkg/cli/audit.go into 3 focused files — Priority: Low
2. Add an advisory CI guardrail for file-size growth — Priority: Low

Long-term Actions (This Quarter)

1. Progressively work through the remaining 32 files over 800 lines using the same functional-grouping methodology — Priority: Low

---

📈 Success Metrics

• Files > 800 lines: 35 → < 20 (after top-3 splits + guardrail)
• Largest file size: 1,144 lines → < 600 lines

---

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 quarter

---

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

Generated by ⚡ Repository Quality Improvement Agent · auto · 28.9 AIC · ⌖ 2.95 AIC · ⊞ 9.4K · ◷

• expires on Aug 13, 2026, 5:19 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-08-13T13:19:46.322Z.

Closed by Workflow