Add Contextual Prompts pattern

documents/patterns/contextual-prompts.md

@@ -0,0 +1,21 @@
+---
+authors: [ivett_ordog]
+---
+
+# Contextual Prompts
+
+## Problem
+
+Projects inevitably have small gotchas that both people and agents run into frequently. It's tempting to front-load these as instructions in CLAUDE.md, but that creates bloat. The more you add, the less reliable any single instruction becomes.
+
+## Pattern
+
+Instead of documenting gotchas upfront, embed the guidance directly in script outputs - error messages, success messages, CLI responses. Put reminders where they'll naturally be seen at the moment they're relevant.
+
+This is what we've always done for humans: good error messages guide you to the solution. It works equally well for AI agents.
+
+## Example
+
+**Database migration gotcha**: Instead of adding "Always run migrations in production before deploying" to CLAUDE.md, make the deploy script check for pending migrations and output: "Pending migrations detected. Run `./migrate.sh production` before deploying."
+
+**Environment-specific script**: A user permissions script only works in production. Both human and agent kept hitting obscure errors when running locally. The fix: check the environment variable and respond with "This script should only be run on the production server" - saving debugging time for everyone.

documents/patterns/yak-shave-delegation.md

@@ -0,0 +1,27 @@
+---
+authors: [ivett_ordog]
+---
+
+# 🐃 Yak Shave Delegation
+
+## Problem
+
+Yak shaving breaks flow and context for both you and your primary agent. Environment issues derail focus even though they're often trivial to fix.
+
+## Pattern
+
+When a tangential issue blocks your main work, spawn a separate agent to handle it instead of switching context yourself.
+
+1. Hit an environment/tooling issue (compiler error, missing dependency, config problem)
+2. Recognize it's yak shaving - not your core task
+3. Spawn a separate agent to handle it (error messages usually contain the fix instructions)
+4. Continue your main work with your primary agent
+5. Check back when the yak-shave agent signals it's done
+
+This keeps both you and your main agent focused on the core problem while the yak shave gets resolved in parallel.
+
+## Example
+
+Returning to a project after some time, the codebase has moved on. Running the app fails - needs a new Ruby runtime, recompiled libraries, and config changes.
+
+Instead of context-switching to fix these, spawn an agent with the error output. The agent installs Ruby, recompiles dependencies, and updates config while you and your primary agent continue exploring the codebase and planning the next feature.

documents/relationships.mmd

@@ -75,13 +75,20 @@ graph LR
   patterns/approved-logs -->|uses| patterns/constrained-tests
   patterns/habit-hooks -->|uses| patterns/hooks
   patterns/habit-hooks -->|uses| patterns/feedback-loop
+  patterns/habit-hooks -->|uses| patterns/contextual-prompts
+  patterns/contextual-prompts -->|solves| obstacles/context-rot
+  patterns/contextual-prompts -->|solves| obstacles/selective-hearing
+  patterns/contextual-prompts <-->|similar| patterns/reminders
   patterns/feedback-loop <-->|similar| patterns/playgrounds
   patterns/feedback-loop <-->|similar| patterns/chain-of-small-steps
   patterns/chain-of-small-steps <-->|similar| patterns/offload-deterministic
   patterns/happy-to-delete <-->|similar| patterns/parallel-implementations
   patterns/happy-to-delete <-->|similar| patterns/playgrounds
   patterns/approved-fixtures <-->|similar| patterns/check-alignment
   patterns/approved-fixtures <-->|similar| patterns/approved-logs
+  patterns/yak-shave-delegation -->|uses| patterns/background-agent
+  patterns/yak-shave-delegation -->|uses| patterns/focused-agent
+  patterns/yak-shave-delegation -->|solves| anti-patterns/distracted-agent
 
   %% Anti-pattern → Obstacle relationships (causes)
   anti-patterns/distracted-agent -->|causes| obstacles/limited-focus