From 2d614e9dfaeeee68f0216e66e03642eff2902434 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 1 Feb 2026 11:46:02 +0000
Subject: [PATCH 1/4] Initial plan


From 7cb698914d56625f5759d4e8a4308cf753306bf5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 1 Feb 2026 11:53:16 +0000
Subject: [PATCH 2/4] Update serena-tool.md with comprehensive usage guidance

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/serena-tool.md | 392 ++++++++++++++++++++++++++++++++------
 1 file changed, 336 insertions(+), 56 deletions(-)

diff --git a/.github/aw/serena-tool.md b/.github/aw/serena-tool.md
index b95c22085b..ed907fdd97 100644
--- a/.github/aw/serena-tool.md
+++ b/.github/aw/serena-tool.md
@@ -1,86 +1,366 @@
 # Serena Language Server Tool
 
-Serena is an **advanced static analysis tool** that provides deep code understanding through language server capabilities. It is designed for **advanced coding tasks** that require sophisticated code analysis.
+Serena is a **language service protocol (LSP) MCP server** that provides advanced code intelligence through semantic analysis, symbol navigation, and code understanding. It's designed for **deep code analysis tasks** that require understanding code structure, relationships, and semantics beyond simple text manipulation.
 
 ## When to Use Serena
 
-⚠️ **Important**: Serena should only be suggested when the user **explicitly requests advanced static analysis** for specific programming languages.
+Serena is powerful for **semantic code analysis** but comes with setup overhead. Use it when tasks genuinely require language-aware understanding:
 
-**Appropriate use cases:**
-- Deep code refactoring requiring semantic understanding
-- Complex code transformations across multiple files
-- Advanced type checking and inference
-- Cross-file dependency analysis
-- Language-specific semantic analysis
+### ✅ Excellent Use Cases
 
-**NOT recommended for:**
-- Simple file editing or text manipulation
-- Basic code generation
-- General workflow automation
-- Tasks that don't require deep code understanding
+**Symbol and dependency analysis:**
+- Finding all usages of a function/type across files
+- Analyzing call graphs and dependency relationships
+- Identifying duplicate or similar code patterns semantically
+- Discovering outlier functions in wrong files
+
+**Code quality and refactoring:**
+- Detecting code that should be extracted or consolidated
+- Analyzing function organization and clustering
+- Identifying refactoring opportunities based on code structure
+- Validating type usage and interface implementations
+
+**Deep code understanding:**
+- Understanding complex codebases quickly
+- Analyzing module usage patterns
+- Identifying architectural improvements
+- Cross-file semantic analysis
+
+### ❌ Poor Use Cases (Use simpler tools instead)
+
+**Simple text operations:**
+- Basic file editing or text manipulation → Use `edit` tool
+- Search/replace by pattern → Use `grep` or `bash`
+- File creation/deletion → Use `create` or `bash`
+
+**When grep/bash suffice:**
+- Finding text patterns → Use `grep`
+- Listing files → Use `find` or `glob`
+- Line counting → Use `wc`
+- Simple code searches → Use `grep` with regex
+
+**Configuration or data files:**
+- YAML/JSON/config file edits → Use `edit` tool
+- Markdown documentation → Use `edit` tool
+- Non-code analysis → Serena won't help
 
 ## Configuration
 
