Skip to content

Add Mermaid diagram for safe output message flow #3428

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 7, 2025
Merged

Add Mermaid diagram for safe output message flow #3428

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e424e02
Initial plan
Copilot Nov 7, 2025
c2ccd8a
Add Mermaid diagram for safe output message flow
Copilot Nov 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions .github/instructions/developer.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -634,6 +634,50 @@ gh aw compile --strict --actionlint --zizmor --poutine

Safe output functions handle GitHub API write operations (creating issues, discussions, comments, PRs) from AI-generated content with consistent messaging patterns.

### 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
Comment on lines +655 to +668
Copy link

Copilot AI Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The flow diagram shows that "Apply Message Patterns" (N) branches into four parallel operations (O, P, Q, R) that each independently flow to "Execute GitHub API Operation" (S). This implies four separate API executions, which is inaccurate.

In the actual implementation (e.g., pkg/workflow/js/create_issue.cjs), all message patterns (AI attribution footer, installation instructions, related items links, patch preview) are applied within a single JavaScript function that executes as part of one GitHub API operation.

Consider revising the diagram to show that O, P, Q, and R all converge into a single path before reaching S, or restructure it to show these as aspects/attributes of the message preparation rather than sequential steps. For example:

    N --> O[Prepare Message Content]
    O --> |Add AI Attribution| O
    O --> |Add Installation Instructions| O  
    O --> |Add Related Items Links| O
    O --> |Add Patch Preview| O
    O --> S[Execute GitHub API Operation]
Loading

Or simply show them as a grouped operation that happens before the API call.

Suggested change
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
H --> N[Prepare Message Content]
I --> N
J --> N
K --> N
L --> N
M --> N
N --> |Add AI Attribution| N
N --> |Add Installation Instructions| N
N --> |Add Related Items Links| N
N --> |Add Patch Preview| N
N --> S[Execute GitHub API Operation]

Copilot uses AI. Check for mistakes.
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

#### AI Attribution Footer
Expand Down
44 changes: 44 additions & 0 deletions specs/safe-output-messages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,50 @@ Safe output functions handle GitHub API write operations (creating issues, discu
- 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
Comment on lines +33 to +46
Copy link

Copilot AI Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The flow diagram shows that "Apply Message Patterns" (N) branches into four parallel operations (O, P, Q, R) that each independently flow to "Execute GitHub API Operation" (S). This implies four separate API executions, which is inaccurate.

In the actual implementation (e.g., pkg/workflow/js/create_issue.cjs), all message patterns (AI attribution footer, installation instructions, related items links, patch preview) are applied within a single JavaScript function that executes as part of one GitHub API operation.

Consider revising the diagram to show that O, P, Q, and R all converge into a single path before reaching S, or restructure it to show these as aspects/attributes of the message preparation rather than sequential steps. For example:

    N --> O[Prepare Message Content]
    O --> |Add AI Attribution| O
    O --> |Add Installation Instructions| O  
    O --> |Add Related Items Links| O
    O --> |Add Patch Preview| O
    O --> S[Execute GitHub API Operation]
Loading

Or simply show them as a grouped operation that happens before the API call.

Suggested change
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
H --> N[Prepare Message Content]
I --> N
J --> N
K --> N
L --> N
M --> N
N --> N1[Add AI Attribution]
N1 --> N2[Add Installation Instructions]
N2 --> N3[Add Related Items Links]
N3 --> N4[Add Patch Preview]
N4 --> S[Execute GitHub API Operation]

Copilot uses AI. Check for mistakes.
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
Expand Down
Loading