[caveman] Optimize instruction verbosity — serena-tool, skills, subagents (2026-06-12)

.github/aw/serena-tool.md

@@ -1,28 +1,27 @@
 # Serena Language Server Tool
 
-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.
+Serena is an **LSP MCP server** for semantic code analysis. Use ONLY when you need deep code understanding beyond text manipulation.
 
-## Quick Decision: Should I Use Serena?
+## When to Use Serena
 
-**✅ YES - Use Serena when you need:**
+**Use 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
 
-**❌ 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`
+**Don't use Serena for:**
+- Text patterns → `grep`
+- File edits → `edit` tool
+- Commands → `bash`
+- YAML/JSON/Markdown → `edit` tool
 
-**Rule of thumb**: If `grep` or `bash` can solve it in 1-2 commands, don't use Serena.
+If `grep` or `bash` can solve it in 1-2 commands, don't use Serena.
 
 ## Configuration
 
-Configure Serena through the shared workflow import. For multi-language, the first entry is the default fallback:
+Import the shared workflow. For multi-language, the first entry is the default fallback:
 
 ```yaml
 imports:
@@ -60,11 +59,11 @@ imports:
 
 ### 1. Activate Serena First
 
-Always call `activate_project` before other Serena tools, passing the workspace path.
+Call `activate_project` before any other Serena tool, passing the workspace path.
 
 ### 2. Combine with Other Tools
 
-Use `bash` for file discovery, Serena for semantic analysis, `edit` for changes.
+`bash` for file discovery, Serena for semantic analysis, `edit` for changes.
 
 ```yaml
 imports:

.github/aw/skills.md

@@ -4,35 +4,30 @@ description: Guide for leveraging skills (SKILL.md files) in agentic workflows 
 
 # Skills in Agentic Workflows
 
-Consult this file when you want a workflow to take advantage of skills — domain-specific knowledge files (`SKILL.md`) that live in the repository under `skills/` or `.github/skills/`.
+Use skills — domain-specific knowledge files (`SKILL.md`) under `skills/` or `.github/skills/` — in workflows.
 
 ---
 
 ## Detecting Skills
 
-At runtime, find skill files with:
-
 ```bash
 find "${GITHUB_WORKSPACE}" -name "SKILL.md" -maxdepth 6
 ```
 
-List available skills and their locations before deciding which strategy to apply.
+List available skills before choosing a strategy.
 
 ---
 
 ## Inline Skills (Fusion at Authoring Time)
 
-**Use when**: You want to keep the main prompt compact while still shipping task-specific skill guidance with the workflow.
+**Use when**: keeping the main prompt compact while shipping task-specific skill guidance with the workflow.
 
-Inline skills let a workflow embed a complete skill or a partial skill fragment under `## skill: \`name\``.
-Extraction happens in the setup/interpolation runtime step of workflow execution, not at `.md` to `.lock.yml` compile time.
-gh-aw writes each block into engine-specific skill locations and removes those blocks from the main prompt body.
-This keeps the main prompt slim and flexible while still making the fused guidance available as skills.
+Inline skills embed a complete skill or fragment under `## skill: \`name\``. Extraction runs in the setup/interpolation step (not at compile time): gh-aw writes each block to engine-specific skill locations and removes it from the main prompt body.
 
-Use this to fuse:
+Use to fuse:
 
 - A full skill when the workflow needs a self-contained capability.
-- Partial skill sections when only targeted guidance is needed.
+- Partial sections when only targeted guidance is needed.
 
 **Pattern**:
 
