Update skill guidance for search-first workflow

Author: rodion-m

skills/codealive-context-engine/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codealive-context-engine
-description: Semantic code search and AI-powered codebase Q&A across indexed repositories. Use when understanding code beyond local files, exploring dependencies, discovering cross-project patterns, planning features, debugging, or onboarding. Queries like "How does X work?", "Show me Y patterns", "How is library Z used?". Provides search (fast, returns file locations and descriptions) and chat-with-codebase (slower, costs more, but returns synthesized answers).
+description: Semantic code search and AI-powered codebase Q&A across indexed repositories. Use when understanding code beyond local files, exploring dependencies, discovering cross-project patterns, planning features, debugging, or onboarding. Queries like "How does X work?", "Show me Y patterns", "How is library Z used?". The default path is semantic search plus grep search; chat-with-codebase is slower, more expensive, and usually secondary.
 ---
 
 # CodeAlive Context Engine
@@ -44,7 +44,9 @@ Do NOT retry the failed script until setup completes successfully.
 | **Artifact Relationships** | `relationships.py` | Fast | Low | Drilling into call graph, inheritance, references for one artifact |
 | **Chat with Codebase** | `chat.py` | Slow | High | Synthesized answers, architectural explanations |
 
-**Cost guidance:** Search is lightweight and should be the default starting point. Chat with Codebase invokes an LLM on the server side, making it significantly more expensive per call — use it when you need a synthesized, ready-to-use answer rather than raw search results.
+**Cost guidance:** `semantic_search` and `grep_search` are the default starting point. Chat with Codebase invokes an LLM on the server side, can take up to 30 seconds, and is significantly more expensive per call — use it only when you need a synthesized, ready-to-use answer rather than raw search results.
+
+**Highest-confidence guidance:** If your agent supports subagents and the task needs maximum reliability or depth, prefer a subagent-driven workflow that combines `search.py`, `grep.py`, `fetch.py`, `relationships.py`, and local file reads. `chat.py` is optional synthesis, not the default path.
 
 **Three-step workflow (search → triage → load real content):**
 1. **Search** — find relevant code locations with descriptions and identifiers
@@ -110,7 +112,7 @@ python scripts/relationships.py "my-org/backend::src/models.py::User" --profile
 python scripts/relationships.py "my-org/backend::src/svc.py::Service" --profile allRelevant --max-count 200
 ```
 
-### 5. Chat with codebase (slower, richer answers)
+### 5. Chat with codebase (slower, optional synthesis)
 
 ```bash
 python scripts/chat.py "Explain the authentication flow" my-backend
@@ -211,7 +213,7 @@ python scripts/relationships.py <identifier> [--profile PROFILE] [--max-count N]
 
 Sends your question to an AI consultant that has full context of the indexed codebase. Returns synthesized, ready-to-use answers. Supports conversation continuity for follow-ups.
 
-**This is more expensive than search** because it runs an LLM inference on the server side. Prefer search when you just need to locate code. Use chat when you need explanations, comparisons, or architectural analysis.
+**This is more expensive than search** because it runs an LLM inference on the server side. Prefer search when you just need to locate code. Use chat when you need explanations, comparisons, or architectural analysis after search. It can take up to 30 seconds.
 
 ```bash
 python scripts/chat.py <question> <data_sources...> [options]
@@ -289,7 +291,7 @@ This skill works standalone, but delivers the best experience when combined with
 | Component | What it provides |
 |-----------|-----------------|
 | **This skill** | Query patterns, workflow guidance, cost-aware tool selection |
-| **MCP server** | Direct `semantic_search`, `grep_search`, `fetch_artifacts`, `get_artifact_relationships`, `codebase_consultant`, `get_data_sources` tools |
+| **MCP server** | Direct `semantic_search`, `grep_search`, `fetch_artifacts`, `get_artifact_relationships`, `chat`, `get_data_sources` tools plus deprecated aliases |
 
 When both are installed, prefer the MCP server's tools for direct operations and this skill's scripts for guided workflows.
 

skills/codealive-context-engine/references/query-patterns.md

@@ -298,7 +298,7 @@ Use when:
 1. **Use natural language** - CodeAlive understands intent, not just keywords
 2. **Be specific about context** - Include domain/layer info (API, database, frontend)
 3. **Leverage workspaces** - Search across multiple repos for patterns
-4. **Start with chat** - Ask "How does X work?" before searching
+4. **Start with search** - Use semantic search first, then grep when the literal pattern matters; only use chat after you have evidence and still need synthesis
 5. **Iterate** - Use follow-up questions to drill deeper
 6. **Combine with local tools** - CodeAlive for discovery, Read for details
 7. **Think like a librarian** - Focus on "what" and "why", not "where"

skills/codealive-context-engine/references/workflows.md

@@ -28,24 +28,24 @@ Review output to understand:
 - What workspaces group related repos
 - Which data sources to use for exploration
 
-### Step 2: Get Architectural Overview
+### Step 2: Understand Entry Points
 ```bash
-python chat.py "Provide an architectural overview of this codebase. What are the main components, how do they interact, and what's the tech stack?" my-backend-repo
+python search.py "main application entry point, startup initialization" my-backend-repo
 ```
 
-### Step 3: Understand Entry Points
+### Step 3: Explore Key Features
 ```bash
-python search.py "main application entry point, startup initialization" my-backend-repo
+python search.py "main features, core capabilities, major services" my-backend-repo
 ```
 
-### Step 4: Explore Key Features
+### Step 4: Get Architectural Overview Only If Needed
 ```bash
-python chat.py "What are the main features/capabilities of this system?" my-backend-repo
+python chat.py "Provide an architectural overview of this codebase. What are the main components, how do they interact, and what's the tech stack?" my-backend-repo
 ```
 
 ### Step 5: Understand Data Models
 ```bash
-python search.py "database models, schemas, entity definitions" my-backend-repo --mode auto
+python search.py "database models, schemas, entity definitions" my-backend-repo
 ```
 
 **Progressive Discovery:**
@@ -61,18 +61,19 @@ python search.py "database models, schemas, entity definitions" my-backend-repo
 
 ### Example: Understanding User Authentication
 
-#### Step 1: Start with High-Level Question
+#### Step 1: Start with Search
 ```bash
-python chat.py "How is user authentication implemented? Describe the flow from login to session management" my-backend
+python search.py "user authentication, login flow, session management" my-backend
+python grep.py "refresh token" my-backend
 ```
 
-Save conversation_id for follow-up questions.
-
-#### Step 2: Find Entry Points
+#### Step 2: Use Chat Only If You Still Need Synthesis
 ```bash
-python search.py "user login endpoint, authentication API" my-backend
+python chat.py "How is user authentication implemented? Describe the flow from login to session management" my-backend
 ```
 
+Save conversation_id for follow-up questions.
+
 #### Step 3: Trace Through Layers
 ```bash
 # API Layer