-When a user explicitly asks for advanced static analysis capabilities:
+Enable Serena by specifying target language(s) in workflow frontmatter:
+
+```yaml
+tools:
+  serena: ["<language>"]  # One or more languages
+```
+
+### Supported Languages
+
+Primary supported languages (with full LSP features):
+- `go` - Go language (gopls)
+- `typescript` - TypeScript/JavaScript
+- `python` - Python (jedi or pyright)
+- `ruby` - Ruby (solargraph)
+- `rust` - Rust (rust-analyzer)
+- `java` - Java
+- `cpp` - C/C++
+- `csharp` - C#
+
+See `.serena/project.yml` for the complete list (25+ languages).
+
+### Multi-language Support
+
+For repositories with multiple languages:
+
+```yaml
+tools:
+  serena: ["go", "typescript"]  # Multiple languages
+```
+
+The first language is the default fallback.
+
+## Detecting Repository Language
+
+**Method 1: Check language-specific files**
+```bash
+# Go
+[ -f go.mod ] && echo "go"
+
+# TypeScript/JavaScript  
+[ -f package.json ] && echo "typescript"
+
+# Python
+[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "python"
+
+# Rust
+[ -f Cargo.toml ] && echo "rust"
+
+# Java
+[ -f pom.xml ] || [ -f build.gradle ] && echo "java"
+```
+
+**Method 2: Examine file extensions**
+```bash
+find . -type f -name "*.go" | head -1  # Go files
+find . -type f -name "*.ts" | head -1  # TypeScript
+find . -type f -name "*.py" | head -1  # Python
+```
+
+## Available Serena Tools
+
+Once Serena is enabled, you have access to powerful MCP tools:
+
+### Core Navigation Tools
+
+- `read_file` - Read file contents with semantic understanding
+- `list_dir` - List directory contents
+- `get_symbols_overview` - Get all symbols (functions, types) in a file
+- `find_symbol` - Search for symbols by name (global or local)
+- `find_referencing_symbols` - Find where a symbol is used
+- `find_referencing_code_snippets` - Find code snippets referencing a symbol
+
+### Code Editing Tools
+
+- `create_text_file` - Create or overwrite files
+- `insert_at_line` - Insert content at specific line
+- `insert_before_symbol` / `insert_after_symbol` - Insert near symbols
+- `replace_lines` - Replace line range with new content
+- `replace_symbol_body` - Replace entire symbol definition
+- `delete_lines` - Delete line range
+
+### Analysis Tools
+
+- `search_for_pattern` - Search for code patterns
+- `onboarding` - Analyze project structure and essential tasks
+- `activate_project` - Activate Serena for a workspace
+- `restart_language_server` - Restart LSP if needed
+
+### Memory and State
+
+- `write_memory` / `read_memory` / `list_memories` - Store project insights
+- `get_current_config` - View Serena configuration
+
+## Practical Usage Patterns
+
+### Pattern 1: Find All Usages of a Function
+
+**Workflow**: Analyzing how a function is used across the codebase
 
 ```yaml
 tools:
-  serena: ["<language>"]  # Specify the programming language(s)
+  serena: ["go"]
 ```
 
-**Supported languages:**
-- `go`
-- `typescript`
-- `python`
-- `ruby`
-- `rust`
-- `java`
-- `cpp`
-- `csharp`
-- And many more (see `.serena/project.yml` for full list)
-
-## Detection and Usage
-
-**To detect the repository's primary language:**
-1. Check file extensions in the repository
-2. Look for language-specific files:
-   - `go.mod` → Go
-   - `package.json` → TypeScript/JavaScript
-   - `requirements.txt` or `pyproject.toml` → Python
-   - `Cargo.toml` → Rust
-   - `pom.xml` or `build.gradle` → Java
-   - etc.
-
-## Example Configuration
+**Agent tasks:**
+1. Use `find_symbol` to locate the function definition
+2. Use `find_referencing_code_snippets` to find all call sites
+3. Analyze patterns and suggest improvements
+
+**Example**: See `go-fan.md` workflow (analyzes Go module usage)
+
+### Pattern 2: Code Quality Analysis
+
+**Workflow**: Identify refactoring opportunities by clustering functions
 
 ```yaml
 tools:
-  serena: ["go"]  # For Go repositories requiring advanced static analysis
+  serena: ["go"]
 ```
 
-## User Interaction Pattern
+**Agent tasks:**
+1. Use `get_symbols_overview` on multiple files
+2. Use `find_symbol` to locate similar function names
+3. Use `search_for_pattern` to find duplicate patterns
+4. Identify outliers and suggest consolidation
+
+**Example**: See `semantic-function-refactor.md` workflow (clusters functions semantically)
+
+### Pattern 3: Daily Code Deep Dives
+
+**Workflow**: Systematically analyze codebase over time
+
+```yaml
+tools:
+  serena: ["go"]
+  cache-memory: true  # Track analysis history
+```
 
