Hard-won gotchas building a .NET Aspire app with gRPC, a message bus, and an in-process agent, the kind that each cost a debugging session. Use when an Aspire service cannot reach another (service discovery, "No such host"), wiring gRPC between Aspire projects (HTTP/2, HTTPS, ALPN), adding RabbitMQ via Aspire (guest login fails, generated password, Not_Authorized), using MassTransit (v8 vs v9 licensing, IBus vs IPublishEndpoint, captive dependency), passing AppHost configuration or parameters (the `__` env-var separator, AddParameter from appsettings/user-secrets, where each setting should live, clone-and-run defaults, Worker SDK appsettings copy), building an agent with the Microsoft Agent Framework (Microsoft.Agents.AI, ChatClientAgent, function tools, an OpenAI-compatible/LiteLLM endpoint, CodeAct/Agent Harness providers, compacting a long-lived AgentSession), a Web SDK project hitting an ambiguous type like SessionOptions, the AppHost not seeing app types, exporting OpenTelemetry GenAI telemetry or fannin
See and drive a locally-running web app in a real browser to verify a change — navigate, screenshot, read console errors, and poke page state via eval. Use when verifying a visual or behavioral change to any web project (UI tweak, new component, animation, form, bug fix), comparing the rendered page against intent, or reproducing a runtime error. Also covers responsive/viewport testing with resize and verifying animations by sampling element state over time (not from a single screenshot), and the gotcha that an eval reading state right after a click returns stale values because the framework re-renders asynchronously. Project-agnostic; uses the global @playwright/cli (playwright-cli).
Performance techniques for canvas 2D render loops that draw thousands of small elements (star fields, particle systems, point clouds, scatter plots) and are CPU-bound or janky, especially on low-end devices. Use when a requestAnimationFrame canvas loop is slow, when optimizing a per-frame draw over many points, or when deciding what is actually expensive (per-element trig/projection vs canvas draw calls). Covers caching a slowly-changing projection and reprojecting at a low rate, sprite blitting (drawImage) instead of per-element beginPath/arc/fill and the per-element fillStyle color-string parse it avoids, color-bucket sprite atlases, sine/periodic lookup tables with bitwise-mask indexing, and decomposing cost before optimizing.
Building a headless or containerized worker that drives the Claude Agent SDK (@anthropic-ai/claude-agent-sdk, the TypeScript/npm SDK that wraps the Claude Code CLI, not the `claude` CLI directly). Use when a query() session hangs and never finishes, when running Claude Code unattended with no human to answer a tool-permission prompt, when streaming input into a live session for mid-run steering, when the SDK's systemPrompt / SDKUserMessage / hook shapes do not match what you wrote, or when building a one-shot vs long-lived agent worker. Covers the streaming-input session that never ends (break on the result message), permissionMode bypassPermissions, the preset-append systemPrompt, SDKUserMessage.parent_tool_use_id, query()/interrupt() teardown, PreToolUse/PostToolUse hook fields, subscription-token billing, and version drift.
Generate unit tests for an interface or service by delegating to implementation-blind sub-agents that derive black-box tests from the documented contract, with a clarifying-question and assumption-ledger loop that resolves spec ambiguity instead of guessing. Use when writing or expanding unit tests for C#/.NET interfaces, services, or DI seams (xUnit), when you want tests that do not share assumptions with the implementation, or when adding a test suite after introducing interfaces. Covers the sub-agent briefing, the question/answer loop, integration (build, run, serialize global-state tests for xUnit parallelism), and the common failure modes of LLM-written tests (tautological, vacuous, hallucinated APIs).
House standard for writing C# XML documentation comments (/// triple-slash doc comments) to Microsoft's conventions. Use when writing, reviewing, or tightening <summary>, <remarks>, <param>, <returns>, <typeparam>, or <exception> tags on C# types and members, or when doc comments feel too verbose. Covers what belongs in summary vs remarks, when to use each tag, and the project rule that summaries stay short.
Write and organize technical documentation with the Diátaxis framework: the four modes (tutorial, how-to guide, reference, explanation), the compass for classifying content, the deep/functional quality model, and the iterative improvement workflow. Use when writing or restructuring docs, READMEs, guides, API/reference pages, or architecture/explanation write-ups; when a page feels tangled or mixes teaching with lookup; when deciding what kind of page something should be; or when auditing and splitting an existing documentation set into a navigable structure.
Capture the durable learnings from a work session and route each one into the right Agent Skill instead of a dump file: augment an existing skill or create a new one, global-and-reusable vs repo-local, written to skill-authoring best practices. Use at the end of a substantive session, or when asked to "capture learnings", "store what we did in skills", "disseminate knowledge", "wrap up", or after solving something non-obvious worth reusing. Covers what is worth keeping, classifying by scope and type, finding the existing home before creating, writing concrete trigger-first skills, the global-vs-committed reference conventions, and avoiding the monolithic learnings file trap.