@@ -52,17 +47,15 @@ Classify by bug / feature / question, identify missing information, and suggest
 the smallest actionable next step.
 ```
 
-Use a unique inline skill name per workflow file. The name can be arbitrary, but it must start with a lowercase letter and then use only lowercase letters, digits, `_`, or `-`.
-These constraints keep extracted skill paths predictable and engine-compatible.
-Avoid naming collisions with repository file-based skills (for example `.github/skills/<name>/SKILL.md`), because inline extraction writes to the same engine skill paths.
+Use a unique inline skill name per workflow file. Name must start with a lowercase letter, then lowercase letters, digits, `_`, or `-`. Avoid collisions with file-based skills under `.github/skills/<name>/SKILL.md` — inline extraction writes to the same paths.
 
 ---
 
 ## Strategy 1 — Hint (Generalist)
 
-**Use when**: The task strategy is not fully known at authoring time, or when the agent must adapt to whatever skills are available.
+**Use when**: the task strategy is unknown at authoring time, or the agent must adapt to whatever skills are available.
 
-The workflow prompt hints that skills exist and asks the agent to discover and apply the relevant ones itself. The agent decides which skill files to read and how much of each to use.
+The prompt tells the agent skills exist and to discover/apply the relevant ones itself.
 
 **Pattern**:
 
@@ -76,9 +69,9 @@ guidance it provides.
 
 ## Strategy 2 — Fusion (Ultra-Cognitive)
 
-**Use when**: You know exactly which skill (or which part of a skill) is needed, and you want to minimise context overhead.
+**Use when**: you know exactly which skill (or part of it) is needed and want minimal context overhead.
 
-Extract and inline **only the specific sections** of the skill content that the agent needs. Do not paste the entire SKILL.md; identify the minimal fragment, then remix it into the workflow prompt so the agent receives precise, surgical guidance without loading the full file.
+Inline **only the specific sections** of the skill the agent needs. Do not paste the entire SKILL.md.
 
 **Pattern**:
 
@@ -102,7 +95,7 @@ environment. Never prompt the user for credentials.
 | **Determinism** | Lower (agent chooses) | Higher (exact fragment) |
 | **Scale** | Poor (entire skills loaded) | Good (minimal content) |
 
-Fusion scales better because entire skills are never loaded. Prefer fusion when you know the task domain and the specific skill sections required.
+Fusion scales better because entire skills are never loaded. Prefer fusion when the task domain and required skill sections are known.
 
 ---
 

.github/aw/subagents.md

@@ -4,7 +4,7 @@ description: Guide for defining inline sub-agents in workflow markdown files —
 
 # Inline Sub-Agents
 
-Inline sub-agents let you define specialised agents directly inside a workflow markdown file. At runtime the sub-agent sections are extracted from the prompt (after `{{#runtime-import}}` macros are resolved) and written to the engine-specific agents directory so the engine CLI can discover and invoke them.
+Define specialised agents directly in a workflow markdown file. At runtime, sub-agent sections are extracted (after `{{#runtime-import}}` macros resolve) and written to the engine-specific agents directory for the engine CLI to discover.
 
 ---
 
@@ -90,11 +90,11 @@ tools:
 
 ## When to Use Sub-Agents
 
-Sub-agents are most useful in two scenarios:
+Two main scenarios:
 
 ### 1 — Parallel specialised tasks with smaller models
 
-Break a large workflow into parallel units of work, each handled by a small, cheap model, and then use the parent (large) model to reason over the aggregated results:
+Break a large workflow into parallel units handled by small/cheap models, then let the parent (large) model reason over the aggregated results:
 
 ```markdown
 # Investigate: Repository Health
@@ -137,24 +137,24 @@ resemble API keys, tokens, or passwords. Report any findings with the
 file name and approximate line number.
 ```
 
-The parent model (e.g. Claude Sonnet or Copilot) orchestrates, while the sub-agents do the heavy lifting with a `small` model at lower cost.
+The parent model orchestrates; sub-agents do the heavy lifting with `small` at lower cost.
 
 ### 2 — Reusable specialised helpers
 
-Extract a repetitive sub-task (file summarisation, commit-message generation, code explanation) into a named sub-agent that the main prompt can call by name, keeping the main prompt concise.
+Extract repetitive sub-tasks (file summarisation, commit-message generation, code explanation) into a named sub-agent the main prompt calls by name.
 
 ---
 
 ## Planner-Worker Pattern
 
-Use a planner-worker split to control cost and keep context quality high:
+Split work to control cost and keep context quality high:
 
-- **Main/frontier agent (planner-orchestrator):** forms hypotheses, decides what evidence is needed, chooses which workers to invoke, and synthesizes final conclusions
-- **Worker sub-agents (usually `model: small`):** execute bounded retrieval, extraction, classification, verification, and one-shot summarization tasks
+- **Main/frontier agent (planner-orchestrator):** forms hypotheses, decides what evidence is needed, picks workers, synthesises conclusions
+- **Worker sub-agents (usually `model: small`):** bounded retrieval, extraction, classification, verification, one-shot summarisation
 
-Prompt workers with narrow, evidence-oriented instructions (for example: “return exact error messages from failing step and line references”), not broad analysis requests.
+Prompt workers narrowly and evidence-first (e.g. "return exact error messages and line references"), not broad analysis.
 
-Worker outputs should be compact and structured (focused excerpts, short JSON, concise findings). Do not return raw logs, full API payloads, or large file dumps to the orchestrator unless explicitly required.
+Worker outputs should be compact and structured. Do not return raw logs or large file dumps to the orchestrator.
 
 ### Bounded delegation rules