# Safe Output Messages Design System This document catalogs all messages, footers, and UI patterns used across GitHub Agentic Workflows safe output functions. ## Overview Safe output functions handle GitHub API write operations (creating issues, discussions, comments, PRs, etc.) from AI-generated content. They produce consistent, user-facing messages with: - AI attribution footers - Workflow installation instructions - Related items references - Staged mode preview messages - Error and warning messages ### Safe Output Message Flow The following diagram illustrates how AI-generated content flows through the safe output system to GitHub API operations: ```mermaid graph TD A[AI Agent Output] --> B{Staged Mode?} B -->|Yes| C[Generate Preview Messages] B -->|No| D[Process Safe Output] C --> E[Show 🎭 Staged Mode Preview] E --> F[Display in Step Summary] D --> G{Safe Output Type} G -->|create-issue| H[Create GitHub Issue] G -->|create-discussion| I[Create GitHub Discussion] G -->|add-comment| J[Add GitHub Comment] G -->|create-pull-request| K[Create Pull Request] G -->|create-pr-review-comment| L[Create PR Review Comment] G -->|update-issue| M[Update GitHub Issue] H --> N[Apply Message Patterns] I --> N J --> N K --> N L --> N M --> N N --> O[Add AI Attribution Footer] N --> P[Add Installation Instructions] N --> Q[Add Related Items Links] N --> R[Add Patch Preview] O --> S[Execute GitHub API Operation] P --> S Q --> S R --> S S --> T[Generate Success Summary] T --> U[Display in Step Summary] ``` **Flow Stages:** 1. **AI Agent Output** - AI generates content for GitHub operations 2. **Staged Mode Check** - Determines if operation is in preview mode 3. **Safe Output Processing** - Routes to appropriate GitHub operation type 4. **Message Pattern Application** - Applies consistent formatting (footers, instructions, links) 5. **GitHub API Execution** - Performs the actual GitHub operation 6. **Success Summary** - Reports results in workflow step summary ## Message Categories ### 1. AI Attribution Footer **Purpose**: Identifies content as AI-generated and links to the workflow run. **Pattern**: Blockquote with workflow link and optional triggering context. #### Basic Footer Format **Markdown Source:** ```markdown > AI generated by [WorkflowName](run_url) ``` **Rendered Output:** > AI generated by [WorkflowName](https://github.com/example/repo/actions/runs/12345) #### Footer with Triggering Context **Markdown Source:** ```markdown > AI generated by [WorkflowName](run_url) for #123 ``` **Rendered Output:** > AI generated by [Issue Analyzer](https://github.com/example/repo/actions/runs/12345) for #123 **Context Variations:** - `for #N` - When triggered by an issue or pull request - `for discussion #N` - When triggered by a discussion ### 2. Workflow Installation Instructions **Purpose**: Provides command to add the workflow to user's repository. **Pattern**: Multi-line blockquote with CLI command and documentation link. **Markdown Source:** ```markdown > > To add this workflow in your repository, run `gh aw add owner/repo/path@ref`. See [usage guide](https://github.github.com/gh-aw/setup/cli/). ``` **Rendered Output:** > > To add this workflow in your repository, run `gh aw add github/gh-aw/.github/workflows/example@main`. See [usage guide](https://github.github.com/gh-aw/setup/cli/). **When shown**: Appears when workflow has a known source location. ### 3. Related Items References **Purpose**: Links AI-generated comments to related issues, discussions, or pull requests created in the same workflow. **Pattern**: Markdown heading with bulleted list of links. **Markdown Source:** ```markdown #### Related Items - Issue: [#123](issue_url) - Discussion: [#456](discussion_url) - Pull Request: [#789](pr_url) ``` **Rendered Output:** #### Related Items - Issue: [#123](https://github.com/example/repo/issues/123) - Discussion: [#456](https://github.com/example/repo/discussions/456) - Pull Request: [#789](https://github.com/example/repo/pull/789) **When shown**: Added to comments when the workflow creates multiple related items. ### 4. Staged Mode Preview Messages **Purpose**: Show preview of safe output operations without executing them, for testing and validation. **Pattern**: Step summary with 🎭 emoji header and detailed preview content. #### Preview Header Pattern All staged mode previews use this consistent format: **Markdown Source:** ```markdown ## 🎭 Staged Mode: [Operation Type] Preview The following [items] would be [action] if staged mode was disabled: ``` **Rendered Output:** ## 🎭 Staged Mode: Create Issues Preview The following issues would be created if staged mode was disabled: #### Create Issues Preview **Markdown Source:** ```markdown ## 🎭 Staged Mode: Create Issues Preview The following issues would be created if staged mode was disabled: ### Issue 1 **Title:** Issue title here **Body:** Issue body content here **Labels:** label1, label2 --- ``` **Rendered Output:** ## 🎭 Staged Mode: Create Issues Preview The following issues would be created if staged mode was disabled: ### Issue 1 **Title:** Bug in user authentication flow **Body:** The login page is not handling incorrect credentials properly. Users are seeing a generic error message instead of specific feedback. **Labels:** bug, authentication --- #### Create Discussions Preview **Markdown Source:** ```markdown ## 🎭 Staged Mode: Create Discussions Preview The following discussions would be created if staged mode was disabled: ### Discussion 1 **Title:** Discussion title here **Body:** Discussion body content here **Category:** category-name --- ``` **Rendered Output:** ## 🎭 Staged Mode: Create Discussions Preview The following discussions would be created if staged mode was disabled: ### Discussion 1 **Title:** Weekly Research Summary - January 2024 **Body:** This week we explored advances in AI code generation, focusing on the latest developments in context-aware suggestions and multi-file editing capabilities. **Category:** announcements --- #### Add Comments Preview **Markdown Source:** ```markdown ## 🎭 Staged Mode: Add Comments Preview The following comments would be added if staged mode was disabled: #### Related Items - Issue: [#123](url) - Discussion: [#456](url) - Pull Request: [#789](url) ### Comment 1 **Target Issue:** [#123](url) **Body:** Comment body content here --- ``` **Rendered Output:** ## 🎭 Staged Mode: Add Comments Preview The following comments would be added if staged mode was disabled: #### Related Items - Issue: [#123](https://github.com/example/repo/issues/123) - Pull Request: [#789](https://github.com/example/repo/pull/789) ### Comment 1 **Target Issue:** [#123](https://github.com/example/repo/issues/123) **Body:** Thank you for reporting this issue. We've identified the root cause and will include a fix in the next release. --- #### Create Pull Request Preview **Markdown Source:** ```markdown ## 🎭 Staged Mode: Create Pull Request Preview The following pull request would be created if staged mode was disabled: **Title:** PR title here **Branch:** branch-name **Base:** main **Body:** PR body content here **Changes:** Patch file exists with 123 lines

