From 1c726750b4f255369b8630a3ad8446a1cc16c2d2 Mon Sep 17 00:00:00 2001
From: zzstoatzz <thrast36@gmail.com>
Date: Wed, 22 Apr 2026 14:36:59 -0500
Subject: [PATCH] feat(slackbot): add research skill for behavior triage

---
 .../skills/prefect-behavior-triage/SKILL.md   | 40 +++++++++++++++++++
 .../slackbot/src/slackbot/research_agent.py   | 14 +++++--
 2 files changed, 50 insertions(+), 4 deletions(-)
 create mode 100644 examples/slackbot/.claude/skills/prefect-behavior-triage/SKILL.md

diff --git a/examples/slackbot/.claude/skills/prefect-behavior-triage/SKILL.md b/examples/slackbot/.claude/skills/prefect-behavior-triage/SKILL.md
new file mode 100644
index 000000000..d7b75a700
--- /dev/null
+++ b/examples/slackbot/.claude/skills/prefect-behavior-triage/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: prefect-behavior-triage
+description: Use when a Prefect question hinges on whether observed behavior is expected, a documentation gap, or a real bug. Inspect docs and source first, then build and run a minimal reproduction only when needed.
+---
+
+# Prefect Behavior Triage
+
+Use this skill when a user reports surprising Prefect behavior or asks whether something is a bug.
+
+## Workflow
+
+1. Read the relevant docs and implementation before making claims.
+2. If docs and source code already answer the question, do not reproduce unnecessarily.
+3. If runtime behavior still matters, create the smallest possible reproduction and run it.
+4. Compare four things explicitly:
+   - what the user observed
+   - what the docs say
+   - what the source code does
+   - what the reproduction actually did
+5. End with a clear classification:
+   - expected behavior
+   - docs unclear or outdated
+   - likely bug
+   - still inconclusive
+
+## Reproduction Rules
+
+- Prefer tiny standalone scripts over modifying existing project files.
+- Write repros under `.research_cache/repros/` and reuse them if they already fit.
+- Keep the repro focused on one claim or edge case.
+- Use `uv run python <script>` or `uv run python - <<'PY'` for quick checks.
+- If the question involves the Prefect API, use the real client or real flow/task execution rather than simulating behavior.
+- If the behavior depends on configuration, log the exact assumptions in the final answer.
+
+## Reporting Rules
+
+- Do not call something a bug unless docs, source, and observed behavior are materially misaligned.
+- If docs and source agree, treat that as intended behavior even if it is surprising.
+- If source and runtime agree but docs do not, call out the documentation mismatch separately.
+- Cite the specific files or commands you used to reach the conclusion.
diff --git a/examples/slackbot/src/slackbot/research_agent.py b/examples/slackbot/src/slackbot/research_agent.py
index 6f710766e..63d257804 100644
--- a/examples/slackbot/src/slackbot/research_agent.py
+++ b/examples/slackbot/src/slackbot/research_agent.py
@@ -12,6 +12,9 @@
 from prefect import task
 from prefect.cache_policies import INPUTS
 
+SLACKBOT_ROOT = Path(__file__).resolve().parents[2]
+REPO_ROOT = Path(__file__).resolve().parents[4]
+
 
 async def research_topic_with_code_access(question: str, version: str = "3.x") -> str:
     """
@@ -30,7 +33,7 @@ async def research_topic_with_code_access(question: str, version: str = "3.x") -
     # Use current working directory for cache
     # Locally: <wherever you run from>/.research_cache/prefect
     # Docker: /app/.research_cache/prefect (since WORKDIR is /app)
-    cache_dir = Path.cwd() / ".research_cache"
+    cache_dir = SLACKBOT_ROOT / ".research_cache"
     prefect_repo = cache_dir / "prefect"
 
     version_context = "Prefect 3.x" if version.startswith("3") else "Prefect 2.x"
@@ -71,12 +74,15 @@ async def research_topic_with_code_access(question: str, version: str = "3.x") -
 
 Remember: You are the research specialist. The main agent relies on you for accurate, comprehensive information.
 Be thorough - use tools repeatedly until you have complete information.
-Do not use any Prefect syntax you have not verified by reading the actual source code."""
+Do not use any Prefect syntax you have not verified by reading the actual source code.
+Use relevant Claude Code skills when they match the task, especially for behavior-vs-bug reproduction."""
 
     options = ClaudeAgentOptions(
-        allowed_tools=["Read", "Grep", "Glob", "Bash"],
-        cwd=str(Path.cwd()),
+        allowed_tools=["Skill", "Read", "Grep", "Glob", "Bash"],
+        cwd=str(SLACKBOT_ROOT),
+        add_dirs=[str(REPO_ROOT)],
         model="claude-haiku-4-5-20251001",
+        setting_sources=["project"],
         system_prompt=system_prompt,
     )