External Comms

Discussion Handling (Phase 1)

Discussions use the GitHub Discussions API, which differs from issues:

• Scan: gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)' to find unanswered discussions
• Categories: Filter by Q&A and General categories only (skip Announcements, Show and Tell)
• Answers vs comments: In Q&A discussions, PAO drafts an "answer" (not a comment). The human marks it as accepted answer after posting.
• Phase 1 scope: Issues and Discussions ONLY. No PR comments.

2. Classify

Determine the response type before drafting.

• Welcome (new contributor)
• Troubleshooting (bug/help)
• Feature guidance (feature request/how-to)
• Redirect (wrong repo/scope)
• Acknowledgment (confirmed, no fix)
• Closing (resolved)
• Technical uncertainty (unknown cause)
• Empathetic disagreement (pushback on a decision or design)
• Information request (need more reproduction details or context)

Template Selection Guide

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.

Confidence Classification

Auto-escalation rules:

• Any mention of competitors → 🔴
• Any mention of pricing/licensing → 🔴
• Author has >3 follow-up comments without resolution → 🔴
• Question references a closed-wontfix issue → 🔴

3. Draft

Use the humanizer skill for every draft.

• Complete Thread-Read Verification before writing.
• Read the full thread, including all comments, before writing.
• Select the matching template from the Template Selection Guide and record the template ID in the review notes.
• Treat templates as reusable drafting assets: keep the structure, replace placeholders, and only improvise when the thread truly requires it.
• Validate the draft against the humanizer anti-patterns.
• Flag long threads (>10 comments) with ⚠️.

Thread-Read Verification

Before drafting, PAO MUST verify complete thread coverage:

1. Count verification: Compare API comment count with actually-read comments. If mismatch, abort draft.
2. Deleted comment check: Use gh api timeline to detect deleted comments. If found, flag as ⚠️ in review table.
3. Thread summary: Include in every draft: "Thread: {N} comments, last activity {date}, {summary of key points}"
4. Long thread flag: If >10 comments, add ⚠️ to review table and include condensed thread summary
5. Evidence line in review table: Each draft row includes "Read: {N}/{total} comments" column

4. Present

Show drafts for review in this exact format:

📝 PAO — Community Response Drafts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| # | Item | Author | Type | Confidence | Read | Preview |
|---|------|--------|------|------------|------|---------|
| 1 | Issue #N | @user | Type | 🟢/🟡/🔴 | N/N | "First words..." |

Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review

Full drafts below ▼

Each full draft must begin with the thread summary line: Thread: {N} comments, last activity {date}, {summary of key points}

5. Human Action

Wait for explicit human direction before anything is posted.

• pao approve 1 3 — approve drafts 1 and 3
• pao edit 2 — edit draft 2
• pao skip — skip all
• banana — freeze all pending (safe word)

Rollback — Bad Post Recovery

If a posted response turns out to be wrong, inappropriate, or needs correction:

1. Delete the comment:
   • Issues: gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}
   • Discussions: gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'
2. Log the deletion: Write audit entry with action delete, include reason and original content
3. Draft replacement (if needed): PAO drafts a corrected response, goes through normal review cycle
4. Postmortem: If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case

Safe word — banana:

• Immediately freezes all pending drafts in the review queue
• No new scans or drafts until pao resume is issued
• Audit entry logged with halter identity and reason

6. Post

After approval:

• Human posts via gh issue comment for issues or gh api for discussion answers/comments.
• PAO helps by preparing the CLI command.
• Write the audit entry after the posting action.

7. Audit

Log every action.

• Location: .squad/comms/audit/{timestamp}.md
• Required fields vary by action — see .squad/comms/templates/audit-entry.md Conditional Fields table
• Universal required fields: timestamp, action
• All other fields are conditional on the action type

Examples

These are reusable templates. Keep the structure, replace placeholders, and adjust only where the thread requires it.

Example scan command

gh issue list --state open --json number,title,author,labels,comments --limit 20

Example review table

📝 PAO — Community Response Drafts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| # | Item | Author | Type | Confidence | Read | Preview |
|---|------|--------|------|------------|------|---------|
| 1 | Issue #426 | @newdev | Welcome | 🟢 | 1/1 | "Hey @newdev! Welcome to Squad..." |
| 2 | Discussion #18 | @builder | Feature guidance | 🟡 | 4/4 | "Great question! Today the CLI..." |
| 3 | Issue #431 ⚠️ | @debugger | Technical uncertainty | 🔴 | 12/12 | "Interesting find, @debugger..." |

Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review

Full drafts below ▼

Example audit entry (post action)

---