[repository-quality] 🔍 Repository Quality Improvement Report — Documentation (2026-06-15)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Documentation

Analysis Date: 2026-06-15 Focus Area: Documentation Strategy Type: Standard Custom Area: No — random=88 (standard tier 60–89); Documentation never analyzed in 18 prior runs

Executive Summary

The repository has 413 Markdown docs pages with excellent frontmatter quality (100% have title+description). However, Go package documentation is sparse: 21/28 packages (75%) lack a doc.go, and three packages — pkg/agentdrain, pkg/github, pkg/gitutil — have zero package-level documentation. The WASM console API surface exposes 37 exported functions with no doc comments. Six non-blog docs pages are missing sidebar.order, causing unpredictable Starlight navigation.

The highest-ROI action is porting pkg/agentdrain/README.md (already rich content) into a doc.go — no new writing needed, just reformatting. The four tasks below target the most impactful gaps across Go godoc coverage and docs site navigation.

Full Analysis Report

Current State Assessment

Metrics Collected:

Metric	Value	Status
Packages with doc.go	7/28 (25%)	⚠️
Packages with zero pkg docs	3 (agentdrain, github, gitutil)	❌
Exported funcs without doc comment	74 total	⚠️
WASM console undocumented exports	37	❌
Docs pages with title+description	176/176	✅
Non-blog pages missing sidebar.order	6	⚠️
ADR coverage	243 docs	✅
Skill docs coverage	40 docs	✅

Findings

Strengths

• Every docs page has title: and description: — zero stub titles
• Rich ADR coverage (243 documents)
• 7 largest packages have detailed doc.go with usage examples
• Blog actively maintained (43 posts, latest 2026-06-15)

Areas for Improvement

