docs(commits): document slack-deepsat MCP payload format

The MCP's `conversations_add_message` tool takes the raw mrkdwn body in `payload`, not a Slack API JSON envelope. Wrapping the body in `{"text": "..."}` posts the literal JSON to the channel — `<@>` mention strips, escaped `\n` renders as a literal `n`, and the `text:` key prefix shows up in the post. Step 8 now documents the format + mrkdwn list so PR-review notifications don't garble.

1 files changed, 11 insertions, 0 deletions

diff --git a/claude-rules/commits.md b/claude-rules/commits.md
index 6c1d275..9e1a8e0 100644
--- a/claude-rules/commits.md
+++ b/claude-rules/commits.md
@@ -388,6 +388,17 @@ Pick the shape first. Most reviews are Shape 1.
    - Changes requested: `<@author-slack-id> Changes Requested PR #N\n<pr-url>`
    Replace `#N` with the PR number and `<pr-url>` with the GHE URL of the PR. Always lead with an `<@author-slack-id>` mention so the engineer who owns the merge decision gets pinged — the message is useless without it. Resolve the Slack user ID via the slack-deepsat `users_search` tool using the PR author's name or email. The URL goes on its own line, immediately after the message. If the MCP doesn't have a post-message tool registered (for example, in a project where the Slack MCP is read-only), surface that to the user and skip the post — don't fall back to a different channel or asking the user to paste it.
 
+   **MCP payload format.** The `mcp__slack-deepsat__conversations_add_message` tool's `payload` parameter is the **raw Slack mrkdwn message body**, not a Slack API JSON envelope. Pass the message body string directly:
+
+   ```
+   payload: <@U09AUV4087N> Approved PR #171.
+   https://deepsat.ghe.com/deepsat/orchestration_dashboard_mvp/pull/171
+   ```
+
+   Wrapping the body in `{"text": "..."}` posts the literal JSON object as the message — the `<@>` mention strips to plain text, escaped `\n` renders as the letter `n`, and the `text:` key prefix appears in the post. The engineer doesn't get pinged. Use real newlines in the string (a literal newline character), not the escape sequence. The MCP has no delete method, so a garbled post can only be removed manually from Slack — surface garble to the user immediately so they can clean it up before reposting.
+
+   Slack mrkdwn that the `payload` string supports: `<@USER_ID>` for user mentions, `<#CHANNEL_ID>` for channel refs, real newlines for line breaks, `*bold*`, `_italic_`, ``\`code\``` and ``` ``` ``` blocks, and `<url|label>` for labeled links.
+
    **Thread under the engineer's review-request post.** Before posting, scan the channel's recent history (`mcp__slack-deepsat__conversations_history`) for the engineer's original post containing the PR URL — typically a "New PR" message or just the PR link. Post the verdict notification with `thread_ts=<original-message-ts>` so it lands in the reply thread off that original. This keeps each PR's review state contained in one thread instead of fragmenting across top-level posts in a mixed feed. The same threading rule applies to both `APPROVE` and `REQUEST_CHANGES` verdicts.
 
    **No review-request post found?** Don't auto-pick a fallback. Ask the user which they prefer: