--- name: rawq-3fc5dedb61b8 description: "Context retrieval engine. Semantic + lexical hybrid search over codebases. Returns ranked code chunks with file paths, line ranges, scope labels, and confidence scores." --- # rawq — Agent Usage Guide Context retrieval engine. Semantic + lexical hybrid search over codebases. Returns ranked code chunks with file paths, line ranges, scope labels, and confidence scores. ## When to use rawq Use rawq when you don't know where to look. Use grep/read when you already know the file or exact string. | Situation | Tool | |-----------|------| | "Where is retry logic implemented?" | `rawq search` | | "Find the function named `parse_config`" | `rawq search` or `grep` | | "Read line 42 of src/main.rs" | `read` | | "What does this codebase do?" | `rawq map` | | "What changed and how does it affect X?" | `rawq diff` | ## Query style matters rawq blends semantic (embedding) and lexical (BM25) search. **How you phrase the query changes which mode dominates.** **Use natural language for concepts** — this is where rawq beats grep: ```bash rawq search "how does the app handle authentication failures" . rawq search "database connection pooling and retry logic" . rawq search "where are environment variables validated" . ``` **Use identifiers only for exact symbol lookup:** ```bash rawq search "fn parse_config" . rawq search "class DatabaseClient" . ``` **Do NOT use grep-style keyword queries with rawq.** These produce worse results: ```bash # BAD — grep-style keywords, rawq can't infer intent rawq search "auth error" . rawq search "db pool" . # GOOD — natural language, rawq understands the concept rawq search "how does authentication error handling work" . rawq search "database connection pool management" . ``` The more descriptive your query, the better semantic search works. Single keywords trigger lexical-dominant mode which is just BM25 — no better than grep. ## Use filtering options Agents often search the entire codebase when they already know constraints. Use filters to narrow results and improve relevance: ```bash # Filter by language — skip irrelevant file types rawq search "parse config" . --lang rust rawq search "API endpoint" . --lang typescript # Exclude patterns — skip tests, generated code, vendored deps rawq search "database" . --exclude "*.test.*" --exclude "vendor/*" # Force search mode when you know what you need rawq search -e "reconnect" . # lexical only — exact keyword match rawq search -s "how does caching work" . # semantic only — concept search # Re-rank for better precision on ambiguous queries rawq search "error handling" . --rerank # Text weight — boost docs/comments when searching for explanations rawq search "how to configure" . --text-weight 1.0 # Token budget — control how much context is returned rawq search "auth" . --token-budget 2000 --json ``` ## Commands ### search — find relevant code ```bash rawq search "query" [path] # hybrid search (default) rawq search "query" [path] --json # structured JSON for parsing rawq search "query" [path] --lang rust # only Rust files rawq search "query" [path] --exclude "test*" # skip test files rawq search "query" [path] --top 5 # limit to 5 results rawq "query" [path] # shorthand (no subcommand needed) ``` Key flags: - `--top N` — number of results (default 10) - `--context N` — surrounding context lines (default 3) - `--json` — structured output with all fields - `--stream` — NDJSON streaming (one result per line) - `--lang X` — filter by language - `--exclude "glob"` — skip matching files - `-e` / `-s` — force lexical / semantic mode - `--rerank` — two-pass keyword overlap re-ranking - `--text-weight F` — weight for text/markdown chunks (default 0.5, use 1.0 for docs) - `--token-budget N` — max tokens in results - `--full-file` — include full file content in results ### map — codebase structure ```bash rawq map . # definitions with hierarchy rawq map . --depth 3 # deeper nesting rawq map . --lang rust # only Rust files rawq map . --exclude "test*" # skip test directories rawq map . --json # structured output ``` Use to orient in an unfamiliar codebase before searching. **Filter with `--lang` and `--exclude`** to avoid noise from irrelevant files. ### diff — search within changes ```bash rawq diff "query" . # unstaged changes rawq diff "query" . --staged # staged changes rawq diff "query" . --base main # diff vs branch ``` ## JSON output format ```json { "schema_version": 1, "model": "snowflake-arctic-embed-s", "results": [ { "file": "src/db.rs", "lines": [23, 41], "display_start_line": 23, "language": "rust", "scope": "DatabaseClient.reconnect", "confidence": 0.91, "content": "...", "context_before": "...", "context_after": "...", "token_count": 45 } ], "query_ms": 8, "total_tokens": 45 } ``` ## Workflow 1. `rawq map .` — understand the structure 2. `rawq search "descriptive query" . --json` — find relevant code 3. Read the top results' files for full context 4. Act on what you found rawq narrows down which files matter. Read those files, not everything. --- Source attribution: auyelbekov Original project: https://github.com/auyelbekov/rawq/blob/56a5eaab8994a6e7dee356554562cdc23da25773/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 Yerzhigit Auyelbekov Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: auyelbekov Original project: https://github.com/auyelbekov/rawq/blob/56a5eaab8994a6e7dee356554562cdc23da25773/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Product Management Roles: Backend Developer, Data Engineer, Product Manager, QA / Test Engineer, Technical Product Manager Specialties: API, Backend Tools: Rawq Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 233b7ce4053f8c0a76eb6b0805f2fc91fe719069476f96eb7eadaedab0033a2e