Show patch preview

\`\`\`diff [patch content up to 2000 chars] ... (truncated) \`\`\`

``` **Rendered Output:** ## 🎭 Staged Mode: Create Pull Request Preview The following pull request would be created if staged mode was disabled: **Title:** Fix authentication error handling **Branch:** aw-fix-auth-error-a3d8f9 **Base:** main **Body:** Updated error handling in the login flow to provide specific feedback to users. **Changes:** Patch file exists with 45 lines

Show patch preview

```diff diff --git a/src/auth.js b/src/auth.js index 1234567..abcdefg 100644 --- a/src/auth.js +++ b/src/auth.js @@ -10,7 +10,10 @@ export async function login(username, password) { - throw new Error('Login failed'); + if (response.status === 401) { + throw new Error('Invalid credentials'); + } + throw new Error('Login error: ' + response.statusText); ```

#### Create PR Review Comments Preview **Markdown Source:** ```markdown ## 🎭 Staged Mode: Create PR Review Comments Preview The following review comments would be created if staged mode was disabled: ### Review Comment 1 **Target PR:** [#123](url) **File:** path/to/file.js **Line:** 42 **Start Line:** 40 **Side:** RIGHT **Body:** Review comment body here --- ``` **Rendered Output:** ## 🎭 Staged Mode: Create PR Review Comments Preview The following review comments would be created if staged mode was disabled: ### Review Comment 1 **Target PR:** [#123](https://github.com/example/repo/pull/123) **File:** src/auth.js **Line:** 42 **Start Line:** 40 **Side:** RIGHT **Body:** Consider adding a timeout to this network request to prevent hanging on slow connections. --- #### Update Issues Preview **Markdown Source:** ```markdown ## 🎭 Staged Mode: Update Issues Preview The following issue updates would be applied if staged mode was disabled: ### Issue Update 1 **Target Issue:** #123 **New Title:** Updated title **New Body:** Updated body content **New Status:** closed --- ``` **Rendered Output:** ## 🎭 Staged Mode: Update Issues Preview The following issue updates would be applied if staged mode was disabled: ### Issue Update 1 **Target Issue:** #123 **New Title:** [Fixed] Authentication error handling **New Body:** This issue has been resolved in PR #789. The fix will be included in the next release. **New Status:** closed --- ### 5. Patch Preview Messages **Purpose**: Display git patches in pull request bodies with size limits and truncation. **Pattern**: Collapsible details section with syntax-highlighted diff. #### Standard Patch Preview **Markdown Source:** ```markdown

Show patch (45 lines)

\`\`\`diff diff --git a/src/auth.js b/src/auth.js index 1234567..abcdefg 100644 --- a/src/auth.js +++ b/src/auth.js @@ -10,7 +10,10 @@ export async function login(username, password) { - throw new Error('Login failed'); + if (response.status === 401) { + throw new Error('Invalid credentials'); + } + throw new Error('Login error: ' + response.statusText); \`\`\`

``` **Rendered Output:**

Show patch (45 lines)

**Used when**: Patch is under 500 lines and 2000 characters #### Truncated Patch Preview **Markdown Source:** ```markdown

Show patch preview (500 of 1234 lines)

\`\`\`diff [first 500 lines of patch content] ... (truncated) \`\`\`

``` **Rendered Output:**

Show patch preview (500 of 1234 lines)

```diff diff --git a/src/auth.js b/src/auth.js index 1234567..abcdefg 100644 --- a/src/auth.js +++ b/src/auth.js [additional patch lines...] ... (truncated) ```

**Used when**: Patch exceeds 500 lines or 2000 characters **Limits**: - Max lines: 500 - Max characters: 2000 ### 6. Fallback Messages **Purpose**: Provide alternative actions when primary operations fail (e.g., PR creation fails). #### Push Failure Fallback **Markdown Source:** ```markdown --- > [!NOTE] > This was originally intended as a pull request, but the git push operation failed. > > **Workflow Run:** [View run details and download patch artifact](run_url) > > The patch file is available in the `agent-artifacts` artifact in the workflow run linked above. To apply the patch locally: \`\`\`sh # Download the artifact from the workflow run [url] # (Use GitHub MCP tools if gh CLI is not available) gh run download [run_id] -n agent-artifacts -D /tmp/agent-artifacts-[run_id] # Apply the patch git am /tmp/agent-artifacts-[run_id]/aw.patch \`\`\` [patch preview if available] ``` **Rendered Output:** --- > [!NOTE] > This was originally intended as a pull request, but the git push operation failed. > > **Workflow Run:** [View run details and download patch artifact](https://github.com/example/repo/actions/runs/12345) > > The patch file is available in the `agent-artifacts` artifact in the workflow run linked above. To apply the patch locally: ```sh # Download the artifact from the workflow run # (Use GitHub MCP tools if gh CLI is not available) gh run download 12345 -n agent-artifacts -D /tmp/agent-artifacts-12345 # Apply the patch git am /tmp/agent-artifacts-12345/aw.patch ```

Show patch (45 lines)

```diff diff --git a/src/auth.js b/src/auth.js [patch content...] ```

**When shown**: When git push fails but patch generation succeeded. #### PR Creation Fallback **Markdown Source:** ```markdown --- **Note:** This was originally intended as a pull request, but PR creation failed. The changes have been pushed to the branch [`branch-name`](branch_url). **Original error:** [error message] You can manually create a pull request from the branch if needed. [patch preview if available] ``` **Rendered Output:** --- **Note:** This was originally intended as a pull request, but PR creation failed. The changes have been pushed to the branch [`aw-fix-auth-error-a3d8f9`](https://github.com/example/repo/tree/aw-fix-auth-error-a3d8f9). **Original error:** Pull request validation failed: title is required You can manually create a pull request from the branch if needed.

Show patch (45 lines)

```diff diff --git a/src/auth.js b/src/auth.js [patch content...] ```

**When shown**: When PR creation fails but branch push succeeded. ### 7. Issue Parent References **Purpose**: Link created issues to their parent issue. **Pattern**: Simple markdown reference at end of issue body. **Markdown Source:** ```markdown Related to #123 ``` **Rendered Output:** Related to #123 **When shown**: When an issue is created as a sub-task of another issue. ### 8. Success Summary Messages **Purpose**: Provide step summary after successful operations. **Pattern**: Markdown heading with bulleted list of created items. #### GitHub Issues Summary **Markdown Source:** ```markdown ## GitHub Issues - Issue #123: [Issue Title](issue_url) - Issue #456: [Another Issue](issue_url) ``` **Rendered Output:** ## GitHub Issues - Issue #123: [Bug in user authentication flow](https://github.com/example/repo/issues/123) - Issue #456: [Add password reset feature](https://github.com/example/repo/issues/456) #### GitHub Discussions Summary **Markdown Source:** ```markdown ## GitHub Discussions - Discussion #123: [Discussion Title](discussion_url) - Discussion #456: [Another Discussion](discussion_url) ``` **Rendered Output:** ## GitHub Discussions - Discussion #123: [Weekly Research Summary - January 2024](https://github.com/example/repo/discussions/123) - Discussion #456: [Q1 Planning Meeting Notes](https://github.com/example/repo/discussions/456) #### GitHub Comments Summary **Markdown Source:** ```markdown ## GitHub Comments - Comment #12345: [View Comment](comment_url) - Comment #67890: [View Comment](comment_url) ``` **Rendered Output:** ## GitHub Comments - Comment #12345: [View Comment](https://github.com/example/repo/issues/123#issuecomment-12345) - Comment #67890: [View Comment](https://github.com/example/repo/pull/456#issuecomment-67890) #### GitHub PR Review Comments Summary **Markdown Source:** ```markdown ## GitHub PR Review Comments - Review Comment #12345: [View Comment](comment_url) - Review Comment #67890: [View Comment](comment_url) ``` **Rendered Output:** ## GitHub PR Review Comments - Review Comment #12345: [View Comment](https://github.com/example/repo/pull/123#discussion_r12345) - Review Comment #67890: [View Comment](https://github.com/example/repo/pull/456#discussion_r67890) #### Pull Request Summary **Markdown Source:** ```markdown ## Pull Request - **Pull Request**: [#123](pr_url) - **Branch**: `branch-name` - **Base Branch**: `main` ``` **Rendered Output:** ## Pull Request - **Pull Request**: [#123](https://github.com/example/repo/pull/123) - **Branch**: `aw-fix-auth-error-a3d8f9` - **Base Branch**: `main` #### Push Failure Fallback Summary **Markdown Source:** ```markdown ## Push Failure Fallback - **Push Error:** [error message] - **Fallback Issue:** [#123](issue_url) - **Patch Artifact:** Available in workflow run artifacts - **Note:** Push failed, created issue as fallback ``` **Rendered Output:** ## Push Failure Fallback - **Push Error:** Permission denied (publickey) - **Fallback Issue:** [#123](https://github.com/example/repo/issues/123) - **Patch Artifact:** Available in workflow run artifacts - **Note:** Push failed, created issue as fallback #### PR Fallback Summary **Markdown Source:** ```markdown ## Fallback Issue Created - **Issue**: [#123](issue_url) - **Branch**: [`branch-name`](branch_url) - **Base Branch**: `main` - **Note**: Pull request creation failed, created issue as fallback ``` **Rendered Output:** ## Fallback Issue Created - **Issue**: [#123](https://github.com/example/repo/issues/123) - **Branch**: [`aw-fix-auth-error-a3d8f9`](https://github.com/example/repo/tree/aw-fix-auth-error-a3d8f9) - **Base Branch**: `main` - **Note**: Pull request creation failed, created issue as fallback #### Updated Issues Summary **Markdown Source:** ```markdown ## Updated Issues - Issue #123: [Updated Title](issue_url) - Issue #456: [Another Updated Issue](issue_url) ``` **Rendered Output:** ## Updated Issues - Issue #123: [[Fixed] Authentication error handling](https://github.com/example/repo/issues/123) - Issue #456: [[Resolved] Password reset feature](https://github.com/example/repo/issues/456) ## Safe Output Types ### Create Issues **Purpose**: Creates new GitHub issues with AI-generated content. **Message Patterns Used**: - AI Attribution Footer (with triggering context) - Workflow Installation Instructions - Issue Parent References - Staged Mode Preview - Success Summary **Key Features**: - Label sanitization for safety - Sub-issue linking to parent issues - Parent issue references ### Create Discussions **Purpose**: Creates new GitHub discussions with AI-generated content. **Message Patterns Used**: - AI Attribution Footer (basic format) - Staged Mode Preview - Success Summary **Key Features**: - Category resolution by name or ID - Simplified footer format ### Add Comments **Purpose**: Adds comments to issues, pull requests, or discussions. **Message Patterns Used**: - AI Attribution Footer (with triggering context) - Workflow Installation Instructions - Related Items References - Staged Mode Preview - Success Summary **Key Features**: - Supports issues, PRs, and discussions - Threaded replies for discussion comments - Related items linking across workflow outputs ### Create Pull Requests **Purpose**: Creates pull requests with git patches from AI-generated code changes. **Message Patterns Used**: - AI Attribution Footer (basic format) - Patch Preview (with truncation) - Fallback Messages (push failure, PR creation failure) - Staged Mode Preview - Success Summary **Key Features**: - Patch validation and size limits - Cryptographic random branch names - Fallback to issue creation on failure - Empty patch detection ### Create PR Review Comments **Purpose**: Creates line-specific review comments on pull requests. **Message Patterns Used**: - AI Attribution Footer (with triggering context) - Workflow Installation Instructions - Staged Mode Preview - Success Summary **Key Features**: - Line-specific and multi-line comments - Side specification (LEFT/RIGHT for diff view) - Commit SHA validation ### Update Issues **Purpose**: Updates existing GitHub issues (title, body, or status). **Message Patterns Used**: - AI Attribution Footer (for all body update operations) - Staged Mode Preview - Success Summary **Key Features**: - Selective field updates (status, title, body) - Permission-based restrictions - AI footer added for all body operations (append, prepend, replace, replace-island) ## Design Patterns ### Consistent Footer Format All AI-generated content uses a blockquote footer format to identify the source via standard formatting: - Basic: `> AI generated by [WorkflowName](run_url)` - With context: `> AI generated by [WorkflowName](run_url) for #123` ### Staged Mode Indicator The 🎭 emoji consistently marks preview mode across all safe output types, enabling clear distinction between test runs and live operations. ### Visual Hierarchy - Headers use `##` for main sections and `###` for subsections - Bold text for field labels in previews - Horizontal rules (`---`) separate multiple items - Collapsible details for large content (patches) ### Link Patterns - Issue links: `#123` or `[#123](url)` - Pull request links: `#789` or `[#789](url)` - Discussion links: `discussion #456` or `[#456](url)` - Workflow runs: `[WorkflowName](run_url)` ### Content Safety - Label text is sanitized to prevent @mentions - Control characters are removed - Patch sizes are limited to prevent overwhelming displays ## Design Principles ### Consistency - All AI-generated content uses the same blockquote footer format - 🎭 emoji consistently marks staged preview mode - URL patterns match GitHub conventions - Step summaries follow the same heading and list structure ### Clarity - Clear distinction between preview and actual operations - Explicit error messages with actionable guidance - Helpful fallback instructions when operations fail - Field labels consistently use bold text ### Discoverability - Installation instructions included in footers when available - Related items automatically linked across workflow outputs - Step summaries provide quick access to created items - Collapsible sections keep large content manageable ### Safety - Labels are sanitized to prevent unintended @mentions - Patch sizes are validated and truncated when needed - Staged mode allows testing without side effects - Graceful fallbacks when primary operations fail ## Message Module Architecture The message system is split into modular files for better maintainability and to reduce JavaScript bundle bloat: ### Module Structure ```text pkg/workflow/js/ ├── messages_core.cjs # Core utilities (getMessages, renderTemplate, toSnakeCase) ├── messages_footer.cjs # Footer messages (getFooterMessage, getFooterInstallMessage, generateFooterWithMessages) ├── messages_staged.cjs # Staged mode messages (getStagedTitle, getStagedDescription) ├── messages_run_status.cjs # Run status messages (getRunStartedMessage, getRunSuccessMessage, getRunFailureMessage) ├── messages_close_discussion.cjs # Close discussion messages (getCloseOlderDiscussionMessage) └── messages.cjs # Barrel file for backward compatibility ``` ### Module Descriptions | Module | Purpose | Exported Functions | |--------|---------|-------------------| | `messages_core.cjs` | Shared utilities for message processing | `getMessages`, `renderTemplate`, `toSnakeCase` | | `messages_footer.cjs` | AI attribution and installation footers | `getFooterMessage`, `getFooterInstallMessage`, `generateFooterWithMessages` | | `messages_staged.cjs` | Staged mode preview messages | `getStagedTitle`, `getStagedDescription` | | `messages_run_status.cjs` | Workflow run status notifications | `getRunStartedMessage`, `getRunSuccessMessage`, `getRunFailureMessage` | | `messages_close_discussion.cjs` | Outdated discussion closing | `getCloseOlderDiscussionMessage` | ### Importing Messages For backward compatibility, the main `messages.cjs` file re-exports all functions: ```javascript // Backward-compatible import (imports all functions) const { generateFooterWithMessages, getStagedTitle } = require("./messages.cjs"); ``` For new code, prefer importing directly from specific modules to reduce bundle size: ```javascript // Direct import for footer messages only const { generateFooterWithMessages } = require("./messages_footer.cjs"); // Direct import for run status only const { getRunSuccessMessage, getRunFailureMessage } = require("./messages_run_status.cjs"); // Direct import for staged mode only const { getStagedTitle, getStagedDescription } = require("./messages_staged.cjs"); ``` ### Bundling Behavior The JavaScript bundler (in `pkg/workflow/bundler.go`) handles these imports during workflow compilation: - Local `require()` statements are resolved and inlined - Shared utilities from `messages_core.cjs` are inlined once and deduplicated - Only the required modules are included in the final bundle --- **Last Updated**: 2025-01-28 **Version**: 2.0 **Maintainers**: GitHub Next Team