Bratan

Pass model explicitly when dispatching sub-agents. Parent-default inheritance bypasses cost considerations; reserve stronger models for tasks that genuinely need them.

When a commit changes a component's public API, the same commit must update every test asserting the removed surface — split commits leave CI broken even when each commit is internally consistent.

When a class of bug keeps slipping through tests, run a coverage-matrix audit first, then fan out fix agents per gap — don't whack-a-mole individual failures.

Before pushing to CI, validate that your local test run is representative — three predictable axes diverge (gitignored fixtures, dev-only ports, dev-only env vars) and each has a deterministic fix.

Land every code fix before running the test harness. Use grep + read to debug; the harness is a verifier, not a debugger.

Tests that mock the layer where the bug lives cannot catch bugs at that layer. Write tests that drive the same code path the user drives, ending at something the user can see.

When verifying or fixing a multi-layer change, dispatch each test layer and each independent fix as a parallel sub-agent rather than running serially in the main context.

Before saying "ready, retest", prove the state is clean by running a concrete numbered checklist. Never claim clean state — demonstrate it with real command output.

Wrap both read and write paths through any client that holds per-path singleton state in a subprocess worker, so on-disk state changes are always reflected without a full process restart.

When verifier agents share a long-running server process with the user, state that poisons the verifier flows directly into the user's next interaction. End every verifier run with process-level restart and a round-trip health check.

Use this skill to attribute the contribution of each pipeline stage by systematically disabling one stage at a time and re-running eval. Tells the Blue Team whether reranking (or hybrid retrieval, or query rewriting, etc.) is actually paying its keep, and which stage to invest tuning effort in. Reach for it before any non-trivial structural change.

Use this skill when the Blue Team needs to tune a small set of numeric hyperparameters (chunk size, top-k, rrf_k, top-n for reranker, generation temperature) and the eval call is expensive enough that random or grid search would burn the budget. Bayesian Optimization uses a probabilistic surrogate (Gaussian Process or Tree-structured Parzen Estimator) to propose the next point most worth evaluating.

Use this skill when the Blue Team is tuning 1–2 discrete or low-cardinality parameters (k, top_n, rrf_k, chunk_overlap) and the Cartesian product is small enough to enumerate exhaustively. Simpler than Bayesian Optimization, with the advantage that every cell of the grid is reported so the result is visually inspectable.

Use this skill when the Blue Team needs to optimize over a mixed continuous + discrete + categorical space too large for grid search and too rough for Bayesian Optimization's Gaussian-Process surrogate. PSO and its evolutionary cousins (CMA-ES, GA) navigate jagged surfaces by maintaining a population of candidates that pull toward both individual and global bests.

Use this skill to add a post-generation pass that verifies every citation in the LLM's answer actually appears in (and is supported by) the cited chunk. Reach for it when the faithfulness score is low even though retrieval is healthy, or when invented citations are surfacing as a failure category.

Use this skill when chunks have ambiguous referents that hurt retrieval — for example, a paragraph starting "It supports up to 10,000 connections" where "it" is whatever the document is about. The technique prepends an LLM-generated context block to each chunk before embedding, so the chunk embeds in the right region of vector space.

Use this skill when you need to interpret /reports/latest.json to find the root cause behind multiple failing cases. Reach for it before making changes to the pipeline, so you fix one root cause at a time instead of whacking moles. The output is "here is the cluster, here is the hypothesis, here is the suggested fix layer".

Use this skill when failures show that vector search is missing exact-token matches (product names, error codes, version numbers, identifiers) or conversely when keyword search is missing semantic paraphrases. This skill documents how to add a BM25 lane alongside the vector lane and merge the results with Reciprocal Rank Fusion.

Use this skill when you need high-level guidance on the structure of a RAG pipeline — what stages it should have, what trade-offs each stage makes, when to add or remove a stage. Reach for it for architectural decisions, not numeric tuning.

Use this skill when generating new failure-targeting test cases. Documents techniques for producing questions that are diverse, non-trivial, and actually defeat the current pipeline — not paraphrases of existing test cases. Most useful for the red team agent.