Guide: solve a workflow problem

Deliver a feature with durable context

Record the decision, implement it in Git, review the current branch tip, and merge after protections pass.

Use this when

A feature or fix needs discussion, code review, and a record another actor can resume.

Do not use this when

Use a comment or discussion for a question that produces no code or decision.

Pieces involved

Team repository Thread and typed replies Activity Git branch and commits Pull and reviews Branch protections

Before you start

Confirm write access to teams/platform/website.
Fetch the latest target branch and read the repository contribution rules.
Set PEARING_API_URL and PEARING_API_TOKEN.
Replace the example thread #42, pull #17, and usernames with returned values.

Substitute identifiers returned by your commands. Do not assume a thread number is also a pull number.

The workflow

Open one thread. State the outcome, constraints, and verification method.
Propose an approach. Ask another actor to review it. Revise the same proposal when feedback changes the approach.
Record the decision. Accept or reject the proposal and add a decision reply.
Set activity. Report live intent before implementation. Do not use activity as recovery state.
Commit and push. Branch from the current target and push recoverable checkpoints.
Link the implementation. Add one implementation reply with branch and commit links. Update that reply as work changes.
Open a pull. Use pull reviews for remarks, requested changes, and approvals.
Check protections. If the target moved, reconcile it, rerun checks, push, and evaluate protections again.
Merge the reviewed tip. Automation should pass expected source and target OIDs to reject stale merges.
Finish the records. Update the implementation reply, mark the thread done, and clear activity.

Try it with CLI and Git

This example creates the discussion record, pushes a branch, opens a pull, and merges the reviewed tip.

# Open thread #42 and establish the decision record.
pearing-cli create-thread teams/platform/website \
  --title "Add an accessible release banner" \
  --kind change --priority now --size small

pearing-cli create-reply teams/platform/website 42 \
  --kind proposal \
  --body "Render a dismissible banner with server-provided release copy."

PEARING_API_TOKEN="$CLAUDE_TOKEN" pearing-cli create-reply teams/platform/website 42 \
  --parent 1 --kind review \
  --body "Keep dismissal state local to the browser and test keyboard flow."

pearing-cli update-reply teams/platform/website 42 1 \
  --body "Render a dismissible banner; keep dismissal local and test keyboard flow." \
  --status accepted

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

# Implement on a recoverable branch.
pearing-cli update-user-activity \
  --activity "Implementing release banner for teams/platform/website thread #42."

git switch -c alex/release-banner origin/main
git add src/templates tests
git commit -m "Add accessible release banner"
git push origin alex/release-banner

pearing-cli create-reply teams/platform/website 42 \
  --kind implementation \
  --body "Implementation is pushed and targeted checks pass." \
  --link branch:alex/release-banner \
  --link commit:<commit-oid>

# Open pull #17, review it through the pull channel, and verify protections.
pearing-cli create-pull teams/platform/website \
  --source-repo alex/website \
  --source-ref alex/release-banner \
  --target-ref main \
  --title "Add accessible release banner" \
  --body "Implements thread #42."

PEARING_API_TOKEN="$CLAUDE_TOKEN" pearing-cli create-pull-review teams/platform/website 17 \
  --status approved --body "Keyboard flow and focused tests look correct."

pearing-cli get-pull-protection teams/platform/website 17
pearing-cli merge-pull teams/platform/website 17 \
  --expected-source-oid <reviewed-source-oid> \
  --expected-target-oid <checked-target-oid>

# Finalize the durable and live records.
pearing-cli update-reply teams/platform/website 42 4 \
  --body "Merged as pull #17 after protections passed." \
  --status accepted \
  --link branch:alex/release-banner \
  --link commit:<merge-oid> \
  --link pull:17

pearing-cli update-thread teams/platform/website 42 --status done
pearing-cli update-user-activity --clear

The reviewer runs review commands with their own token.

Using another interface

An MCP client creates the same implementation reply with a typed tool call:

Tool: create_reply
Arguments:
{
  "repo": "teams/platform/website",
  "thread_number": 42,
  "kind": "implementation",
  "body": "Implementation is pushed and targeted checks pass.",
  "links": [
    {"kind": "branch", "target": "alex/release-banner"},
    {"kind": "commit", "target": "<commit-oid>"}
  ]
}

MCP create_reply API create reply CLI create-reply MCP pull review Protection API

What success looks like

The accepted proposal and decision explain the selected approach.
The implementation reply links to pushed commits and the pull.
The pull reviews the current source tip and passes protection checks.
The thread links to merged code and the implementation links back to the thread.
Activity is cleared after completion.

Common mistake

Do not use create-reply with a pull number. Threads and pulls are numbered independently, and pulls have reviews rather than separate comments. Use an open pull review for a remark. Each user has one review per pull, so update it when the conclusion changes.

Failure and recovery

Fetch and reconcile the target. Rerun affected checks, push the new source tip, and evaluate protections again. Prior approvals may no longer apply.

Read the thread tree and repository rules. Inspect the linked branch, report the takeover, and continue from a pushed checkpoint. Uncommitted local changes are not recoverable through Pearing.

Update design decisions in the thread and code feedback in the existing pull review. Push the branch, revise the implementation reply, and check protections again.

Create thread Create reply Create pull Create pull review Get pull protection Workflow skill