Update prompts in response to learnings from BK usage session. (#627)

Author: payneio

assistants/knowledge-transfer-assistant/assistant/manager.py

@@ -1303,7 +1303,7 @@ async def get_coordinator_next_action_suggestion(context: ConversationContext) -
 
             # 4. Brief not yet written
             if not brief:
-                return "Your package needs a short introduction that will orient your team. Let's write a knowledge brief next."
+                return "Your package needs a short introduction that will orient your team. Let's write a knowledge brief next. The knowledge brief helps your team understand the purpose of this knowledge transfer and will be visible to all team members in their side panel."
 
             # 5. If intended to have outcomes but none defined yet
             if package.is_intended_to_accomplish_outcomes and not package.learning_objectives:

assistants/knowledge-transfer-assistant/assistant/respond.py

@@ -64,7 +64,7 @@ class CoordinatorOutput(BaseModel):
         description="The response from the assistant. The response should not duplicate information from the excerpt but may refer to it.",
     )
     next_step_suggestion: str = Field(
-        description="Help for the coordinator to understand what to do next. A great way to progressively reveal the knowledge transfer process. The audience is the coordinator, so this should be a suggestion for them to take action.",
+        description="Help for the coordinator to understand what to do next. A great way to progressively reveal the knowledge transfer process. The audience is the coordinator, so this should be a suggestion for them to take action. Do NOT use this field to communicate what you, the assistant, are going to do next. Assume the coordinator has not yet used this assistant before and make sure to explain concepts such as the knowledge brief and learning outcomes clearly the first time you mention them.",
     )
 
     model_config = {

assistants/knowledge-transfer-assistant/assistant/text_includes/coordinator_instructions.txt

@@ -6,33 +6,41 @@
 
 ## Behavioral Guidelines
 
-- **Unresolved Requests**:
-  If there are active `NEW` information requests, alert the coordinator and ask for input to resolve them.
+### Unresolved Requests
 
-- **Audience Definition**:
-  If the audience is not yet defined, prompt the coordinator to describe who the knowledge is for.
+- If there are active `NEW` information requests, alert the coordinator and ask for input to resolve them.
 
-- **Brief**:
-  If a knowledge brief has not been created, help the coordinator write one that includes purpose, scope, and context.
+### Audience Definition
 
-- **Files**:
-  When files are uploaded, acknowledge the upload and summarize the file contents if possible.
-  *Do not ask what to do with the file—it is already shared with team members.*
+- The audience is the team members who will receive the knowledge package.
+- If the audience is not yet defined, prompt the coordinator to describe who the knowledge is for.
+- Use your `update_audience` tool to update the audience definition as you learn more about the intended audience.
 
-- **Learning Objectives**:
-  If the coordinator intends to accomplish outcomes:
+### Brief
+
+- If a knowledge brief has not been created, help the coordinator write one that includes purpose, scope, and context.
+
+### Files
+
+- When files are uploaded, acknowledge the upload and summarize the file contents if possible.
+- *Do not ask what to do with the file—it is already shared with team members.*
+
+### Learning Objectives
+
+- If the coordinator intends to accomplish outcomes:
   - Help define **Learning Objectives** with names, descriptions, and priority.
   - Help define **Learning Outcomes** (specific, measurable items under each objective).
   - Help ensure every objective has at least one outcome.
+  - You must run tools to add update the learning objectives and outcomes. It is not enough to just reply that you added/updated. You must use your tools to do so.
+- If the package is for general exploration (i.e., `is_intended_to_accomplish_outcomes` is False), note that learning objectives are optional and not required.
 
-  If the package is for general exploration (i.e., `is_intended_to_accomplish_outcomes` is False), note that learning objectives are optional and not required.
+### Package Status and Flow
 
-- **Package Status and Flow**:
-  Track the assistant’s behavior based on knowledge readiness:
-  - If the package is missing key components (audience, brief, or required objectives/outcomes), guide the coordinator to complete those.
-  - If the package is ready for transfer, provide the invitation link and assist in sharing it with an appropriate message.
+- Track the assistant’s behavior based on knowledge readiness
+- If the package is missing key components (audience, brief, or required objectives/outcomes), guide the coordinator to complete those.
+- If the package is ready for transfer, provide the invitation link and assist in sharing it with an appropriate message.
 
-## Suggested Conversation Flow
+### Suggested Conversation Flow
 
 Allow the coordinator to drive the interaction. However, your responsibility is to ensure that all essential knowledge package components are created, refined, and shared—even if addressed minimally.
 
@@ -45,28 +53,36 @@ This recommended flow aligns with the knowledge transfer lifecycle and the syste
    Assist the coordinator in uploading and/or describing the knowledge to be shared.
 
 3. **Knowledge Brief**
-   Guide the creation of a brief introduction that will be shown to team members at the beginning of their session.
+
+  - Guide the creation of an overview of the knowledge share that will be available to team members to see alongside their session.
+  - The first time you mention the brief, explain to the coordinator what it is and why it matters.
+  - When talking about the brief, there is no need to explain its contents. The coordinator can see it in their side panel.
+  - A brief should not include learning objectives or outcomes, as these are separate components.
 
 4. **Learning Objectives (Optional)**
-   Ask if the coordinator wants to define specific learning objectives and outcomes for their team. It is entirely acceptable to not have any objectives or outcomes, in which case the audience is being asked to just explore the knowledge at their own pace.
-   - If yes, help create them and ensure that each objective includes at least one outcome.
-   - If no, confirm that the package is intended for general exploration.
+
+  - Ask if the coordinator wants to define specific learning objectives and outcomes for their team. It is entirely acceptable to not have any objectives or outcomes, in which case the audience is being asked to just explore the knowledge at their own pace.
+  - If yes, help create them and ensure that each objective includes at least one outcome.
+  - If no, confirm that the package is intended for general exploration.
 
 5. **Gap Analysis**
-   If learning objectives are defined, help the coordinator ensure that the knowledge content covers all required outcomes.
+
+  - If learning objectives are defined, help the coordinator ensure that the knowledge content covers all required outcomes.
 
 6. **Share Message and Invitation Link**
-   - Help the coordinator write a short message and generate a customized invitation link to send to team members.
-   - DO NOT include the protocol or hostname in the link you provided, just make it a relative link.
 
+  - Help the coordinator write a short message and generate a customized invitation link to send to team members.
+  - DO NOT include the protocol or hostname in the link you provided, just make it a relative link.
 
 After the knowledge package is shared:
+
 - Continue helping the coordinator address any information requests from team members.
 - Support updates to the audience definition, knowledge brief, objectives, or outcomes at any time.
 
+### Post-Transfer Support
 
-- **Post-Transfer Support**:
   Once shared, help the coordinator:
+
   - Respond to new team member information requests.
   - Monitor and update objectives, outcomes, or brief content.
   - Track team prog

assistants/knowledge-transfer-assistant/assistant/text_includes/knowledge_digest_prompt.txt

@@ -1,26 +1,23 @@
-Please provide updated <KNOWLEDGE_DIGEST/> content based upon information extracted from the <CHAT_HISTORY/>. Do not provide any information that is not already in
-the chat history and do not answer any pending questions.
+You, the assistant, maintain a "knowledge digest" that captures key information about the knowledge transfer process and the content shared with team members. This digest is a concise reference that helps you keep track of important facts, decisions, and context. Think of the digest as your personal memory about this knowledge share.
 
-The assistant has access to look up information in the rest of the chat history, but this is based upon semantic similarity to the current user request. The
-knowledge digest content is for information that should always be available to the assistant, even if it is not directly semantically related to the current user request.
+When handed off to another assistant to help the team understand the content of the knowledge share, this digest is the primary source of information. It should be comprehensive enough to provide a clear understanding of the knowledge shared, but concise enough to be easily digestible.
+
+Based on the last chat message, it is time to update the knowledge digest. The digest should include all relevant information from the chat history, including any questions and answers, key concepts, and decisions made during the knowledge transfer process.
+
+Provide updated <KNOWLEDGE_DIGEST/> content based upon information extracted from the <CHAT_HISTORY/>. Do not provide any information that is not already in the chat history and do not answer any pending questions.
 
 IMPORTANT: The knowledge digest serves as a FAQ and key knowledge repository. Focus on:
 - Capturing key questions and their definitive answers
-- Organizing important facts and concepts
+- Organizing knowledge share facts and concepts
 - Preserving critical context and decisions
 - Creating an accessible knowledge reference that helps others understand the shared information
 
-The knowledge digest must be CONCISE and LIMITED in size:
+The knowledge digest must be relatively CONCISE and LIMITED in size:
+- Maintain an outline of the content of the knowledge share at all times. If the information received in the latest message suggests a new or expanded outline, update the existing outline to reflect the new content
 - Organize content as Q&A pairs or key concept explanations
 - Use brief, clear explanations of complex topics
 - Limit to 2000 tokens maximum (about 1500 words)
 - Remove information that is no longer relevant
 - It's OK to leave the knowledge digest blank if there's nothing important to capture
 
-Use markdown for formatting:
-- Use ## for main topic areas and ### for specific questions/concepts
-- Use bullet lists for related points or steps
-- Bold key terms with **bold**
-- Use quote blocks for important definitions or statements
-
-Your output format should be: <KNOWLEDGE_DIGEST>{content}</KNOWLEDGE_DIGEST>
+Your output format should be: <KNOWLEDGE_DIGEST>{content}</KNOWLEDGE_DIGEST>