# Channel adapter  -  GitHub Issue comment

> Canonical template for the `issue` channel of `/multi-agent:channels`. Every successful run that touched a tracked GitHub issue MUST post one comment using this template  -  no exceptions, no "state-only" shortcuts.

## When this fires

The Issue Comment adapter runs once per channels invocation when:

```
state.tracker.kind === "github-issue"  AND  channels.selected includes "issue"
```

In multi-repo tasks, the issue lives on the primary repo's issue tracker. Extras don't get separate issue comments  -  their PRs are linked back through the comment body.

## The hard rule

**Never update the issue body Progress flags without ALSO posting a comment.** The comment is the human-readable narrative; flags are the machine-readable status. Either both or neither. A run that updates flags without commenting is a contract violation and the run is incomplete.

## Required body structure

The template (this doc) is English because `promptLanguage="en"` is locked. At write-time, headings and prose render in `prefs.global.outputLanguage`; code identifiers, repo/branch/commit names, URLs, and the `Ref: #N` footer stay verbatim across languages.

| # | Section key | Heading (`tr`) | Heading (`en`) | Required? |
|---|---|---|---|---|
| 1 | `title` | `## Geliştirme Detayı  -  \`<name>\`` | `## Implementation Detail  -  \`<name>\`` | always |
| 2 | `summary` | (paragraphs immediately under the title) | (same) | always |
| 3 | `prs_branches` | `### Pull Request / Dal` | `### Pull Requests / Branches` | always |
| 4 | `acceptance_criteria` | `### Kabul Kriterleri` | `### Acceptance Criteria` | always |
| 5 | `build_and_test` | `### Build & Test` | `### Build & Test` | always (heading stays English  -  tooling token) |
| 6 | `figma_extras` | `### Code Connect / Wiki` | `### Code Connect / Wiki` | only on the figma component task type |
| 7 | `next_steps` | `### Sonraki Adımlar` | `### Next Steps` | always (empty list allowed  -  signals "fully complete") |
| 8 | `ref_footer` | `Ref: #<issueNumber>` | `Ref: #<issueNumber>` | always (token text, never translated) |

### Template body (English  -  runtime renders headings in `outputLanguage`)

```markdown
## Implementation Detail  -  `<ComponentOrTaskName>`

<1-3 paragraphs: why this approach was chosen, what changed, any architectural decision worth flagging>

### Pull Requests / Branches
- **<repoName>:** <prKindLabel>  -  <prUrl OR "branch `<branchName>` pushed (commit `<shortSha>`), PR not opened">
<one line per repo touched; never collapse multiple repos into one>

### Acceptance Criteria
- [<x| >] <AC text  -  `x` if delivered, space if intentionally deferred (with `(deferred: <reason>)` suffix)>
<one bullet per AC item from the issue body, or per implicit AC if the issue had none>

### Build & Test
- Build: <green|red|baseline-pre-existing|skipped>  -  <one-line evidence: command + result OR "pre-existing failure verified on `<baselineSha>`">
- Tests: <N tests added | tests skipped (Phase 5 user-test path) | none>
<for figma component flow, also:>
- Code Connect: <published | dry-run-only | not-applicable>  -  <URL of Figma node if published>
- Wiki: <published | local-only | skipped>  -  <URL of wiki page if published>

### Next Steps
- <follow-up bullet  -  PRs to open, manual deploys, push consents needed>
<empty list is fine; the section header itself stays>

Ref: #<issueNumber>
```

### Section content rules

- **`title`**  -  always wraps the component or task name in backticks. No emoji.
- **`summary`**  -  1-3 paragraphs, **why** before **what**. No bullet lists in the summary block  -  those belong in `acceptance_criteria`.
- **`prs_branches`**  -  every repo the run touched gets exactly ONE line. If the PR was deferred, write the branch + commit SHA explicitly so the reader can `gh pr create` from there. Never collapse multiple repos into one line.
- **`acceptance_criteria`**  -  copy from the issue body verbatim when an `### Acceptance Criteria` section exists. If the section is `_No response_`, the agent enumerates the implicit ACs it satisfied during Phase 1/3. `[x]` only when delivered and verified; `[ ]` for deferred, with the reason in parens  -  GitHub's task-list syntax accepts only `[ ]` and `[x]`, any other marker (a `·` was used here once) renders as literal bracket text instead of a checkbox, and the `(deferred: <reason>)` suffix is what distinguishes deferred from merely unchecked.
- **`build_and_test`**  -  required. If a build failure was pre-existing, the line includes the baseline SHA where the failure was reproduced (per `feedback_build_baseline_proof.md`).
- **`figma_extras`**  -  emitted only when `state.taskType == "component"` and the figma sub-pipeline ran.
- **`next_steps`**  -  empty list is fine; the section header itself stays. Empty signals "fully complete, no follow-ups".
- **`ref_footer`**  -  always `Ref: #N` (or `Related: #N`). NEVER `Closes/Fixes/Resolves`  -  the pipeline never auto-closes issues (`feedback_no_issue_close.md`).

