Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ One invocation of thirdshift that does factory work: a **Ticket run** or **Spec
_Avoid_: invocation, job

**Ticket run**:
One invocation of the factory on a single issue that is not a **Spec**, from launch to cleanup, normally ending in one pull request ready for review, or a **Self-merge** when its command or the **User config** asks for one. A Ticket run on an issue labelled `bug` reproduces the bug before fixing it, in a fresh Ticket run or a **Continuation**, except for Security fixes and **Base fixes**, which have their own flow. If the bug is not reproduced, the Ticket run ends successfully with triage notes and `needs-info` on the issue, without opening or merging a pull request. Started directly on an **Issue URL**, by a **Spec run** for one of its **Tickets**, by an **Architect run** for the Ticket its **Architecture review** published, by a **Pickup run** for the **Ready issue** it took, or by a **Security run** for a **Security finding** it fixes.
One invocation of the factory on a single issue that is not a **Spec**, from launch to cleanup, normally ending in one pull request ready for review, or a **Self-merge** when its command or the **User config** asks for one. A Ticket run on an issue labelled `bug` reproduces the bug before fixing it, in a fresh Ticket run or a **Continuation**, except for Security fixes and **Base fixes**, which have their own flow. A Continuation whose **Issue branch** has commits beyond the **Base branch** reproduces at their merge base, then checks the fix on the branch; a fix already there still goes on to review and the pull request. If the bug is not reproduced, including when it is absent at that merge base, the Ticket run ends successfully with triage notes and `needs-info` on the issue, without opening or merging a pull request. Started directly on an **Issue URL**, by a **Spec run** for one of its **Tickets**, by an **Architect run** for the Ticket its **Architecture review** published, by a **Pickup run** for the **Ready issue** it took, or by a **Security run** for a **Security finding** it fixes.
_Avoid_: Run, Merge run (former names), auto-merge (GitHub's own feature)

**Spec run**:
Expand Down
4 changes: 2 additions & 2 deletions prompts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ With `harness codex`, each session runs `codex exec --json --dangerously-bypass-
| Code review | In an Eval Trial, reviews the prepared historical diff with the production code-review Factory skill, under the implement session's sub-agent rules. Writes reports without fixing or publishing anything. | [code-review.md](code-review.md) |
| Spec review | In a Spec run, starts the Spec review once every Ticket has landed on the Spec branch, before the Spec PR, a draft until then, is marked ready. | [spec-review.md](spec-review.md) |
| Bug Ticket run, fresh | Starts the implement session on an issue labelled bug: diagnose before changing code, then implement only if reproduced. Security fixes and Base fixes keep their own flow. | [bug-fresh.md](bug-fresh.md) |
| Bug Ticket run, Continuation without a pull request | Diagnoses a bug in a Continuation with no pull request before changing code. A not reproduced ending hands the issue back for information without a PR. | [bug-continuation.md](bug-continuation.md) |
| Bug Ticket run, Continuation with an open pull request | Diagnoses a bug before continuing its open pull request. A not reproduced ending leaves the existing PR unmerged and hands the issue back for information. | [bug-continuation-pr.md](bug-continuation-pr.md) |
| Bug Ticket run, Continuation without a pull request | Diagnoses a bug in a Continuation with no pull request before changing code. When the Issue branch is ahead of the Base branch, the prompt names their merge base and reproduction happens there. A not reproduced ending hands the issue back for information without a PR. | [bug-continuation.md](bug-continuation.md) |
| Bug Ticket run, Continuation with an open pull request | Diagnoses a bug before continuing its open pull request. When the Issue branch is ahead of the Base branch, the prompt names their merge base and reproduction happens there. A not reproduced ending leaves the existing PR unmerged and hands the issue back for information. | [bug-continuation-pr.md](bug-continuation-pr.md) |
| Architecture review | Starts the Architecture review, the session an Architect run opens with, in a worktree at the head of the Base branch. The line naming the focus is left out when the command gives none. | [architecture-review.md](architecture-review.md) |
| Security review | When enabled, runs one guidance review after a Ticket run's opening session or a Spec run's Spec review, before Delivery pushes and enters the Repair loop. Each Ticket run and Base fix gets one too. Introduced findings, refusals or incomplete reviews hold Self-merge. | [security-review.md](security-review.md) |
| Security audit | Starts the report-only Security audit in a throwaway worktree at origin's Base branch head. The threat-model line is included when a conventional document exists; artifacts stay under the repository's audit root. | [security-audit.md](security-audit.md) |
Expand Down
5 changes: 4 additions & 1 deletion prompts/bug-continuation-pr.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,17 @@

# Bug Ticket run, Continuation with an open pull request

Diagnoses a bug before continuing its open pull request. A not reproduced ending leaves the existing PR unmerged and hands the issue back for information.
Diagnoses a bug before continuing its open pull request. When the Issue branch is ahead of the Base branch, the prompt names their merge base and reproduction happens there. A not reproduced ending leaves the existing PR unmerged and hands the issue back for information.

```
/thirdshift-diagnosing-bugs <Issue URL>
Use the `thirdshift-diagnosing-bugs` skill before changing code.
Follow the skill to one of its two endings. Its not reproduced ending replaces the implementation steps below.
Completion lines (the final message's last line): reproduced: `Bug reproduced: fixed`; not reproduced: `Bug not reproduced: <comment URL>`.

This Continuation's Issue branch is ahead of the Base branch. Reproduce at the merge base, then check the fix on the branch.
Merge base commit: `<merge base commit>`.

Implementation after reproduction:
/thirdshift-implement <Issue URL>

Expand Down
5 changes: 4 additions & 1 deletion prompts/bug-continuation.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,17 @@

# Bug Ticket run, Continuation without a pull request

Diagnoses a bug in a Continuation with no pull request before changing code. A not reproduced ending hands the issue back for information without a PR.
Diagnoses a bug in a Continuation with no pull request before changing code. When the Issue branch is ahead of the Base branch, the prompt names their merge base and reproduction happens there. A not reproduced ending hands the issue back for information without a PR.

```
/thirdshift-diagnosing-bugs <Issue URL>
Use the `thirdshift-diagnosing-bugs` skill before changing code.
Follow the skill to one of its two endings. Its not reproduced ending replaces the implementation steps below.
Completion lines (the final message's last line): reproduced: `Bug reproduced: fixed`; not reproduced: `Bug not reproduced: <comment URL>`.

This Continuation's Issue branch is ahead of the Base branch. Reproduce at the merge base, then check the fix on the branch.
Merge base commit: `<merge base commit>`.

Implementation after reproduction:
/thirdshift-implement <Issue URL>

Expand Down
2 changes: 1 addition & 1 deletion site/architecture/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -226,7 +226,7 @@ <h1>Architecture</h1>
<li><b>Pre-flight checks</b> stop a Ticket run before anything is created: the Issue URL must match the clone's <code>origin</code>, the issue must be open, and the Base branch must be on <code>origin</code>.</li>
<li><b>The Claim</b> labels the issue <code>in-progress</code>, so the issue list shows what the factory is working on.</li>
<li><b>A Worktree</b> gives the Ticket run its own checkout beside your clone, so yours is never touched.</li>
<li><b>Delivery</b> starts the implement session. On issues labelled <code>bug</code>, diagnosis comes first: a reproduced bug gets a failing regression test and fix; an unreproduced bug ends successfully with triage notes and <code>needs-info</code>, without PR delivery. Security fixes and Base fixes keep their own flow. Otherwise Delivery pushes the branch and checks that the pull request exists and targets the Base branch. thirdshift, not the agent, marks it ready.</li>
<li><b>Delivery</b> starts the implement session. On issues labelled <code>bug</code>, diagnosis comes first: a reproduced bug gets a failing regression test and fix; a Continuation whose Issue branch is ahead of the Base branch reproduces at their merge base, and a fix already on the branch goes on to review and the pull request; an unreproduced bug ends successfully with triage notes and <code>needs-info</code>, without PR delivery. Security fixes and Base fixes keep their own flow. Otherwise Delivery pushes the branch and checks that the pull request exists and targets the Base branch. thirdshift, not the agent, marks it ready.</li>
<li><b>Keeping it green</b> merges the Base branch in and watches CI. A conflict or the branch's own red check starts a Repair, at most 5 a Ticket run.</li>
<li><b>The Self-merge</b>, when asked, merges exactly the head commit whose CI thirdshift watched.</li>
<li><b>Cleaning up</b> removes the Worktree. A <b>Failed ticket run</b> pushes its work first and turns the pull request back into a draft.</li>
Expand Down
2 changes: 1 addition & 1 deletion site/how-it-works/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ <h1>How thirdshift works</h1>
<summary class="sec-head"><p class="eyebrow">01 / The human handoff</p><h2 id="handoff-title">Start with work you can describe</h2></summary>
<div class="guide-content" id="handoff">
<p>The <strong>Day shift</strong> is you: settle what should change, what success looks like, and what is out of scope. Put that in a GitHub issue. One session's worth of work can stand alone; a larger <strong>Spec</strong> is an issue with <strong>Tickets</strong> as GitHub sub-issues. We'll follow a standalone issue first.</p>
<p>For issues labelled <code>bug</code>, a fresh Ticket run or Continuation uses <a href="/prompts/#skill-thirdshift-diagnosing-bugs"><code>/thirdshift-diagnosing-bugs</code></a> before changing code. It captures a failing regression test, then fixes it. If the bug cannot be reproduced, it comments with triage notes, replaces <code>ready-for-agent</code> with <code>needs-info</code> and ends successfully with the comment link, without opening or merging a pull request. Security fixes and Base fixes keep their own flow.</p>
<p>For issues labelled <code>bug</code>, a fresh Ticket run or Continuation uses <a href="/prompts/#skill-thirdshift-diagnosing-bugs"><code>/thirdshift-diagnosing-bugs</code></a> before changing code. A fresh run, or a Continuation with nothing on the Issue branch beyond the Base branch, reproduces on that checkout. A Continuation whose Issue branch is ahead of the Base branch reproduces at their merge base, then checks the fix on the branch: a bug there, with the fix already on the branch, goes on to review and the pull request. Otherwise it captures a failing regression test, then fixes it. If the bug cannot be reproduced at that checkout, it comments with triage notes, replaces <code>ready-for-agent</code> with <code>needs-info</code> and ends successfully with the comment link, without opening or merging a pull request. Security fixes and Base fixes keep their own flow.</p>
<figure class="guide-diagram grid-bg">
<figcaption>Human intent becomes the agent's brief</figcaption>
<ol class="guide-flow">
Expand Down
2 changes: 1 addition & 1 deletion site/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ <h1 class="misreg">Your issues become pull requests overnight.</h1>
<div class="shift third"><h3>Third shift</h3><p class="who">Agents, with headless copies of the same skills</p>
<ol class="chain"><li><a href="/prompts/#skill-thirdshift-implement">/thirdshift-implement</a></li><li><a href="/prompts/#skill-thirdshift-code-review">/thirdshift-code-review</a></li><li><a href="/prompts/#skill-thirdshift-pr">/thirdshift-pr</a></li></ol>
<p>thirdshift takes an Issue URL: one issue starts a Ticket run; an issue with sub-issues starts a Spec run. Its Factory skills, adapted to run with no human in the loop, implement the issue with <code>/thirdshift-implement</code>, review the work with <code>/thirdshift-code-review</code> and write the pull request with <code>/thirdshift-pr</code>.</p>
<p>Issues labelled <code>bug</code> first use <a href="/prompts/#skill-thirdshift-diagnosing-bugs"><code>/thirdshift-diagnosing-bugs</code></a> to reproduce the reported failure and write a failing regression test before fixing it. If it cannot reproduce the bug, the Ticket run leaves triage notes and <code>needs-info</code> on the issue, ending successfully without a new pull request. Security fixes and Base fixes keep their own flow.</p>
<p>Issues labelled <code>bug</code> first use <a href="/prompts/#skill-thirdshift-diagnosing-bugs"><code>/thirdshift-diagnosing-bugs</code></a> to reproduce the reported failure and write a failing regression test before fixing it. A Continuation whose Issue branch is ahead of the Base branch reproduces at their merge base, and a fix already on the branch still goes on to review and the pull request. If it cannot reproduce the bug, the Ticket run leaves triage notes and <code>needs-info</code> on the issue, ending successfully without a new pull request. Security fixes and Base fixes keep their own flow.</p>
<p class="more"><a href="/prompts/">Read every prompt and skill the agents get →</a></p></div>
</div>
</div>
Expand Down
24 changes: 21 additions & 3 deletions site/prompts/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -285,13 +285,16 @@ <h1 class="misreg">Prompts and skills</h1>
<details class="fold">
<summary><h3 id="prompt-bug-continuation-title">Bug Ticket run, Continuation without a pull request</h3></summary>
<div class="job-body">
<p>Diagnoses a bug in a Continuation with no pull request before changing code. A not reproduced ending hands the issue back for information without a PR.</p>
<p>Diagnoses a bug in a Continuation with no pull request before changing code. When the Issue branch is ahead of the Base branch, the prompt names their merge base and reproduction happens there. A not reproduced ending hands the issue back for information without a PR.</p>
<p class="sent-by">Sent by <a href="/#unit-2">2 · M · Implement</a></p>
<pre class="job-text"><code>/thirdshift-diagnosing-bugs <mark class="ph">&lt;Issue URL&gt;</mark>
Use the `thirdshift-diagnosing-bugs` skill before changing code.
Follow the skill to one of its two endings. Its not reproduced ending replaces the implementation steps below.
Completion lines (the final message's last line): reproduced: `Bug reproduced: fixed`; not reproduced: `Bug not reproduced: &lt;comment URL&gt;`.

This Continuation's Issue branch is ahead of the Base branch. Reproduce at the merge base, then check the fix on the branch.
Merge base commit: `<mark class="ph">&lt;merge base commit&gt;</mark>`.

Implementation after reproduction:
/thirdshift-implement <mark class="ph">&lt;Issue URL&gt;</mark>

Expand Down Expand Up @@ -325,13 +328,16 @@ <h1 class="misreg">Prompts and skills</h1>
<details class="fold">
<summary><h3 id="prompt-bug-continuation-pr-title">Bug Ticket run, Continuation with an open pull request</h3></summary>
<div class="job-body">
<p>Diagnoses a bug before continuing its open pull request. A not reproduced ending leaves the existing PR unmerged and hands the issue back for information.</p>
<p>Diagnoses a bug before continuing its open pull request. When the Issue branch is ahead of the Base branch, the prompt names their merge base and reproduction happens there. A not reproduced ending leaves the existing PR unmerged and hands the issue back for information.</p>
<p class="sent-by">Sent by <a href="/#unit-2">2 · M · Implement</a></p>
<pre class="job-text"><code>/thirdshift-diagnosing-bugs <mark class="ph">&lt;Issue URL&gt;</mark>
Use the `thirdshift-diagnosing-bugs` skill before changing code.
Follow the skill to one of its two endings. Its not reproduced ending replaces the implementation steps below.
Completion lines (the final message's last line): reproduced: `Bug reproduced: fixed`; not reproduced: `Bug not reproduced: &lt;comment URL&gt;`.

This Continuation's Issue branch is ahead of the Base branch. Reproduce at the merge base, then check the fix on the branch.
Merge base commit: `<mark class="ph">&lt;merge base commit&gt;</mark>`.

Implementation after reproduction:
/thirdshift-implement <mark class="ph">&lt;Issue URL&gt;</mark>

Expand Down Expand Up @@ -1058,9 +1064,21 @@ <h1 class="misreg">Prompts and skills</h1>

Redact secrets from commands, output and captured artifacts. Build loops against environment variables so credentials stay out of the evidence.

## Where to reproduce

The Session prompt says which checkout the bug is reproduced on.

When it names a merge base, this is a Continuation whose Issue branch already has commits beyond the Base branch. Reproduce at that merge base. Use the commit the prompt names; do not choose another from git history. Then check the fix on the Issue branch.

- The bug reproduces at the merge base and the branch already fixes it: take the reproduced ending. Do not rewrite the fix. Continue to the Session prompt's implementation steps, including review and the pull request.
- The bug reproduces at the merge base and the branch does not fix it: take the reproduced ending, finish the fix, then continue to those steps.
- The bug does not reproduce at the merge base: take the not reproduced ending. A passing check on the branch is not enough to hand the issue back.

A fresh bug Ticket run, or a Continuation whose Session prompt names no merge base, reproduces against the checkout you are in.

## 1. Build a tight feedback loop

Spend most of the diagnosis effort here. Read enough code to find a seam that reaches the reported symptom, then run an unattended pass/fail command against the current code. Prefer a focused test; a CLI fixture, HTTP replay, headless browser script or throwaway harness can help establish reproduction. Assert the exact reported symptom, rather than simply checking that execution succeeds. A setup or compilation failure is not reproduction.
Spend most of the diagnosis effort here. Read enough code to find a seam that reaches the reported symptom, then run an unattended pass/fail command against the checkout named under Where to reproduce. Prefer a focused test; a CLI fixture, HTTP replay, headless browser script or throwaway harness can help establish reproduction. Assert the exact reported symptom, rather than simply checking that execution succeeds. A setup or compilation failure is not reproduction.

Tighten the loop: narrow inputs, pin time and seeds, and remove unrelated setup. For intermittent bugs, repeat the trigger and establish a reproducible failure rate. Record the command, output and conditions. Proceed only once the loop actually fails for the reported reason. If it does not, take the not reproduced ending.

Expand Down
Loading
Loading