From b65060439a89b0a5c61cb4b75c82d0376f4f77fc Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sun, 10 May 2026 21:03:33 +0000
Subject: [PATCH] [caveman] Trim verbose prose in serena-tool.md and
 runbooks/README.md

Why use many token when few do trick.

- serena-tool.md: 182 -> 156 lines. Merged two redundant import
  examples, removed restating-the-YAML "Pattern:" list, dropped the
  anecdotal "Production Examples" section (workflow names + success
  percentages with no schema signal).
- runbooks/README.md: 32 -> 19 lines. Collapsed generic "Purpose" and
  obvious "How to Use" sections that added no agent-actionable signal.

All YAML examples, schema field names, and decision tables preserved.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/aw/runbooks/README.md | 17 ++---------------
 .github/aw/serena-tool.md     | 32 +++-----------------------------
 2 files changed, 5 insertions(+), 44 deletions(-)

diff --git a/.github/aw/runbooks/README.md b/.github/aw/runbooks/README.md
index ee4b76fce45..dc597f00510 100644
--- a/.github/aw/runbooks/README.md
+++ b/.github/aw/runbooks/README.md
@@ -8,25 +8,12 @@ This directory contains operational runbooks for managing and troubleshooting Gi
 
 ## Purpose
 
-Runbooks provide step-by-step procedures for:
-- Diagnosing workflow issues
-- Resolving common failure patterns
-- Applying learnings from incident response
-- Maintaining workflow reliability
-
-## How to Use Runbooks
-
-1. Identify the type of issue you're experiencing
-2. Open the relevant runbook
-3. Follow the investigation steps
-4. Apply the resolution procedure
-5. Verify the fix
+Step-by-step procedures for diagnosing workflow issues, resolving failure patterns, applying incident-response learnings, and maintaining reliability.
 
 ## Contributing
 
 When creating new runbooks:
-- Focus on actionable procedures
-- Include real-world examples and case studies
+- Focus on actionable procedures with real-world examples
 - Document commands and configuration patterns
 - Reference related documentation
 - Follow the how-to guide format
diff --git a/.github/aw/serena-tool.md b/.github/aw/serena-tool.md
index c6a2587d613..a31322dac74 100644
--- a/.github/aw/serena-tool.md
+++ b/.github/aw/serena-tool.md
@@ -22,21 +22,13 @@ Serena is a **language service protocol (LSP) MCP server** for semantic code ana
 
 ## Configuration
 
-Import the shared Serena workflow via the `imports:` field — `tools.serena` has been removed:
+Import the shared Serena workflow via the `imports:` field — `tools.serena` has been removed. For multi-language, first entry is the default fallback:
 
 ```yaml
 imports:
   - uses: shared/mcp/serena.md
     with:
-      languages: ["go"]  # Specify language(s): go, typescript, python, ruby, rust, java, cpp, csharp
-```
-
-Multi-language repositories:
-```yaml
-imports:
-  - uses: shared/mcp/serena.md
-    with:
-      languages: ["go", "typescript"]  # First language is default fallback
+      languages: ["go", "typescript"]  # go, typescript, python, ruby, rust, java, cpp, csharp
 ```
 
 ## Available Serena Tools
@@ -79,7 +71,7 @@ imports:
 
 ### 2. Combine with Other Tools
 
-**Best practice**: Use bash for discovery, Serena for analysis
+Use `bash` for file discovery, Serena for semantic analysis, `edit` for changes.
 
 ```yaml
 imports:
@@ -94,15 +86,8 @@ tools:
     toolsets: [default]
 ```
 
-**Pattern**: 
-1. Use `bash` to list files
-2. Use Serena to analyze semantic structure
-3. Use `edit` to make changes
-
 ### 3. Use Cache for Recurring Analysis
 
-Track analysis state across runs:
-
 ```yaml
 imports:
   - uses: shared/mcp/serena.md
@@ -111,8 +96,6 @@ imports:
 cache-memory: true  # Store analysis history
 ```
 
-Load cache → Analyze new/changed files → Save results → Avoid redundant work
-
 ## Common Patterns
 
 ### Pattern 1: Find All Function Usages
@@ -142,15 +125,6 @@ Load cache → Analyze new/changed files → Save results → Avoid redundant wo
 5. Generate improvement tasks
 ```
 
-## Production Examples
-
-Workflows successfully using Serena:
-
-- **go-fan** (97.6% success) - Go module usage analysis with round-robin
-- **sergo** (94.4% success) - Daily code quality with 50/50 cached/new strategies
-- **semantic-function-refactor** - Function clustering and outlier detection
-- **daily-compiler-quality** - Rotating file analysis with cache tracking
-
 ## Common Pitfalls
 
 ❌ **Using Serena for non-code files** - Use `edit` for YAML/JSON/Markdown