# PR Summary Sync

Read this file before syncing the single reviewer-facing PR summary comment.

## Scope

Current callers:
- `create-pr`: create or update the summary comment when the PR is opened
- `commit`: refresh the summary comment on an existing PR when needed

If another skill needs to refresh the PR summary later, point that skill's reference file at this rule first, then document only the skill-specific trigger and failure behavior there.

## Hidden Marker

Use this hidden marker:

```html
<!-- sync-pr:{task-id}:summary -->
```

Within one PR, a given `{task-id}` must have only one summary comment with this marker.

## Aggregation Inputs

Aggregate the latest artifacts in the task directory:
- `plan.md` or the latest `plan-r{N}.md`
- `implementation.md` or the latest `implementation-r{N}.md`
- `review.md` or the latest `review-r{N}.md`
- `refinement.md` or the latest `refinement-r{N}.md`

Aggregation rules:
- extract 2-4 self-contained technical decisions from `plan*`
- build the review-history table from `review*` and `refinement*`
- extract the test summary from `implementation*` or `refinement*`
- if one artifact class is missing, treat it as "no data for this stage" and continue

## Comment Body Template

Use this canonical comment body template:

```markdown
<!-- sync-pr:{task-id}:summary -->
<!-- last-commit: {git-head-sha} -->
## Review Summary

> **{agent}** · {task-id}

**Updated At**: {current-time}

### Key Technical Decisions

- {decision-1}
- {decision-2}

### Review History

| Round | Verdict | Finding Counts | Fix Status |
|-------|---------|----------------|------------|
| Round 1 | Pending | N/A | N/A |

### Test Results

- {test-summary}

---
*Generated by {agent} · Internal tracking: {task-id}*
```

## Comment Lookup And Update

Fetch existing comments through the Issues comments API, not the dedicated PR comments API.

Before this section runs, the caller must resolve `upstream_repo` by following `.agents/rules/issue-pr-commands.md` / `.agents/rules/issue-sync.md`.

Process:
1. Fetch existing PR comments and locate the comment ID that starts with `<!-- sync-pr:{task-id}:summary -->`
2. When rendering the body, always write the current `git rev-parse HEAD` result into `<!-- last-commit: {git-head-sha} -->`
3. If it does not exist, create it once as a fallback
4. If it exists and the body is identical, skip the write
5. If it exists and the body changed, PATCH it in place

When updating an existing comment, use:

```bash
gh api "repos/$upstream_repo/issues/comments/{comment-id}" -X PATCH -f body="$(cat <<'EOF'
{comment-body}
EOF
)"
```

## Shell Safety Rules

1. Read local artifact content first, then inline the actual text into a `<<'EOF'` heredoc.
2. Do not use command substitution or variable expansion inside the heredoc.
3. Do not use `echo` to construct bodies that contain `<!-- -->`; use `cat <<'EOF'` or `printf '%s\n'`.

## Error Handling

| Failure Point | Handling |
|--------|------|
| `task.md` cannot be read | skip sync and let the later verification gate report it |
| aggregation input is missing | warn and continue with the available data |
| `gh api` GET/PATCH/POST fails | warn and continue; whether the current skill should block is decided by the caller |
| `pr_number` points to a missing PR | warn with `PR #{pr-number} not found` and continue |

## Result Reporting

Return one of these normalized results so callers can reuse it in Activity Log entries or user output:
- `summary created`
- `summary updated`
- `summary skipped (no diff)`
- `summary failed: <reason>`