-When a user describes a task:
+**Agent tasks:**
+1. Load previous analysis state from cache
+2. Select rotation strategy (round-robin, prioritize recent updates)
+3. Use Serena for deep semantic analysis
+4. Save findings to cache for next run
+5. Generate actionable improvement tasks
 
-1. **Analyze the request**: Does it require advanced static analysis?
-2. **If NO**: Use standard tools (bash, edit, etc.)
-3. **If YES**: Ask the user if they want to use Serena for advanced static analysis
-4. **Only add Serena** if the user explicitly confirms
+**Examples**: 
+- `sergo.md` - Daily Go analysis with 50/50 cached/new strategies
+- `go-fan.md` - Daily Go module reviewer with round-robin
 
-**Example conversation:**
+### Pattern 4: Compiler/Large File Analysis
 
-User: "I need to refactor the authentication logic across multiple files with proper type safety"
+**Workflow**: Analyze large complex files for quality
 
-Agent: "This task involves complex cross-file refactoring. Would you like me to use the Serena language server for advanced static analysis? This will provide deeper code understanding but adds complexity to the workflow."
+```yaml
+tools:
+  serena: ["go"]
+  cache-memory: true
+  bash:
+    - "find pkg/workflow -name 'compiler*.go' ! -name '*_test.go'"
+    - "wc -l pkg/workflow/compiler*.go"
+```
 
-User: "Yes, use Serena"
+**Agent tasks:**
+1. Use bash to identify target files
+2. Track file hashes to detect changes
+3. Use Serena for semantic analysis only on changed files
+4. Focus on human-written quality standards
 
-Agent: *Adds `serena: ["go"]` to the workflow configuration*
+**Example**: See `daily-compiler-quality.md` workflow
 
 ## Best Practices
 
