| 1 | --- |
| 2 | name: "external-comms" |
| 3 | description: "PAO workflow for scanning, drafting, and presenting community responses with human review gate" |
| 4 | domain: "community, communication, workflow" |
| 5 | confidence: "low" |
| 6 | source: "manual (RFC #426 — PAO External Communications)" |
| 7 | tools: |
| 8 | - name: "github-mcp-server-list_issues" |
| 9 | description: "List open issues for scan candidates and lightweight triage" |
| 10 | when: "Use for recent open issue scans before thread-level review" |
| 11 | - name: "github-mcp-server-issue_read" |
| 12 | description: "Read the full issue, comments, and labels before drafting" |
| 13 | when: "Use after selecting a candidate so PAO has complete thread context" |
| 14 | - name: "github-mcp-server-search_issues" |
| 15 | description: "Search for candidate issues or prior squad responses" |
| 16 | when: "Use when filtering by keywords, labels, or duplicate response checks" |
| 17 | - name: "gh CLI" |
| 18 | description: "Fallback for GitHub issue comments and discussions workflows" |
| 19 | when: "Use gh issue list/comment and gh api or gh api graphql when MCP coverage is incomplete" |
| 20 | --- |
| 21 | |
| 22 | ## Context |
| 23 | |
| 24 | Phase 1 is **draft-only mode**. |
| 25 | |
| 26 | - PAO scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval. |
| 27 | - **Human review gate is mandatory** — PAO never posts autonomously. |
| 28 | - Every action is logged to `.squad/comms/audit/`. |
| 29 | - This workflow is triggered manually only ("PAO, check community") — no automated or Ralph-triggered activation in Phase 1. |
| 30 | |
| 31 | ## Patterns |
| 32 | |
| 33 | ### 1. Scan |
| 34 | |
| 35 | Find unanswered community items with GitHub MCP tools first, or `gh issue list` / `gh api` as fallback for issues and discussions. |
| 36 | |
| 37 | - Include **open** issues and discussions only. |
| 38 | - Filter for items with **no squad team response**. |
| 39 | - Limit to items created in the last 7 days. |
| 40 | - Exclude items labeled `squad:internal` or `wontfix`. |
| 41 | - Include discussions **and** issues in the same sweep. |
| 42 | - Phase 1 scope is **issues and discussions only** — do not draft PR replies. |
| 43 | |
| 44 | ### Discussion Handling (Phase 1) |
| 45 | |
| 46 | Discussions use the GitHub Discussions API, which differs from issues: |
| 47 | |
| 48 | - **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions |
| 49 | - **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell) |
| 50 | - **Answers vs comments:** In Q&A discussions, PAO drafts an "answer" (not a comment). The human marks it as accepted answer after posting. |
| 51 | - **Phase 1 scope:** Issues and Discussions ONLY. No PR comments. |
| 52 | |
| 53 | ### 2. Classify |
| 54 | |
| 55 | Determine the response type before drafting. |
| 56 | |
| 57 | - Welcome (new contributor) |
| 58 | - Troubleshooting (bug/help) |
| 59 | - Feature guidance (feature request/how-to) |
| 60 | - Redirect (wrong repo/scope) |
| 61 | - Acknowledgment (confirmed, no fix) |
| 62 | - Closing (resolved) |
| 63 | - Technical uncertainty (unknown cause) |
| 64 | - Empathetic disagreement (pushback on a decision or design) |
| 65 | - Information request (need more reproduction details or context) |
| 66 | |
| 67 | ### Template Selection Guide |
| 68 | |
| 69 | | Signal in Issue/Discussion | → Response Type | Template | |
| 70 | |---------------------------|-----------------|----------| |
| 71 | | New contributor (0 prior issues) | Welcome | T1 | |
| 72 | | Error message, stack trace, "doesn't work" | Troubleshooting | T2 | |
| 73 | | "How do I...?", "Can Squad...?", "Is there a way to...?" | Feature Guidance | T3 | |
| 74 | | Wrong repo, out of scope for Squad | Redirect | T4 | |
| 75 | | Confirmed bug, no fix available yet | Acknowledgment | T5 | |
| 76 | | Fix shipped, PR merged that resolves issue | Closing | T6 | |
| 77 | | Unclear cause, needs investigation | Technical Uncertainty | T7 | |
| 78 | | Author disagrees with a decision or design | Empathetic Disagreement | T8 | |
| 79 | | Need more reproduction info or context | Information Request | T9 | |
| 80 | |
| 81 | Use exactly one template as the base draft. Replace placeholders with issue-specific details, then apply the humanizer patterns. If the thread spans multiple signals, choose the highest-risk template and capture the nuance in the thread summary. |
| 82 | |
| 83 | ### Confidence Classification |
| 84 | |
| 85 | | Confidence | Criteria | Example | |
| 86 | |-----------|----------|---------| |
| 87 | | 🟢 High | Answer exists in Squad docs or FAQ, similar question answered before, no technical ambiguity | "How do I install Squad?" | |
| 88 | | 🟡 Medium | Technical answer is sound but involves judgment calls, OR docs exist but don't perfectly match the question, OR tone is tricky | "Can Squad work with Azure DevOps?" (yes, but setup is nuanced) | |
| 89 | | 🔴 Needs Review | Technical uncertainty, policy/roadmap question, potential reputational risk, author is frustrated/angry, question about unreleased features | "When will Squad support Claude?" | |
| 90 | |
| 91 | **Auto-escalation rules:** |
| 92 | - Any mention of competitors → 🔴 |
| 93 | - Any mention of pricing/licensing → 🔴 |
| 94 | - Author has >3 follow-up comments without resolution → 🔴 |
| 95 | - Question references a closed-wontfix issue → 🔴 |
| 96 | |
| 97 | ### 3. Draft |
| 98 | |
| 99 | Use the humanizer skill for every draft. |
| 100 | |
| 101 | - Complete **Thread-Read Verification** before writing. |
| 102 | - Read the **full thread**, including all comments, before writing. |
| 103 | - Select the matching template from the **Template Selection Guide** and record the template ID in the review notes. |
| 104 | - Treat templates as reusable drafting assets: keep the structure, replace placeholders, and only improvise when the thread truly requires it. |
| 105 | - Validate the draft against the humanizer anti-patterns. |
| 106 | - Flag long threads (`>10` comments) with `⚠️`. |
| 107 | |
| 108 | ### Thread-Read Verification |
| 109 | |
| 110 | Before drafting, PAO MUST verify complete thread coverage: |
| 111 | |
| 112 | 1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft. |
| 113 | 2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table. |
| 114 | 3. **Thread summary:** Include in every draft: "Thread: {N} comments, last activity {date}, {summary of key points}" |
| 115 | 4. **Long thread flag:** If >10 comments, add ⚠️ to review table and include condensed thread summary |
| 116 | 5. **Evidence line in review table:** Each draft row includes "Read: {N}/{total} comments" column |
| 117 | |
| 118 | ### 4. Present |
| 119 | |
| 120 | Show drafts for review in this exact format: |
| 121 | |
| 122 | ```text |
| 123 | 📝 PAO — Community Response Drafts |
| 124 | ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ |
| 125 | |
| 126 | | # | Item | Author | Type | Confidence | Read | Preview | |
| 127 | |---|------|--------|------|------------|------|---------| |
| 128 | | 1 | Issue #N | @user | Type | 🟢/🟡/🔴 | N/N | "First words..." | |
| 129 | |
| 130 | Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review |
| 131 | |
| 132 | Full drafts below ▼ |
| 133 | ``` |
| 134 | |
| 135 | Each full draft must begin with the thread summary line: |
| 136 | `Thread: {N} comments, last activity {date}, {summary of key points}` |
| 137 | |
| 138 | ### 5. Human Action |
| 139 | |
| 140 | Wait for explicit human direction before anything is posted. |
| 141 | |
| 142 | - `pao approve 1 3` — approve drafts 1 and 3 |
| 143 | - `pao edit 2` — edit draft 2 |
| 144 | - `pao skip` — skip all |
| 145 | - `banana` — freeze all pending (safe word) |
| 146 | |
| 147 | ### Rollback — Bad Post Recovery |
| 148 | |
| 149 | If a posted response turns out to be wrong, inappropriate, or needs correction: |
| 150 | |
| 151 | 1. **Delete the comment:** |
| 152 | - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}` |
| 153 | - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'` |
| 154 | 2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content |
| 155 | 3. **Draft replacement** (if needed): PAO drafts a corrected response, goes through normal review cycle |
| 156 | 4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case |
| 157 | |
| 158 | **Safe word — `banana`:** |
| 159 | - Immediately freezes all pending drafts in the review queue |
| 160 | - No new scans or drafts until `pao resume` is issued |
| 161 | - Audit entry logged with halter identity and reason |
| 162 | |
| 163 | ### 6. Post |
| 164 | |
| 165 | After approval: |
| 166 | |
| 167 | - Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments. |
| 168 | - PAO helps by preparing the CLI command. |
| 169 | - Write the audit entry after the posting action. |
| 170 | |
| 171 | ### 7. Audit |
| 172 | |
| 173 | Log every action. |
| 174 | |
| 175 | - Location: `.squad/comms/audit/{timestamp}.md` |
| 176 | - Required fields vary by action — see `.squad/comms/templates/audit-entry.md` Conditional Fields table |
| 177 | - Universal required fields: `timestamp`, `action` |
| 178 | - All other fields are conditional on the action type |
| 179 | |
| 180 | ## Examples |
| 181 | |
| 182 | These are reusable templates. Keep the structure, replace placeholders, and adjust only where the thread requires it. |
| 183 | |
| 184 | ### Example scan command |
| 185 | |
| 186 | ```bash |
| 187 | gh issue list --state open --json number,title,author,labels,comments --limit 20 |
| 188 | ``` |
| 189 | |
| 190 | ### Example review table |
| 191 | |
| 192 | ```text |
| 193 | 📝 PAO — Community Response Drafts |
| 194 | ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ |
| 195 | |
| 196 | | # | Item | Author | Type | Confidence | Read | Preview | |
| 197 | |---|------|--------|------|------------|------|---------| |
| 198 | | 1 | Issue #426 | @newdev | Welcome | 🟢 | 1/1 | "Hey @newdev! Welcome to Squad..." | |
| 199 | | 2 | Discussion #18 | @builder | Feature guidance | 🟡 | 4/4 | "Great question! Today the CLI..." | |
| 200 | | 3 | Issue #431 ⚠️ | @debugger | Technical uncertainty | 🔴 | 12/12 | "Interesting find, @debugger..." | |
| 201 | |
| 202 | Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review |
| 203 | |
| 204 | Full drafts below ▼ |
| 205 | ``` |
| 206 | |
| 207 | ### Example audit entry (post action) |
| 208 | |
| 209 | ```markdown |
| 210 | --- |
| 211 | timestamp: "2026-03-16T21:30:00Z" |
| 212 | action: "post" |
| 213 | item_number: 426 |
| 214 | draft_id: 1 |
| 215 | reviewer: "@bradygaster" |
| 216 | --- |
| 217 | |
| 218 | ## Context (draft, approve, edit, skip, post, delete actions) |
| 219 | - Thread depth: 3 |
| 220 | - Response type: welcome |
| 221 | - Confidence: 🟢 |
| 222 | - Long thread flag: false |
| 223 | |
| 224 | ## Draft Content (draft, edit, post actions) |
| 225 | Thread: 3 comments, last activity 2026-03-16, reporter hit a preview-build regression after install. |
| 226 | |
| 227 | Hey @newdev! Welcome to Squad 👋 Thanks for opening this. |
| 228 | We reproduced the issue in preview builds and we're checking the regression point now. |
| 229 | Let us know if you can share the command you ran right before the failure. |
| 230 | |
| 231 | ## Post Result (post, delete actions) |
| 232 | https://github.com/bradygaster/squad/issues/426#issuecomment-123456 |
| 233 | ``` |
| 234 | |
| 235 | ### T1 — Welcome |
| 236 | |
| 237 | ```text |
| 238 | Hey {author}! Welcome to Squad 👋 Thanks for opening this. |
| 239 | {specific acknowledgment or first answer} |
| 240 | Let us know if you have questions — happy to help! |
| 241 | ``` |
| 242 | |
| 243 | ### T2 — Troubleshooting |
| 244 | |
| 245 | ```text |
| 246 | Thanks for the detailed report, {author}! |
| 247 | Here's what we think is happening: {explanation} |
| 248 | {steps or workaround} |
| 249 | Let us know if that helps, or if you're seeing something different. |
| 250 | ``` |
| 251 | |
| 252 | ### T3 — Feature Guidance |
| 253 | |
| 254 | ```text |
| 255 | Great question! {context on current state} |
| 256 | {guidance or workaround} |
| 257 | We've noted this as a potential improvement — {tracking info if applicable}. |
| 258 | ``` |
| 259 | |
| 260 | ### T4 — Redirect |
| 261 | |
| 262 | ```text |
| 263 | Thanks for reaching out! This one is actually better suited for {correct location}. |
| 264 | {brief explanation of why} |
| 265 | Feel free to open it there — they'll be able to help! |
| 266 | ``` |
| 267 | |
| 268 | ### T5 — Acknowledgment |
| 269 | |
| 270 | ```text |
| 271 | Good catch, {author}. We've confirmed this is a real issue. |
| 272 | {what we know so far} |
| 273 | We'll update this thread when we have a fix. Thanks for flagging it! |
| 274 | ``` |
| 275 | |
| 276 | ### T6 — Closing |
| 277 | |
| 278 | ```text |
| 279 | This should be resolved in {version/PR}! 🎉 |
| 280 | {brief summary of what changed} |
| 281 | Thanks for reporting this, {author} — it made Squad better. |
| 282 | ``` |
| 283 | |
| 284 | ### T7 — Technical Uncertainty |
| 285 | |
| 286 | ```text |
| 287 | Interesting find, {author}. We're not 100% sure what's causing this yet. |
| 288 | Here's what we've ruled out: {list} |
| 289 | We'd love more context if you have it — {specific ask}. |
| 290 | We'll dig deeper and update this thread. |
| 291 | ``` |
| 292 | |
| 293 | ### T8 — Empathetic Disagreement |
| 294 | |
| 295 | ```text |
| 296 | We hear you, {author}. That's a fair concern. |
| 297 | |
| 298 | The current design choice was driven by {reason}. We know it's not ideal for every use case. |
| 299 | |
| 300 | {what alternatives exist or what trade-off was made} |
| 301 | |
| 302 | If you have ideas for how to make this work better for your scenario, we'd love to hear them — open a discussion or drop your thoughts here! |
| 303 | ``` |
| 304 | |
| 305 | ### T9 — Information Request |
| 306 | |
| 307 | ```text |
| 308 | Thanks for reporting this, {author}! |
| 309 | |
| 310 | To help us dig into this, could you share: |
| 311 | - {specific ask 1} |
| 312 | - {specific ask 2} |
| 313 | - {specific ask 3, if applicable} |
| 314 | |
| 315 | That context will help us narrow down what's happening. Appreciate it! |
| 316 | ``` |
| 317 | |
| 318 | ## Anti-Patterns |
| 319 | |
| 320 | - ❌ Posting without human review (NEVER — this is the cardinal rule) |
| 321 | - ❌ Drafting without reading full thread (context is everything) |
| 322 | - ❌ Ignoring confidence flags (🔴 items need Flight/human review) |
| 323 | - ❌ Scanning closed issues (only open items) |
| 324 | - ❌ Responding to issues labeled `squad:internal` or `wontfix` |
| 325 | - ❌ Skipping audit logging (every action must be recorded) |
| 326 | - ❌ Drafting for issues where a squad member already responded (avoid duplicates) |
| 327 | - ❌ Drafting pull request responses in Phase 1 (issues/discussions only) |
| 328 | - ❌ Treating templates like loose examples instead of reusable drafting assets |
| 329 | - ❌ Asking for more info without specific requests |