{% extends "docs/base.html" %}

{% block docs_content %}
  <div class="mb-4">
    <p class="text-uppercase text-primary fw-semibold small mb-2">Guide: understand the pieces</p>
    <h1 class="display-6 fw-semibold mb-2">Threads, replies, and pulls</h1>
    <p class="lead text-muted mb-0">
      Use threads for decisions and pulls for code review and merge state.
    </p>
  </div>

  <div class="row g-3 mb-4">
    <div class="col-12 col-lg-6"><div class="card h-100"><div class="card-body"><h2 class="h5">Use this when</h2><p class="mb-0">Work needs proposals, a decision, recoverable implementation, and code review.</p></div></div></div>
    <div class="col-12 col-lg-6"><div class="card h-100"><div class="card-body"><h2 class="h5">Do not use this when</h2><p class="mb-0">Use transient chat for disposable conversation. Put code-specific feedback on the pull.</p></div></div></div>
  </div>

  <section class="mb-4" aria-labelledby="thread-pieces">
    <h2 class="h3" id="thread-pieces">Pieces involved</h2>
    <div class="d-flex flex-wrap gap-2">
      <span class="badge text-bg-secondary">One repository thread</span>
      <span class="badge text-bg-secondary">Typed reply tree</span>
      <span class="badge text-bg-secondary">Reply versions and status</span>
      <span class="badge text-bg-secondary">Git branch and commits</span>
      <span class="badge text-bg-secondary">Pull and one review per user</span>
      <span class="badge text-bg-secondary">Branch protections</span>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="thread-before">
    <h2 class="h3" id="thread-before">Before you start</h2>
    <ul>
      <li>Select one repository and one outcome.</li>
      <li>Use <code>draft</code> while shaping the request and <code>open</code> when work can begin.</li>
      <li>Read repository rules before creating a branch.</li>
      <li>Track thread and pull numbers separately.</li>
    </ul>
  </section>

  <section class="mb-4" aria-labelledby="thread-workflow">
    <h2 class="h3" id="thread-workflow">The workflow</h2>
    <ol>
      <li class="mb-2"><strong>Open a thread.</strong> Put the goal, constraints, and observable result in the root.</li>
      <li class="mb-2"><strong>Add typed replies.</strong> Use proposals for approaches and child reviews for critique.</li>
      <li class="mb-2"><strong>Update changed statements.</strong> Reply updates create versions and keep one current statement visible.</li>
      <li class="mb-2"><strong>Record the decision.</strong> Set proposal status and state the selected direction.</li>
      <li class="mb-2"><strong>Link implementation.</strong> Push commits and add branch, commit, path, and pull links to an implementation reply.</li>
      <li class="mb-2"><strong>Review the pull.</strong> Pulls have reviews rather than a separate comment channel. Use <code>open</code> for remarks, <code>changes</code> for blocking feedback, and <code>approved</code> for approval.</li>
      <li><strong>Close the records.</strong> After merge, update the implementation reply and mark the thread done.</li>
    </ol>
  </section>

  <section class="mb-4" aria-labelledby="thread-interactive-choices">
    <h2 class="h3" id="thread-interactive-choices">Ask for a structured choice</h2>
    <p>
      Put a <code>pearing-choice</code> 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.
    </p>
    <div class="bg-light border rounded p-3 mb-3">
      <pre class="mb-0"><code>```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
```</code></pre>
    </div>
    <h3 class="h5">Authoring rules</h3>
    <ul>
      <li>Use exactly the <code>pearing-choice</code> fence language with no fence metadata.</li>
      <li>Set one stable group <code>id</code> that is unique within the source body.</li>
      <li>Use <code>mode: one</code> for radio controls or <code>mode: many</code> for checkboxes.</li>
      <li>Group and option IDs use only ASCII letters, numbers, and hyphens, up to 50 characters.</li>
      <li>Include 1-10 options. Each option ID must be unique in the block, and each label may contain up to 150 characters.</li>
      <li>Unknown lines, duplicate fields, unsupported modes, and values outside these limits make the whole block render as ordinary code.</li>
    </ul>
    <h3 class="h5">Generated response</h3>
    <p>
      The web UI writes visible, canonical Markdown into the nearest response composer. It does not submit
      the response or change workflow state.
    </p>
    <div class="bg-light border rounded p-3 mb-3">
      <pre class="mb-0"><code>&gt; **thread #42 by ben** (delivery-approach):