• pkg/agentdrain (68 exports): has README.md but no doc.go — tooling cannot find it
• pkg/github (30 exports): no package comment anywhere
• pkg/gitutil (24 exports): no package comment anywhere
• pkg/console/*_wasm.go: 37 exported functions, zero doc comments
• 4 reference + 1 spec + 1 pattern page missing sidebar.order

Detailed Findings

agentdrain gap: pkg/agentdrain/README.md documents the Drain algorithm and anomaly detection purpose — but go doc .../pkg/agentdrain returns nothing because no Go file has a // Package agentdrain ... comment.

WASM console contract: pkg/console/console_wasm.go exposes 37 functions (FormatError, RenderTable, NewSpinner, etc.) with zero doc comments. These are the Go→Browser WASM API.

Navigation gap: Starlight assigns arbitrary order when sidebar.order is absent. Affected: reference/wasm-compilation.md, reference/feature-flags.md, reference/steps-jobs.md, reference/self-hosted-runners.md, specs/frontmatter-hash-specification.md, patterns/spec-ops.md.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Port pkg/agentdrain README into doc.go

Priority: High Estimated Effort: Small Focus Area: Documentation

Description: Create pkg/agentdrain/doc.go using pkg/agentdrain/README.md as source. The package has no // Package agentdrain ... comment so go doc returns nothing. Port the README content into a Go package comment covering: Drain algorithm origin, gh-aw anomaly-detection use-case, key types (Config, Coordinator, Miner, Anomaly). Model on pkg/workflow/doc.go.

Acceptance Criteria:

• pkg/agentdrain/doc.go created with // Package agentdrain ... comment
• Covers algorithm origin, use-case (AgentEvent anomaly detection), key types
• go doc github.com/github/gh-aw/pkg/agentdrain returns a meaningful description
• README.md updated or removed to avoid duplication
• make agent-report-progress passes

Code Region: pkg/agentdrain/doc.go (new), pkg/agentdrain/README.md

Create pkg/agentdrain/doc.go from pkg/agentdrain/README.md content.
Model structure on pkg/workflow/doc.go: purpose → usage sketch → key components → related packages.
Key facts: Drain algorithm ((jiemingzhu.github.io/redacted), anomaly detection on AgentEvent records, types: Config/Coordinator/Miner/Anomaly.
Update or remove README.md after doc.go is written.

---

Task 2: Add doc comments to pkg/console WASM exports

Priority: High Estimated Effort: Medium Focus Area: Documentation

Description: pkg/console/*_wasm.go has 37 exported functions with no doc comments. These are compiled to WebAssembly and form the browser playground public API. Add a // FuncName ... doc comment to each.

Files: console_wasm.go (20 funcs), input_wasm.go, select_wasm.go, form_wasm.go, layout_wasm.go, list_wasm.go, confirm_wasm.go, spinner_wasm.go, progress_wasm.go, banner_wasm.go.

Acceptance Criteria:

• All 37 exported functions in pkg/console/*_wasm.go have a // FuncName ... doc comment
• Comments follow Go doc convention (start with function name)
• No compilation errors
• make agent-report-progress passes

Code Region: pkg/console/console_wasm.go, pkg/console/input_wasm.go, pkg/console/select_wasm.go, pkg/console/form_wasm.go, pkg/console/layout_wasm.go, pkg/console/list_wasm.go, pkg/console/confirm_wasm.go, pkg/console/spinner_wasm.go, pkg/console/progress_wasm.go, pkg/console/banner_wasm.go

Add Go doc comments to all 37 exported functions in pkg/console/*_wasm.go (the WASM browser API).
For each: add `// FuncName does X.` before the func declaration.
Formatters: describe the formatting they apply (emoji prefix, styling).
Interactive prompts: describe UX behavior (what the user sees/does).

---

Task 3: Create doc.go for pkg/github and pkg/gitutil

Priority: Medium Estimated Effort: Small Focus Area: Documentation

Description: Both packages have zero package-level documentation. pkg/github contains label-to-objective mapping for repository health metrics. pkg/gitutil provides git utilities (branch detection, commits, remote URL parsing). Create doc.go for each following pkg/types/doc.go pattern.

Acceptance Criteria:

• pkg/github/doc.go created with // Package github ... covering label-objective mapping
• pkg/gitutil/doc.go created with // Package gitutil ... covering git utilities
• go doc returns meaningful descriptions for both
• make agent-report-progress passes

Code Region: pkg/github/doc.go (new), pkg/gitutil/doc.go (new)

Create doc.go for pkg/github (label-to-objective mapping, health scoring) and pkg/gitutil (git operations for CLI pipeline).
Model on pkg/types/doc.go (focused, 20-40 line comment).
Read the source files to understand what each package does before writing.

---

Task 4: Fix sidebar.order on 6 navigational docs pages

Priority: Medium Estimated Effort: Small Focus Area: Documentation

Description: Six non-blog docs pages lack sidebar.order, causing Starlight to render them in arbitrary order. Add sidebar: order: to each, choosing a value consistent with neighboring pages.

Affected files:

• docs/src/content/docs/reference/wasm-compilation.md
• docs/src/content/docs/reference/feature-flags.md
• docs/src/content/docs/reference/steps-jobs.md
• docs/src/content/docs/reference/self-hosted-runners.md
• docs/src/content/docs/specs/frontmatter-hash-specification.md
• docs/src/content/docs/patterns/spec-ops.md

Acceptance Criteria:

• All 6 files have sidebar: block with order: in frontmatter
• Values fit logically between neighboring pages in each section
• make agent-report-progress passes

Code Region: docs/src/content/docs/reference/wasm-compilation.md, docs/src/content/docs/reference/feature-flags.md, docs/src/content/docs/reference/steps-jobs.md, docs/src/content/docs/reference/self-hosted-runners.md, docs/src/content/docs/specs/frontmatter-hash-specification.md, docs/src/content/docs/patterns/spec-ops.md

Fix missing sidebar.order on 6 docs pages.
For each section find existing order values: grep -r "order:" docs/src/content/docs/<section>/ --include="*.md" | sort -t: -k3 -n
Add sidebar: order: <N> to frontmatter of each file using a value that fits logically between neighbors.

---

📊 Historical Context

Previous Focus Areas (last 8)

Date	Focus Area	Type
2026-06-12	Cobra Example Field Migration	Custom
2026-06-11	Benchmark Infrastructure Completeness	Custom
2026-06-10	Security	Standard
2026-06-09	Context Propagation (reuse)	Standard
2026-06-08	Compiler Error Hint Rendering Gap	Custom

---

🎯 Recommendations

Immediate Actions (This Week)

1. Port pkg/agentdrain/README.md → doc.go — Priority: High
2. Add doc comments to 37 WASM console exports — Priority: High

Short-term Actions (This Month)

1. Create doc.go for pkg/github and pkg/gitutil — Priority: Medium
2. Fix sidebar.order on 6 navigational docs pages — Priority: Medium

Long-term Actions (This Quarter)

1. Add doc.go to remaining 17 packages with inline-only package comments — Priority: Low
2. Enforce godoc coverage via CI linter — Priority: Low

---

📈 Success Metrics

• Packages with doc.go: 7/28 (25%) → 28/28 (100%)
• WASM exports documented: 0/37 → 37/37
• Non-blog pages missing sidebar.order: 6 → 0
• Packages with zero package docs: 3 → 0

---

Next Steps

1. Prioritise and assign the 4 tasks to Copilot coding agent
2. Re-evaluate Documentation in 90 days

---

References: §27554699119

Generated by Repository Quality Improvement Agent

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• proxy.golang.org

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "proxy.golang.org"

See Network Configuration for more information.

Generated by ⚡ Repository Quality Improvement Agent · 609.1 AIC · ⌖ 14.9 AIC · ⊞ 22K · ◷

• expires on Jun 16, 2026, 7:06 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Repository Quality Improvement Agent.

A newer discussion is available at Discussion #39571.