From d1b84d457388d096adf5f9e5d330e7abf82701b8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 21 May 2026 14:27:24 +0000 Subject: [PATCH] =?UTF-8?q?docs(scratchpad):=20v9.13=20maintenance=20tone?= =?UTF-8?q?=20scan=20=E2=80=94=208=20fixes=20across=206=20spec=20files?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace subjective intensifiers with concrete descriptions: - serena-tools-analysis.md: title "Deep Statistical Analysis"→"Statistical Analysis" (matches v9.7 "Complete deep dive"→"Complete statistical analysis"); "deep language service features"→"language service features". - mdflow.md: "Deep Technical Analysis"→"Technical Analysis" (status field and body sentence), matching the v5.7 "Deep Research Comparison"→ "Technical Comparison" pattern. - engine-architecture-review.md / engine-review-summary.md: "Deep review"→"Detailed review", matching v3.8 "Deep analysis"→ "Detailed analysis". - ubuntulatest.md: "due to the extensive software list"→"due to the size of the software list", matching v9.10 "Due to the extensive nature of..."→ "Given the number of...". - dev.md: bump to v9.13, add history entry; align Related Documentation description for serena-tools-analysis.md with the title fix. Coverage: 64 spec files (no new files). Co-Authored-By: Claude Opus 4.7 (1M context) --- scratchpad/dev.md | 7 ++++--- scratchpad/engine-architecture-review.md | 2 +- scratchpad/engine-review-summary.md | 2 +- scratchpad/mdflow.md | 4 ++-- scratchpad/serena-tools-analysis.md | 4 ++-- scratchpad/ubuntulatest.md | 2 +- 6 files changed, 11 insertions(+), 10 deletions(-) diff --git a/scratchpad/dev.md b/scratchpad/dev.md index 5ac1e27b826..05308eb4cdd 100644 --- a/scratchpad/dev.md +++ b/scratchpad/dev.md @@ -1,7 +1,7 @@ # Developer Instructions -**Version**: 9.12 -**Last Updated**: 2026-05-20 +**Version**: 9.13 +**Last Updated**: 2026-05-21 **Purpose**: Consolidated development guidelines for GitHub Agentic Workflows This document consolidates specifications from the scratchpad directory into unified developer instructions. It provides architecture patterns, security guidelines, code organization rules, and testing practices. @@ -2959,7 +2959,7 @@ These files are loaded automatically by compatible AI tools (e.g., GitHub Copilo - [oh-my-opencode Comparison](./oh-my-code.md) - Technical comparison of oh-my-opencode and gh-aw: architecture, use cases, tool ecosystems, security models, and implementation patterns - [Agent Sessions Terminology Migration](./agent-sessions.md) - Migration plan for renaming "agent task" to "agent session": schema updates, codemod in `fix_codemods.go`, Go/JavaScript code changes, documentation updates, and backward compatibility strategy - [Safe Output Handler Factory Pattern](./safe-output-handlers-refactoring.md) - Refactoring status for all 11 safe output handlers to the handler factory pattern (`main(config)` returns a message handler function): per-handler status, testing strategy, and handler manager compatibility -- [Serena Tools Statistical Analysis](./serena-tools-analysis.md) - Deep statistical analysis of Serena MCP tool usage in workflow run 21560089409: tool adoption rates (26% of registered tools used), call distributions, and unused tool identification +- [Serena Tools Statistical Analysis](./serena-tools-analysis.md) - Statistical analysis of Serena MCP tool usage in workflow run 21560089409: tool adoption rates (26% of registered tools used), call distributions, and unused tool identification - [GitHub API Rate Limit Observability](./github-rate-limit-observability.md) - JSONL artifact logging and OTLP span enrichment for GitHub API rate-limit visibility: `github_rate_limit_logger.cjs` helper, three usage patterns, artifact upload paths, and `jq` debugging commands - [WorkQueueOps Design Pattern](../docs/src/content/docs/patterns/workqueue-ops.md) - Four queue strategies (issue checklist, sub-issues, cache-memory, discussion-based) for incremental backlog processing: idempotency requirements, concurrency control, and retry budgets - [BatchOps Design Pattern](../docs/src/content/docs/patterns/batch-ops.md) - Four batch strategies (chunked, matrix fan-out, rate-limit-aware, result aggregation) for high-volume parallel processing: shard assignment, partial failure handling, and real-world label migration example @@ -2974,6 +2974,7 @@ These files are loaded automatically by compatible AI tools (e.g., GitHub Copilo --- **Document History**: +- v9.13 (2026-05-21): Maintenance tone scan — fixed 8 tone issues across 6 spec files: `serena-tools-analysis.md` (2 fixes: "# Serena Tools Usage - Deep Statistical Analysis"→"# Serena Tools Usage - Statistical Analysis" line 1 — "Deep" is redundant when "Statistical Analysis" follows, matches v9.7 "Complete deep dive"→"Complete statistical analysis" pattern; "rather than deep language service features"→"rather than language service features" line 181 — removed subjective intensifier, matches v9.7 "deep exploration"→"multi-step exploration" pattern); `mdflow.md` (2 fixes: "**Status**: Deep Technical Analysis"→"**Status**: Technical Analysis" line 5; "This document provides a deep technical analysis"→"This document provides a technical analysis" line 11 — "deep" is subjective, matches v5.7 "Deep Research Comparison"→"Technical Comparison" pattern); `engine-architecture-review.md` (1 fix: "**Scope**: Deep review of agentic engine interface and implementations"→"**Scope**: Detailed review of agentic engine interface and implementations" line 5 — matches v3.8 "Deep analysis"→"Detailed analysis" pattern); `engine-review-summary.md` (1 fix: "Completed deep review of the agentic engine architecture"→"Completed a detailed review of the agentic engine architecture" line 5 — same v3.8 pattern); `ubuntulatest.md` (1 fix: "due to the extensive software list"→"due to the size of the software list" line 350 — replaced subjective "extensive" with concrete "size", matches v9.10 "Due to the extensive nature of..."→"Given the number of..." pattern). Also updated dev.md Related Documentation description for `serena-tools-analysis.md`: "Deep statistical analysis of Serena MCP"→"Statistical analysis of Serena MCP" line 2962 (consistency with the title fix). Coverage: 64 spec files (no new files). - v9.12 (2026-05-20): Maintenance tone scan — fixed 7 tone issues across 4 spec files: `mods/jsonschema-go.md` (2 fixes: "**Enhanced Type Mapping:** Improved handling of pointer types for nullable fields"→"**Type Mapping:** Improved handling of pointer types for nullable fields" line 119 — "Enhanced" is redundant when the same bullet already says "Improved"; "Enhanced default value support"→"Expanded default value support" line 129 — "Enhanced" is comparative with no baseline, "Expanded" describes the concrete change); `oh-my-code.md` (1 fix: "Provide extensive agent capabilities"→"Provide a broad set of agent capabilities" line 23 — "extensive" is subjective; matches the v6.1 "Comprehensive"→removed pattern); `mcp_logs_guardrails.md` (1 fix: "Runs contain extensive tool usage data"→"Runs contain large volumes of tool usage data" line 9 — replaced subjective "extensive" with concrete "large volumes of"); `github-mcp-access-control-specification.md` (3 fixes: "Only read operations allowed (enhanced security)"→"Only read operations allowed (write operations rejected)" line 407 and "Only triggering repository accessible (enhanced security)"→"Only triggering repository accessible (cross-repo access rejected)" line 508 — "enhanced security" is vague; replaced with the specific behavioral guarantee; "fine-grained permissions, enhanced security posture"→"fine-grained permissions and short-lived tokens" line 2341 — replaced vague "enhanced security posture" with one of the specific properties already listed in the surrounding bullets). Coverage: 64 spec files (no new files). - v9.11 (2026-05-19): Maintenance tone scan — fixed 3 tone issues across 3 spec files: `labels.md` (1 fix: "Nice-to-have improvements"→"Lower-priority improvements" line 27; matches the v8.0 "nice to have"→"non-blocking" pattern applied to `agents/hierarchical-agents-quickstart.md`); `serena-tools-analysis.md` (1 fix: "## Serena Tool Usage Deep Dive"→"## Serena Tool Usage Analysis" line 47; matches the v3.8 "Deep analysis"→"Detailed analysis" pattern and v9.7 "deep dive"→"statistical analysis" replacement applied to `serena-tools-quick-reference.md`); `ubuntulatest.md` (1 fix: "cannot be perfectly replicated"→"cannot be fully replicated" line 656; removed redundant intensifier — "perfectly" adds no information when contrasting partial vs. complete replication). Coverage: 64 spec files (no new files). - v9.10 (2026-05-18): Maintenance tone scan — fixed 4 tone issues across 4 spec files: `testing.md` (1 fix: "extensive testing practices (699 test files, 1,061+ table-driven tests)"→"uses 699 test files and 1,061+ table-driven tests" line 7; "extensive" is subjective when the concrete count is already provided); `html-entity-mention-bypass-fix.md` (1 fix: "Extensive test suite validates all attack vectors"→"Test suite validates all attack vectors" line 137; matches the v6.1 "Comprehensive"→removed pattern); `safe-outputs-specification.md` (1 fix: "Due to the extensive nature of GitHub operations (20+ operation types)"→"Given the number of GitHub operations (20+ operation types)" line 810); `serena-tools-analysis.md` (1 fix: "Serena tools are highly **bandwidth-efficient**"→"Serena tools are **bandwidth-efficient**" line 170; redundant intensifier — preceding line already states "minimal bandwidth"). Coverage: 64 spec files (no new files). diff --git a/scratchpad/engine-architecture-review.md b/scratchpad/engine-architecture-review.md index 7e0537962c0..7a8dd0a9887 100644 --- a/scratchpad/engine-architecture-review.md +++ b/scratchpad/engine-architecture-review.md @@ -2,7 +2,7 @@ **Date**: 2026-02-17 **Reviewer**: AI Agent -**Scope**: Deep review of agentic engine interface and implementations +**Scope**: Detailed review of agentic engine interface and implementations ## Executive Summary diff --git a/scratchpad/engine-review-summary.md b/scratchpad/engine-review-summary.md index 10b1a6c166d..f99347f81eb 100644 --- a/scratchpad/engine-review-summary.md +++ b/scratchpad/engine-review-summary.md @@ -2,7 +2,7 @@ ## Overview -Completed deep review of the agentic engine architecture, interface design, and all implementations (Copilot, Claude, Codex, Custom). The architecture is structured for extension and follows established ISP patterns. +Completed a detailed review of the agentic engine architecture, interface design, and all implementations (Copilot, Claude, Codex, Custom). The architecture is structured for extension and follows established ISP patterns. ## What Was Reviewed diff --git a/scratchpad/mdflow.md b/scratchpad/mdflow.md index 699df681eff..a93d9c8efb9 100644 --- a/scratchpad/mdflow.md +++ b/scratchpad/mdflow.md @@ -2,13 +2,13 @@ **Date**: 2026-01-04 **Repository**: https://github.com/johnlindquist/mdflow -**Status**: Deep Technical Analysis +**Status**: Technical Analysis --- ## Executive Summary -This document provides a deep technical analysis of mdflow and GitHub Agentic Workflows (gh-aw), focusing on custom engine opportunities, architectural patterns, and strategic insights for gh-aw development. While the existing `mdflow-comparison.md` provides a detailed syntax comparison, this document focuses on **what gh-aw can learn from mdflow** and **opportunities for custom engine development**. +This document provides a technical analysis of mdflow and GitHub Agentic Workflows (gh-aw), focusing on custom engine opportunities, architectural patterns, and strategic insights for gh-aw development. While the existing `mdflow-comparison.md` provides a detailed syntax comparison, this document focuses on **what gh-aw can learn from mdflow** and **opportunities for custom engine development**. ### Key Findings diff --git a/scratchpad/serena-tools-analysis.md b/scratchpad/serena-tools-analysis.md index da8d10d72f4..97baa6ec07c 100644 --- a/scratchpad/serena-tools-analysis.md +++ b/scratchpad/serena-tools-analysis.md @@ -1,4 +1,4 @@ -# Serena Tools Usage - Deep Statistical Analysis +# Serena Tools Usage - Statistical Analysis **Workflow Run:** [21560089409](https://github.com/github/gh-aw/actions/runs/21560089409/job/62122702303#step:33:1) **Workflow:** Sergo - Serena Go Expert @@ -178,7 +178,7 @@ Only **26.09%** of registered Serena tools were actually used during execution. 1. **Over-provisioning:** Many specialized tools are available but not needed for typical workflows 2. **Selective Usage:** Agent prefers general-purpose builtin tools (Bash, Read, Write) over specialized Serena tools -3. **Workflow Patterns:** Current workflow primarily uses file operations rather than deep language service features +3. **Workflow Patterns:** Current workflow primarily uses file operations rather than language service features ### Builtin vs Serena Tool Ratio diff --git a/scratchpad/ubuntulatest.md b/scratchpad/ubuntulatest.md index a1fe7c72e80..c0baee105bc 100644 --- a/scratchpad/ubuntulatest.md +++ b/scratchpad/ubuntulatest.md @@ -347,7 +347,7 @@ DEBIAN_FRONTEND=noninteractive ## Creating a Docker Image Mimic -To create a Docker image that mimics the GitHub Actions Ubuntu runner environment, follow these guidelines. Note that creating a complete replica is not practical due to the extensive software list, so focus on the tools your workflows actually need. +To create a Docker image that mimics the GitHub Actions Ubuntu runner environment, follow these guidelines. Note that creating a complete replica is not practical due to the size of the software list, so focus on the tools your workflows actually need. ### Base Image