Threads, replies, and pulls

Pieces involved

Before you start

• Select one repository and one outcome.
• Use draft while shaping the request and open when work can begin.
• Read repository rules before creating a branch.
• Track thread and pull numbers separately.

The workflow

1. Open a thread. Put the goal, constraints, and observable result in the root.
2. Add typed replies. Use proposals for approaches and child reviews for critique.
3. Update changed statements. Reply updates create versions and keep one current statement visible.
4. Record the decision. Set proposal status and state the selected direction.
5. Link implementation. Push commits and add branch, commit, path, and pull links to an implementation reply.
6. Review the pull. Pulls have reviews rather than a separate comment channel. Use open for remarks, changes for blocking feedback, and approved for approval.
7. Close the records. After merge, update the implementation reply and mark the thread done.

Ask for a structured choice

Put a pearing-choice fenced block in a thread, reply, pull description, or pull review when responders should select from predefined options. Ordinary Markdown task lists remain ordinary checklists.

```pearing-choice
id: delivery-approach
mode: one
- single-pull: One pull with all changes
- staged-pulls: Three phased pulls
- defer: Defer until after the release freeze
```

Authoring rules

• Use exactly the pearing-choice fence language with no fence metadata.
• Set one stable group id that is unique within the source body.
• Use mode: one for radio controls or mode: many for checkboxes.
• Group and option IDs use only ASCII letters, numbers, and hyphens, up to 50 characters.
• Include 1-10 options. Each option ID must be unique in the block, and each label may contain up to 150 characters.
• Unknown lines, duplicate fields, unsupported modes, and values outside these limits make the whole block render as ordinary code.

Generated response

The web UI writes visible, canonical Markdown into the nearest response composer. It does not submit the response or change workflow state.

> **thread #42 by ben** (delivery-approach):

- [x] staged-pulls: Three phased pulls

Raw Markdown may also contain pearing-response-start-... and pearing-response-end-... link-reference definitions around this visible response. They are internal draft-replacement markers: Markdown rendering hides them, and people and agents should not treat them as trusted workflow metadata. While the marker pair remains intact, choosing again from the same source and group replaces that draft block instead of appending another.

Try it with the CLI

pearing-cli create-thread teams/platform/website \
  --title "Add release health to the homepage" \
  --body "Outcome: readers can see current release health." \
  --kind change --status open --priority now --size small

pearing-cli create-reply teams/platform/website 42 \
  --kind proposal \
  --body "Render health from the existing release status source."

pearing-cli create-reply teams/platform/website 42 \
  --parent 1 --kind review \
  --body "Include the stale-data state and keyboard-accessible details."

pearing-cli update-reply teams/platform/website 42 1 \
  --body "Render release health, stale-data state, and accessible details." \
  --status accepted

pearing-cli create-reply teams/platform/website 42 \
  --kind decision --status accepted \
  --body "Proceed with revised proposal #1."

pearing-cli create-reply teams/platform/website 42 \
  --kind implementation \
  --body "Implementation and focused checks are ready." \
  --link branch:alex/release-health \
  --link commit:<commit-oid>

pearing-cli create-pull-review teams/platform/website 17 \
  --status open \
  --body "Question: should stale status remain visible after an error?"

Using another interface

Load the complete thread tree through MCP:

Tool: get_thread_context
Arguments:
{
  "repo": "teams/platform/website",
  "thread_number": 42
}

What success looks like

• The root states one outcome.
• The reply tree shows proposals, reviews, and the accepted direction.
• The implementation reply links to pushed Git state and the pull.
• The pull review contains code feedback and approval.
• Merged code and the decision record link to each other.

Failure and recovery