-- **Default to simpler tools** when possible
-- **Only suggest Serena** for genuinely complex analysis tasks
-- **Ask before adding** Serena to a workflow
-- **Explain the benefits** when suggesting Serena
-- **Consider the trade-offs** (added complexity vs. better analysis)
+### 1. Combine with Other Tools
+
+Serena works best **in combination** with standard tools:
+
+```yaml
+tools:
+  serena: ["go"]
+  github:
+    toolsets: [default]  # For repo info
+  bash:
+    - "find pkg -name '*.go'"  # File discovery
+    - "cat go.mod"  # Read dependencies
+  edit:  # For making changes
+```
+
+**Use bash for discovery, Serena for analysis, edit for changes.**
+
+### 2. Use Cache Memory for State
+
+For recurring workflows, track analysis history:
+
+```yaml
+tools:
+  serena: ["go"]
+  cache-memory: true
+```
+
+**Pattern**: Load cache → analyze new/changed files → save results → avoid redundant work
+
+### 3. Start with Project Activation
+
+Always activate the project first:
+
+```javascript
+// Use activate_project tool
+{
+  "path": "/home/runner/work/gh-aw/gh-aw"
+}
+```
+
+### 4. Leverage Memory for Insights
+
+Store long-term insights using Serena's memory:
+
+```javascript
+// write_memory tool
+{
+  "name": "authentication_pattern",
+  "content": "Auth logic centralized in pkg/auth/handler.go"
+}
+```
+
+### 5. Don't Over-Use Serena
+
+**Good**: "Analyze function call graph for authentication flow" → Use Serena
+
+**Bad**: "Read package.json to get version" → Just use bash `cat package.json`
+
+**Rule of thumb**: If grep/bash can do it in 1-2 commands, don't use Serena.
+
+## Common Pitfalls
+
+### ❌ Using Serena for Non-Code Files
+
+**Wrong**: Analyzing YAML/JSON/Markdown with Serena
+**Right**: Use `view`, `edit`, or `bash` tools
+
+### ❌ Forgetting to Activate Project
+
+**Wrong**: Directly calling Serena tools without activation
+**Right**: Call `activate_project` first
+
+### ❌ Not Combining with Bash
+
+**Wrong**: Using only Serena tools for everything
+**Right**: Use bash for file discovery, Serena for semantic analysis
+
+### ❌ Missing Language Configuration
+
+**Wrong**: Adding `serena: true` without specifying language
+**Right**: `serena: ["go"]` with explicit language(s)
+
+## Real-World Examples
+
+### Example Workflows Using Serena
+
+1. **go-fan.md** - Go module usage reviewer (83 successful runs)
+   - Uses Serena for semantic analysis of module usage
+   - Combines with GitHub API for repo metadata
+   - Round-robin selection with priority for recent updates
+
+2. **sergo.md** - Daily Go code quality analyzer (17 of 18 runs successful)
+   - Scans available Serena tools dynamically
+   - 50% cached strategies, 50% new exploration
+   - Tracks success metrics in cache
+
+3. **semantic-function-refactor.md** - Function clustering analyzer
+   - Uses Serena to find duplicate/similar functions
+   - Identifies outliers (functions in wrong files)
+   - Semantic pattern detection beyond text matching
+
+4. **daily-compiler-quality.md** - Compiler code quality checker
+   - Rotating file analysis with cache tracking
+   - Uses Serena for semantic quality assessment
+   - Avoids re-analyzing unchanged files
+
+5. **cloclo.md** - Claude-powered general assistant
+   - Serena available for code analysis requests
+   - Combined with Playwright and other tools
+   - Flexible for various task types
+
+### Success Metrics
+
+Based on recent workflow runs:
+- **go-fan**: 81/83 successful runs (97.6% success rate)
+- **sergo**: 17/18 successful runs (94.4% success rate)
+- **Average execution time**: 6-8 minutes for Serena workflows
+- **Most common language**: Go (100% of analyzed workflows)
+
+## Decision Tree
+
+```
+Does the task require understanding code semantics/structure?
+├─ NO  → Use bash, edit, view, grep instead
+└─ YES → Continue
+    │
+    ├─ Is it simple text search/replace?
+    │  └─ YES → Use grep/bash instead
+    │
+    ├─ Is it for non-code files (YAML, JSON, MD)?
+    │  └─ YES → Use view/edit instead
+    │
+    └─ Does it involve:
+       ├─ Finding symbol usages?
+       ├─ Analyzing code structure?
+       ├─ Detecting semantic patterns?
+       ├─ Understanding dependencies?
+       └─ YES to any → Use Serena! ✅
+```
+
+## Getting Help
+
+- **Serena config**: Check `.serena/project.yml` in repository
+- **Tool list**: Use `get_current_config` MCP tool to see available tools
+- **Language servers**: Serena auto-detects based on project files
+- **Debugging**: Use `restart_language_server` if LSP has issues

From 38b4c7bb15d7598f5dbf83f9d7780e8ed9005a79 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 1 Feb 2026 12:03:39 +0000
Subject: [PATCH 3/4] Remove Serena memory features and language detection
 section per feedback

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/serena-tool.md | 45 +--------------------------------------
 1 file changed, 1 insertion(+), 44 deletions(-)

diff --git a/.github/aw/serena-tool.md b/.github/aw/serena-tool.md
index ed907fdd97..d260bed239 100644
--- a/.github/aw/serena-tool.md
+++ b/.github/aw/serena-tool.md
@@ -78,33 +78,6 @@ tools:
 
 The first language is the default fallback.
 
-## Detecting Repository Language
-
-**Method 1: Check language-specific files**
-```bash
-# Go
-[ -f go.mod ] && echo "go"
-
-# TypeScript/JavaScript  
-[ -f package.json ] && echo "typescript"
-
-# Python
-[ -f requirements.txt ] || [ -f pyproject.toml ] && echo "python"
-
-# Rust
-[ -f Cargo.toml ] && echo "rust"
-
-# Java
-[ -f pom.xml ] || [ -f build.gradle ] && echo "java"
-```
-
-**Method 2: Examine file extensions**
-```bash
-find . -type f -name "*.go" | head -1  # Go files
-find . -type f -name "*.ts" | head -1  # TypeScript
-find . -type f -name "*.py" | head -1  # Python
-```
-
 ## Available Serena Tools
 
 Once Serena is enabled, you have access to powerful MCP tools:
@@ -133,10 +106,6 @@ Once Serena is enabled, you have access to powerful MCP tools:
 - `onboarding` - Analyze project structure and essential tasks
 - `activate_project` - Activate Serena for a workspace
 - `restart_language_server` - Restart LSP if needed
-
-### Memory and State
-
-- `write_memory` / `read_memory` / `list_memories` - Store project insights
 - `get_current_config` - View Serena configuration
 
 ## Practical Usage Patterns
@@ -258,19 +227,7 @@ Always activate the project first:
 }
 ```
 
-### 4. Leverage Memory for Insights
-
-Store long-term insights using Serena's memory:
-
-```javascript
-// write_memory tool
-{
-  "name": "authentication_pattern",
-  "content": "Auth logic centralized in pkg/auth/handler.go"
-}
-```
-
-### 5. Don't Over-Use Serena
+### 4. Don't Over-Use Serena
 
 **Good**: "Analyze function call graph for authentication flow" → Use Serena
 

From 194afe17a7e5f732f5999f74eabaf21bcfbe18cf Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 1 Feb 2026 12:12:09 +0000
Subject: [PATCH 4/4] Optimize serena-tool.md for agentic planning - make it
 action-oriented and concise

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 .github/aw/serena-tool.md | 350 +++++++++++---------------------------
 1 file changed, 100 insertions(+), 250 deletions(-)

diff --git a/.github/aw/serena-tool.md b/.github/aw/serena-tool.md
index d260bed239..706ebface3 100644
--- a/.github/aw/serena-tool.md
+++ b/.github/aw/serena-tool.md
@@ -1,323 +1,173 @@
 # Serena Language Server Tool
 
-Serena is a **language service protocol (LSP) MCP server** that provides advanced code intelligence through semantic analysis, symbol navigation, and code understanding. It's designed for **deep code analysis tasks** that require understanding code structure, relationships, and semantics beyond simple text manipulation.
+Serena is a **language service protocol (LSP) MCP server** for semantic code analysis. Use it ONLY when you need deep code understanding beyond text manipulation.
 
-## When to Use Serena
+## Quick Decision: Should I Use Serena?
 
-Serena is powerful for **semantic code analysis** but comes with setup overhead. Use it when tasks genuinely require language-aware understanding:
+**✅ YES - Use Serena when you need:**
+- Symbol navigation (find all usages of a function/type)
+- Call graph analysis across files
+- Semantic duplicate detection (not just text matching)
+- Refactoring analysis (functions in wrong files, extraction opportunities)
+- Type relationships and interface implementations
 
-### ✅ Excellent Use Cases
+**❌ NO - Use simpler tools when:**
+- Searching text patterns → Use `grep`
+- Editing files → Use `edit` tool
+- Running commands → Use `bash`
+- Working with YAML/JSON/Markdown → Use `edit` tool
+- Simple file operations → Use `bash` or `create`
 
-**Symbol and dependency analysis:**
-- Finding all usages of a function/type across files
-- Analyzing call graphs and dependency relationships
-- Identifying duplicate or similar code patterns semantically
-- Discovering outlier functions in wrong files
-
-**Code quality and refactoring:**
-- Detecting code that should be extracted or consolidated
-- Analyzing function organization and clustering
-- Identifying refactoring opportunities based on code structure
-- Validating type usage and interface implementations
-
-**Deep code understanding:**
-- Understanding complex codebases quickly
-- Analyzing module usage patterns
-- Identifying architectural improvements
-- Cross-file semantic analysis
-
-### ❌ Poor Use Cases (Use simpler tools instead)
-
-**Simple text operations:**
-- Basic file editing or text manipulation → Use `edit` tool
-- Search/replace by pattern → Use `grep` or `bash`
-- File creation/deletion → Use `create` or `bash`
-
-**When grep/bash suffice:**
-- Finding text patterns → Use `grep`
-- Listing files → Use `find` or `glob`
-- Line counting → Use `wc`
-- Simple code searches → Use `grep` with regex
-
-**Configuration or data files:**
-- YAML/JSON/config file edits → Use `edit` tool
-- Markdown documentation → Use `edit` tool
-- Non-code analysis → Serena won't help
+**Rule of thumb**: If `grep` or `bash` can solve it in 1-2 commands, don't use Serena.
 
 ## Configuration
 
-Enable Serena by specifying target language(s) in workflow frontmatter:
+Add to workflow frontmatter:
 
 ```yaml
 tools:
-  serena: ["<language>"]  # One or more languages
+  serena: ["go"]  # Specify language(s): go, typescript, python, ruby, rust, java, cpp, csharp
 ```
 
-### Supported Languages
-
-Primary supported languages (with full LSP features):
-- `go` - Go language (gopls)
-- `typescript` - TypeScript/JavaScript
-- `python` - Python (jedi or pyright)
-- `ruby` - Ruby (solargraph)
-- `rust` - Rust (rust-analyzer)
-- `java` - Java
-- `cpp` - C/C++
-- `csharp` - C#
-
-See `.serena/project.yml` for the complete list (25+ languages).
-
-### Multi-language Support
-
-For repositories with multiple languages:
-
+Multi-language repositories:
 ```yaml
 tools:
-  serena: ["go", "typescript"]  # Multiple languages
+  serena: ["go", "typescript"]  # First language is default fallback
 ```
 
-The first language is the default fallback.
-
 ## Available Serena Tools
 
-Once Serena is enabled, you have access to powerful MCP tools:
-
-### Core Navigation Tools
-
-- `read_file` - Read file contents with semantic understanding
-- `list_dir` - List directory contents
-- `get_symbols_overview` - Get all symbols (functions, types) in a file
-- `find_symbol` - Search for symbols by name (global or local)
+### Navigation & Analysis
+- `find_symbol` - Search for symbols by name
+- `get_symbols_overview` - List all symbols in a file
 - `find_referencing_symbols` - Find where a symbol is used
-- `find_referencing_code_snippets` - Find code snippets referencing a symbol
+- `find_referencing_code_snippets` - Find code snippets using a symbol
+- `search_for_pattern` - Search for code patterns (regex)
 
-### Code Editing Tools
-
-- `create_text_file` - Create or overwrite files
-- `insert_at_line` - Insert content at specific line
+### Code Editing
+- `read_file` - Read file with semantic context
+- `create_text_file` - Create/overwrite files
+- `insert_at_line` - Insert content at line number
 - `insert_before_symbol` / `insert_after_symbol` - Insert near symbols
-- `replace_lines` - Replace line range with new content
-- `replace_symbol_body` - Replace entire symbol definition
+- `replace_lines` - Replace line range
+- `replace_symbol_body` - Replace symbol definition
 - `delete_lines` - Delete line range
 
-### Analysis Tools
-
-- `search_for_pattern` - Search for code patterns
-- `onboarding` - Analyze project structure and essential tasks
-- `activate_project` - Activate Serena for a workspace
+### Project Management
+- `activate_project` - **REQUIRED** - Activate Serena for workspace
+- `onboarding` - Analyze project structure
 - `restart_language_server` - Restart LSP if needed
 - `get_current_config` - View Serena configuration
+- `list_dir` - List directory contents
 
-## Practical Usage Patterns
+## Usage Workflow
 
-### Pattern 1: Find All Usages of a Function
+### 1. Activate Serena First
 
-**Workflow**: Analyzing how a function is used across the codebase
+**Always call activate_project before other Serena tools:**
 
-```yaml
-tools:
-  serena: ["go"]
+```javascript
+// activate_project tool
+{
+  "path": "/home/runner/work/gh-aw/gh-aw"
+}
 ```
 
-**Agent tasks:**
-1. Use `find_symbol` to locate the function definition
-2. Use `find_referencing_code_snippets` to find all call sites
-3. Analyze patterns and suggest improvements
+### 2. Combine with Other Tools
 
