From d7febbd5864e2425309bc2fb9a03edf9ac9bcfbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivett=20=C3=96rd=C3=B6g?= Date: Sat, 24 Jan 2026 11:55:40 +0100 Subject: [PATCH 1/2] Add Yak Shave Delegation pattern Co-Authored-By: Claude Opus 4.5 --- documents/patterns/yak-shave-delegation.md | 27 ++++++++++++++++++++++ documents/relationships.mmd | 3 +++ 2 files changed, 30 insertions(+) create mode 100644 documents/patterns/yak-shave-delegation.md diff --git a/documents/patterns/yak-shave-delegation.md b/documents/patterns/yak-shave-delegation.md new file mode 100644 index 0000000..846c79c --- /dev/null +++ b/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. diff --git a/documents/relationships.mmd b/documents/relationships.mmd index 919ccd9..985108b 100644 --- a/documents/relationships.mmd +++ b/documents/relationships.mmd @@ -82,6 +82,9 @@ graph LR 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 From cf6091b1862a2df707211f3d6c012d95369f944c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivett=20=C3=96rd=C3=B6g?= Date: Sat, 24 Jan 2026 13:05:53 +0100 Subject: [PATCH 2/2] Add Contextual Prompts pattern Co-Authored-By: Claude Opus 4.5 --- documents/patterns/contextual-prompts.md | 21 +++++++++++++++++++++ documents/relationships.mmd | 4 ++++ 2 files changed, 25 insertions(+) create mode 100644 documents/patterns/contextual-prompts.md diff --git a/documents/patterns/contextual-prompts.md b/documents/patterns/contextual-prompts.md new file mode 100644 index 0000000..3acc040 --- /dev/null +++ b/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. diff --git a/documents/relationships.mmd b/documents/relationships.mmd index 985108b..a12a97e 100644 --- a/documents/relationships.mmd +++ b/documents/relationships.mmd @@ -75,6 +75,10 @@ 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