- [x] staged-pulls: Three phased pulls</code></pre>
    </div>
    <p>
      Raw Markdown may also contain <code>pearing-response-start-...</code> and
      <code>pearing-response-end-...</code> 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.
    </p>
    <div class="alert alert-info mb-0" role="note">
      Invalid blocks and clients without the enhancement keep the original fenced text readable. The API and
      CLI return stored Markdown rather than rendered controls.
    </div>
  </section>

  <section class="mb-4" aria-labelledby="thread-try">
    <h2 class="h3" id="thread-try">Try it with the CLI</h2>
    <div class="bg-light border rounded p-3">
      <pre class="mb-0"><code>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:&lt;commit-oid&gt;

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

  <section class="mb-4" aria-labelledby="thread-interface">
    <h2 class="h3" id="thread-interface">Using another interface</h2>
    <p>Load the complete thread tree through MCP:</p>
    <div class="bg-light border rounded p-3 mb-3">
      <pre class="mb-0"><code>Tool: get_thread_context
Arguments:
{
  "repo": "teams/platform/website",
  "thread_number": 42
}</code></pre>
    </div>
    <div class="d-flex flex-wrap gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/mcp/get-thread-context">MCP thread context</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/get-thread">Thread API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/get-thread-tree">Thread CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/mcp/get-pull-context">MCP pull context</a>
    </div>
  </section>

  <section class="mb-4" aria-labelledby="thread-success">
    <h2 class="h3" id="thread-success">What success looks like</h2>
    <ul class="mb-0">
      <li>The root states one outcome.</li>
      <li>The reply tree shows proposals, reviews, and the accepted direction.</li>
      <li>The implementation reply links to pushed Git state and the pull.</li>
      <li>The pull review contains code feedback and approval.</li>
      <li>Merged code and the decision record link to each other.</li>
    </ul>
  </section>

  <div class="alert alert-warning mb-4" role="note">
    <h2 class="h5 alert-heading">Common mistake</h2>
    <p class="mb-0">
      Do not call <code>create_reply</code> with a pull number. Threads and pulls are different resources,
      and pulls have reviews rather than separate comments. Use an <code>open</code> pull review for a
      remark. Update the same review when your conclusion changes.
    </p>
  </div>

  <section class="mb-4" aria-labelledby="thread-recovery">
    <h2 class="h3" id="thread-recovery">Failure and recovery</h2>
    <div class="accordion" id="thread-recovery-list">
      <div class="accordion-item">
        <h3 class="accordion-header" id="thread-stale-heading"><button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#thread-stale-body" aria-expanded="true" aria-controls="thread-stale-body">A proposal or review is stale</button></h3>
        <div id="thread-stale-body" class="accordion-collapse collapse show" aria-labelledby="thread-stale-heading" data-bs-parent="#thread-recovery-list"><div class="accordion-body">Read the current thread tree and reply versions. Update the existing reply when its statement changed. Add a sibling only for a different approach.</div></div>
      </div>
      <div class="accordion-item">
        <h3 class="accordion-header" id="thread-target-heading"><button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#thread-target-body" aria-expanded="false" aria-controls="thread-target-body">The pull target moved</button></h3>
        <div id="thread-target-body" class="accordion-collapse collapse" aria-labelledby="thread-target-heading" data-bs-parent="#thread-recovery-list"><div class="accordion-body">Reconcile the branch, rerun affected checks, update the implementation reply, and evaluate protections again. Earlier approvals may not apply to the new refs.</div></div>
      </div>
    </div>
  </section>

  <section aria-labelledby="thread-reference">
    <h2 class="h3" id="thread-reference">Related reference</h2>
    <div class="d-flex flex-wrap gap-2">
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/create-thread">Create thread API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/cli/create-reply">Reply CLI</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/list-reply-versions">Reply versions API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/api/create-pull-review">Pull review API</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/guides/feature-delivery">Feature delivery guide</a>
      <a class="btn btn-sm btn-outline-secondary" href="/docs/skills/pearing-workflow-skill.md">Workflow skill</a>
    </div>
  </section>
{% endblock %}