retrieval-playbook-for-ai_skill

Overview

This skill provides a practical playbook for retrieving only the right context for AI tasks. It explains what to include, what to exclude, and how to prioritize snippets and files to save tokens and improve results. The guidance is task-oriented so retrieval is efficient and repeatable.

How this skill works

The playbook inspects the task type and pulls a minimal, prioritized set of context elements: the offending file or snippet, error messages, relevant types/interfaces, and direct dependencies. It uses rules (direct dependencies, snippets over full files, recency, and examples-only-when-needed) plus simple filtering (recency, relevance score, size) to assemble a compact context package.

When to use it

• Preparing context for bug fixes to include the exact failing code and error trace
• Assembling inputs for feature work to include similar implementations and API contracts
• Preparing diffs and related files for code reviews to keep scope narrow
• Scoping refactors by including the file, importers, and tests only
• Any time you need to reduce token usage while preserving task success

Best practices

• Always start with a one-line summary and the error or goal before code snippets
• Prefer 10–40 line snippets that contain the relevant logic rather than whole files
• Limit retrieval to the last few commits or recent changes, not full history
• Score and sort candidate files by relevance, then take the top 3–5
• Track metrics like filesRetrieved, tokensUsed, relevanceScore, and taskSuccess

Example use cases

• Fixing an authentication bug: include validateToken snippet, types, and error message
• Adding a feature: include one similar feature example, types, and API contract
• Code review: include changed files (diff) and any imported files that changed
• Refactoring a module: include the module, its importers, and its tests