### Assembly order (per run)

```
1. Read agent-state.json (taskId, contextLinks, prUrls, taskType, language).
2. Build section bodies in markdown  -  title first, then in the table order, skipping conditional sections that don't apply.
3. Run the assembled body through the `humanizer` skill.
4. Apply compaction policy if length > 4000 chars (see below).
5. POST via `gh issue comment`.
```

## Hard prohibitions

- No "Co-Authored-By: Claude" trailer. No "🤖 Generated with ..." footer. No mention of Claude / Copilot / AI / model names anywhere in the body.
- No em-dashes (` - `) in prose. Use ` · ` or `→` per `feedback_no_em_dash.md`.
- No decorative/emotive emoji or smileys (    ) in the body prose. Only a fixed-template functional mark (e.g. a `done/pending` scope tick) is allowed; free text carries none.
- No HTML entities. Use raw markdown.
- No links to internal `/tmp/*` or local-machine paths.
- No screenshots embedded as base64  -  link to wiki / Figma instead.

## Compaction policy

If the comment exceeds 4000 characters, compact in this order:

1. `summary` trimmed to 1 paragraph.
2. `acceptance_criteria` list moved to a `<details>` collapsible.
3. `build_and_test` details collapsed to a one-line outcome.
4. `prs_branches` stays verbatim  -  never compact.
5. `next_steps` stays verbatim  -  never compact.

Below 4000 chars, no compaction; render the full template.

## API contract

```bash
gh issue comment "$ISSUE_NUMBER" --repo "$ORG/$REPO" --body-file /tmp/channels-$TASK_ID-issue.md
```

Token resolution: `gh auth status` for the active GitHub account selected in Phase 0. The comment is authored by the configured Git identity, posted via that account's PAT.

## Pairing with the Progress flag updater

Every issue comment post is paired with `$HOME/.claude/scripts/update-issue-progress.sh "$TASK_ID"` in the same Phase 7 step. Order: comment FIRST (so the timestamp marks the run), flags SECOND (so the body diff is one logical change).

```bash
# Phase 7 Step 5  -  issue channel
gh issue comment "$ISSUE_NUMBER" --repo "$ORG/$REPO" --body-file /tmp/channels-$TASK_ID-issue.md
bash $HOME/.claude/scripts/update-issue-progress.sh "$TASK_ID"
```

If either call fails, the channel adapter MUST NOT mark the issue channel as completed in `agent-state.json`. The user sees a clear error and can retry.

## Drift detection

`pipeline/scripts/smoke-issue-comment-template.sh` greps the latest 5 issue comments authored by the configured Git identity and asserts each contains:

- `## Geliştirme Detayı` OR `## Implementation Detail` (language axis)
- `### Pull Requests` OR `### Branches`
- `### Acceptance Criteria`
- `### Build & Test`
- `Ref: #` footer

A failed assertion blocks `pre-push-check.sh`. This catches runs where the agent free-formed the comment instead of using the template.

## Hard rules (must not regress)

- Section order is fixed: `title` → `summary` → `prs_branches` → `acceptance_criteria` → `build_and_test` → `figma_extras` (cond.) → `next_steps` → `ref_footer`. Conditional sections may be omitted but never reordered.
- Humanizer pass runs **after** body assembly and **before** compaction / POST.
- Body content language follows `prefs.global.outputLanguage`. Repo names, branch names, commit SHAs, URLs, the `Ref: #N` footer, and the `### Build & Test` heading itself stay verbatim. The template (this doc) is English because `promptLanguage="en"` is locked.
- Never update issue body Progress flags without also posting this comment  -  see "The hard rule" above and `pairing` block below.