-**Example**: See `go-fan.md` workflow (analyzes Go module usage)
-
-### Pattern 2: Code Quality Analysis
-
-**Workflow**: Identify refactoring opportunities by clustering functions
+**Best practice**: Use bash for discovery, Serena for analysis
 
 ```yaml
 tools:
   serena: ["go"]
+  bash:
+    - "find pkg -name '*.go' ! -name '*_test.go'"
+    - "cat go.mod"
+  github:
+    toolsets: [default]
 ```
 
-**Agent tasks:**
-1. Use `get_symbols_overview` on multiple files
-2. Use `find_symbol` to locate similar function names
-3. Use `search_for_pattern` to find duplicate patterns
-4. Identify outliers and suggest consolidation
+**Pattern**: 
+1. Use `bash` to list files
+2. Use Serena to analyze semantic structure
+3. Use `edit` to make changes
 
-**Example**: See `semantic-function-refactor.md` workflow (clusters functions semantically)
+### 3. Use Cache for Recurring Analysis
 
-### Pattern 3: Daily Code Deep Dives
-
-**Workflow**: Systematically analyze codebase over time
+Track analysis state across runs:
 
 ```yaml
 tools:
   serena: ["go"]
-  cache-memory: true  # Track analysis history
+  cache-memory: true  # Store analysis history
 ```
 
-**Agent tasks:**
-1. Load previous analysis state from cache
-2. Select rotation strategy (round-robin, prioritize recent updates)
-3. Use Serena for deep semantic analysis
-4. Save findings to cache for next run
-5. Generate actionable improvement tasks
-
-**Examples**: 
-- `sergo.md` - Daily Go analysis with 50/50 cached/new strategies
-- `go-fan.md` - Daily Go module reviewer with round-robin
+Load cache → Analyze new/changed files → Save results → Avoid redundant work
 
-### Pattern 4: Compiler/Large File Analysis
+## Common Patterns
 
-**Workflow**: Analyze large complex files for quality
+### Pattern 1: Find All Function Usages
 
-```yaml
-tools:
-  serena: ["go"]
-  cache-memory: true
-  bash:
-    - "find pkg/workflow -name 'compiler*.go' ! -name '*_test.go'"
-    - "wc -l pkg/workflow/compiler*.go"
 ```
-
-**Agent tasks:**
-1. Use bash to identify target files
-2. Track file hashes to detect changes
-3. Use Serena for semantic analysis only on changed files
-4. Focus on human-written quality standards
-
-**Example**: See `daily-compiler-quality.md` workflow
-
-## Best Practices
-
-### 1. Combine with Other Tools
-
-Serena works best **in combination** with standard tools:
-
-```yaml
-tools:
-  serena: ["go"]
-  github:
-    toolsets: [default]  # For repo info
-  bash:
-    - "find pkg -name '*.go'"  # File discovery
-    - "cat go.mod"  # Read dependencies
-  edit:  # For making changes
+1. Use find_symbol to locate function definition
+2. Use find_referencing_code_snippets to find call sites
+3. Analyze patterns
 ```
 
-**Use bash for discovery, Serena for analysis, edit for changes.**
-
-### 2. Use Cache Memory for State
-
-For recurring workflows, track analysis history:
+### Pattern 2: Code Quality Analysis
 
-```yaml
-tools:
-  serena: ["go"]
-  cache-memory: true
+```
+1. Use get_symbols_overview on multiple files
+2. Use find_symbol for similar function names
+3. Use search_for_pattern for duplicate logic
+4. Identify consolidation opportunities
 ```
 
-**Pattern**: Load cache → analyze new/changed files → save results → avoid redundant work
-
-### 3. Start with Project Activation
-
-Always activate the project first:
+### Pattern 3: Daily Code Analysis
 
-```javascript
-// Use activate_project tool
-{
-  "path": "/home/runner/work/gh-aw/gh-aw"
-}
+```
+1. Load previous state from cache-memory
+2. Select files using round-robin or priority
+3. Use Serena for semantic analysis
+4. Save findings to cache
+5. Generate improvement tasks
 ```
 
-### 4. Don't Over-Use Serena
-
-**Good**: "Analyze function call graph for authentication flow" → Use Serena
+## Production Examples
 
-**Bad**: "Read package.json to get version" → Just use bash `cat package.json`
+Workflows successfully using Serena:
 
-**Rule of thumb**: If grep/bash can do it in 1-2 commands, don't use 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
-
-**Wrong**: Analyzing YAML/JSON/Markdown with Serena
-**Right**: Use `view`, `edit`, or `bash` tools
-
-### ❌ Forgetting to Activate Project
-
-**Wrong**: Directly calling Serena tools without activation
-**Right**: Call `activate_project` first
-
-### ❌ Not Combining with Bash
-
-**Wrong**: Using only Serena tools for everything
-**Right**: Use bash for file discovery, Serena for semantic analysis
-
-### ❌ Missing Language Configuration
+❌ **Using Serena for non-code files** - Use `edit` for YAML/JSON/Markdown
+❌ **Forgetting activate_project** - Always call first
+❌ **Not combining with bash** - Use bash for file discovery
+❌ **Missing language configuration** - Must specify language(s)
 
-**Wrong**: Adding `serena: true` without specifying language
-**Right**: `serena: ["go"]` with explicit language(s)
+## Supported Languages
 
-## Real-World Examples
+Primary languages with full LSP features:
+- `go` (gopls)
+- `typescript` (TypeScript/JavaScript)
+- `python` (jedi/pyright)
+- `ruby` (solargraph)
+- `rust` (rust-analyzer)
+- `java`, `cpp`, `csharp`
 
-### Example Workflows Using Serena
-
-1. **go-fan.md** - Go module usage reviewer (83 successful runs)
-   - Uses Serena for semantic analysis of module usage
-   - Combines with GitHub API for repo metadata
-   - Round-robin selection with priority for recent updates
-
-2. **sergo.md** - Daily Go code quality analyzer (17 of 18 runs successful)
-   - Scans available Serena tools dynamically
-   - 50% cached strategies, 50% new exploration
-   - Tracks success metrics in cache
-
-3. **semantic-function-refactor.md** - Function clustering analyzer
-   - Uses Serena to find duplicate/similar functions
-   - Identifies outliers (functions in wrong files)
-   - Semantic pattern detection beyond text matching
-
-4. **daily-compiler-quality.md** - Compiler code quality checker
-   - Rotating file analysis with cache tracking
-   - Uses Serena for semantic quality assessment
-   - Avoids re-analyzing unchanged files
-
-5. **cloclo.md** - Claude-powered general assistant
-   - Serena available for code analysis requests
-   - Combined with Playwright and other tools
-   - Flexible for various task types
-
-### Success Metrics
-
-Based on recent workflow runs:
-- **go-fan**: 81/83 successful runs (97.6% success rate)
-- **sergo**: 17/18 successful runs (94.4% success rate)
-- **Average execution time**: 6-8 minutes for Serena workflows
-- **Most common language**: Go (100% of analyzed workflows)
+See `.serena/project.yml` for complete list (25+ languages).
 
 ## Decision Tree
 
 ```
-Does the task require understanding code semantics/structure?
-├─ NO  → Use bash, edit, view, grep instead
-└─ YES → Continue
-    │
-    ├─ Is it simple text search/replace?
-    │  └─ YES → Use grep/bash instead
-    │
-    ├─ Is it for non-code files (YAML, JSON, MD)?
-    │  └─ YES → Use view/edit instead
-    │
-    └─ Does it involve:
-       ├─ Finding symbol usages?
-       ├─ Analyzing code structure?
-       ├─ Detecting semantic patterns?
-       ├─ Understanding dependencies?
-       └─ YES to any → Use Serena! ✅
+Task requires code semantics/structure?
+├─ NO → Use bash/edit/view
+└─ YES
+    ├─ Simple text search/replace? → Use grep/bash
+    ├─ Config/data files? → Use edit
+    └─ Symbol/structure/semantic patterns? → Use Serena ✅
 ```
-
-## Getting Help
-
-- **Serena config**: Check `.serena/project.yml` in repository
-- **Tool list**: Use `get_current_config` MCP tool to see available tools
-- **Language servers**: Serena auto-detects based on project files
-- **Debugging**: Use `restart_language_server` if LSP has issues