ask-for-help

Ask for Help

Use the halyard MCP tools to get human input when you're blocked, need clarification, or face decisions that require human judgment. ALWAYS summarize helpful answers to build a knowledge base.

Before Asking: Check the Knowledge Base

Before routing to a human, search for existing answers. Experts get frustrated when asked questions that were already answered in a previous session, and work summaries from past sessions are searchable too.

mcp__plugin_halyard_ask-expert__search_knowledge(
  query: "describe your question topic"
)

If the search returns a relevant answer, use it directly and skip the expert workflow. If not, proceed to the workflow below.

Complete Workflow

Every interaction should follow this pattern:

0. mcp__plugin_halyard_ask-expert__search_knowledge(...)   → Check if this was already answered
1. mcp__plugin_halyard_ask-expert__list_team()             → Find the right expert
2. mcp__plugin_halyard_ask-expert__ask_expert(...)         → Send your question (returns immediately)
3. mcp__plugin_halyard_ask-expert__check_response(...)     → REQUIRED: Wait for the response
4. mcp__plugin_halyard_ask-expert__summarize_conversation  → CRITICAL: Capture what you learned
   OR mcp__plugin_halyard_ask-expert__close_conversation   → (with summary parameter)

Steps 3 and 4 are critical—mcp__plugin_halyard_ask-expert__ask_expert returns immediately after notifying the expert, so you MUST call mcp__plugin_halyard_ask-expert__check_response to get their reply. Without summarization, the knowledge is lost and experts get asked the same questions repeatedly.

When to Ask for Help

Ask for help when:

• Ambiguous requirements — The task description is unclear or could be interpreted multiple ways
• Design decisions — Multiple valid approaches exist and you need guidance on which to choose
• Domain expertise needed — The task requires knowledge you don't have (e.g., business logic, design preferences)
• Blocked by external factors — You need credentials, access, or information only a human can provide
• Verification needed — You want to confirm an approach before investing significant effort

Do not ask for help when:

• You can find the answer by reading code or documentation
• The task is straightforward and well-defined
• You're just uncertain—try first, then ask if truly stuck

Available Tools

1. Search Knowledge Base (check this first)

Semantic search across past expert Q&A and work summaries from previous sessions. Always try this before asking an expert — the answer may already exist.

mcp__plugin_halyard_ask-expert__search_knowledge(
  query: "how do we handle authentication?"
)

Parameters:

Parameter	Description
query	Natural language search query (required)
type	Filter by type: "WORK_OUTPUT", "DECISION", "PROCESS", "CONTEXT"
author	Filter by author — use "me" for your own entries
since	Time filter: "today", "yesterday", "this week", "7d", "30d", or an ISO date
limit	Max results to return

Use this to:

• Find answers to questions that were already asked — avoid repeating questions experts have already answered
• Look up work done in previous sessions — summaries logged via mcp__plugin_halyard_ask-expert__summarize_work are searchable here
• Discover past decisions and context — understand why something was built a certain way

2. List the Team

Before asking, check who's available:

mcp__plugin_halyard_ask-expert__list_team()
mcp__plugin_halyard_ask-expert__list_team(role: "designer")
mcp__plugin_halyard_ask-expert__list_team(skill: "security")
mcp__plugin_halyard_ask-expert__list_team(available_only: true)
mcp__plugin_halyard_ask-expert__list_team(query: "who knows about deployment?")

3. Ask an Expert

Send a question to an expert by role or skill:

mcp__plugin_halyard_ask-expert__ask_expert(
  prompt: "Your question here",
  role: "designer"  // or use skill: "ui-design"
)

Parameters:

Parameter	Description
prompt	The question or request (required)
role	Expert role: "designer", "architect", "pm", "engineer"
skill	Expert skill: "ui-design", "security", "database", "typescript"
options	Optional array of choices for the expert to pick from
force_human	If true, skip knowledge base auto-resolution and always route to a human

With options (when you want a specific choice):

mcp__plugin_halyard_ask-expert__ask_expert(
  prompt: "Should we use server-side or client-side validation for this form?",
  role: "architect",
  options: [
    { label: "Server-side only", value: "server" },
    { label: "Client-side only", value: "client" },
    { label: "Both", value: "both" }
  ]
)

4. Check for Response (Required)

mcp__plugin_halyard_ask-expert__ask_expert returns immediately after notifying the expert. You MUST call mcp__plugin_halyard_ask-expert__check_response to wait for their reply:

mcp__plugin_halyard_ask-expert__check_response(
  conversation_id: "conversation-id-from-ask-expert",
  wait: true  // Wait up to 55 seconds for response
)

If no response yet, call again to continue waiting.

4b. Get Full Conversation History

Retrieve the complete message history for a conversation:

mcp__plugin_halyard_ask-expert__get_conversation(
  conversation_id: "conversation-id"
)

4c. Reply to Expert

Send a follow-up message in an existing conversation to ask clarifying questions or provide additional context:

mcp__plugin_halyard_ask-expert__reply_to_expert(
  conversation_id: "conversation-id",
  message: "Thanks — one follow-up: should we also handle token revocation?"
)

5. Summarize What You Learned (CRITICAL)

Always call this after receiving a helpful response. This builds organizational knowledge so experts don't get asked the same questions repeatedly.

mcp__plugin_halyard_ask-expert__summarize_conversation(
  conversation_id: "conversation-id",
  question: "Should we use JWT or session auth for the mobile app? Our existing mobile SDK expects Bearer tokens.",
  answer: "Use JWT with refresh tokens because mobile clients need stateless auth and we already have JWT infrastructure in the API."
)

Parameters:

Parameter	Description
conversation_id	The conversation ID from ask_expert (required)
question	The question or context that was asked (required)
answer	The answer, decision, or guidance from the expert (required)
source_provider	Source system: "github", "slack", "linear", "claude", "codex", "notion"
source_url	Link to the source context (e.g., the PR that prompted this question)

Write effective summaries:

• question: Write it so someone with a similar question would recognize it as relevant
• answer: Include key reasoning and context that makes the answer useful

6. View User Profile

View a user's expertise areas and activity, or your own:

mcp__plugin_halyard_ask-expert__get_user_profile()
mcp__plugin_halyard_ask-expert__get_user_profile(user_id: "user-id")
mcp__plugin_halyard_ask-expert__get_user_profile(since: "this week")

Without since, shows accumulated expertise. With since, shows time-scoped activity.

7. Close Conversation (Without Summary)

Close a conversation without capturing knowledge (not recommended):

mcp__plugin_halyard_ask-expert__close_conversation(
  conversation_id: "conversation-id"
)

Note: Prefer using mcp__plugin_halyard_ask-expert__summarize_conversation instead, which both captures knowledge and closes the conversation.

Writing Good Questions

Be specific and provide context:

# Bad
"How should I do authentication?"

# Good
"We're adding user authentication to the API. The app uses Fastify
and Prisma. Should we use JWT tokens with refresh tokens, or
session-based auth with cookies? The app will have both web and
mobile clients."

Include what you've already considered:

"I need to add file upload to the form. I'm considering:
1. Direct upload to S3 with presigned URLs
2. Upload through our API server

The files are user avatars (small images). Which approach
fits our architecture better?"

State the decision you need:

"The sidebar component can either use CSS transitions or
Framer Motion for animations. Our existing components use
both patterns. Which should I use for consistency?"

Complete Workflow Example

// 1. Find an expert
mcp__plugin_halyard_ask-expert__list_team(skill: "ui-design")

// 2. Ask your question (returns immediately)
mcp__plugin_halyard_ask-expert__ask_expert(
  prompt: "The design shows cards with hover states. Should I use
           CSS transitions or Framer Motion? We use both in the codebase.",
  skill: "ui-design"
)
// Returns immediately: { status: "pending", conversation_id: "conv_abc123" }

// 3. Wait for response (REQUIRED - ask_expert doesn't wait)
mcp__plugin_halyard_ask-expert__check_response(
  conversation_id: "conv_abc123",
  wait: true
)
// Expert responds: "Use CSS transitions for simple hover states.
//    Framer Motion is for complex animations like page transitions."

// 4. ALWAYS summarize the knowledge gained
mcp__plugin_halyard_ask-expert__summarize_conversation(
  conversation_id: "conv_abc123",
  question: "CSS transitions vs Framer Motion for card hover states?",
  answer: "Use CSS transitions for simple hover effects. Framer Motion should be reserved for complex animations like page transitions and multi-step sequences. Guideline: Simple state changes = CSS, complex/sequenced animations = Framer Motion."
)

Tips

• Search first — Use mcp__plugin_halyard_ask-expert__search_knowledge before asking an expert; answers from past conversations and work summaries from previous sessions are all searchable
• Be patient — Experts are notified via Slack and may not respond immediately
• Continue other work — While waiting, work on unblocked tasks
• One question at a time — Keep questions focused; ask follow-ups separately
• Provide options when possible — Makes it easier for experts to respond quickly
• ALWAYS summarize — This is the most important step for building organizational knowledge