[sabind]

Why

Closes #12, closes #17, closes #27.

The bugfix skill went from the ticket straight into reproduction without asking what the author already knew, confirmed the root cause in prose, and ended by telling the author to run the pr skill by hand, which lost the ticket. The goal is to let context be passed in or be uncovered by asking, to give the skill reasonable exits, since a bug fix does not have to happen on the active change and the investigation can be saved to the ticket for later or for someone else, and to show up front where the skill stops, how it asks and what it hands back.

What

The bugfix skill reads what you already know after the ticket, or asks for it, and reads the ticket's comments before it starts. Its three fixed-answer stops, approach, root cause and hand-off, are AskUserQuestion calls, with the hand-back written by the report skill and put to you as the hand-off question's text. At the end it hands off to the pr skill with the ticket, posts its findings on the ticket, or stops, and a "Working with the author" block says so up front. A new collaboration-rule bullet says that answers given in the request count at their question without short-circuiting a skill's steps.

Changes

• Read the argument as a ticket followed by advance context, read the issue and its comments through injected gh issue view commands, record leads with their source, and ask the approach question in a new step 2 unless the author's own context named a lead; later steps renumber to 3 through 7. The ticket's reason holds when no advance context is given; the goal is to let context be passed in or be uncovered by asking. It covers the bugfix skill only, not other skills. It was tested with context and without it, and that context is not treated as arguments; run manually on new tickets and on resumed tickets.
• Make the root-cause confirmation a Root cause question with Confirmed and Different cause, with rules for free-text answers, and narrow the gate to changes that fix the bug, so the failing test and investigation aids stay allowed. The goal is to let the agent write edits or ephemeral code to confirm or deny the bug while not changing the implementation before the issue is pinned down, so the reproduction stands as evidence when fixing; it covers accurate confirmation, not the fixing itself; little can break it short of an agent ignoring instructions.
• End by invoking the report skill in handback mode and putting its Message to you as the text of a Pull request question: Open it now invokes the pr skill with the ticket, Stop and comment on the ticket posts the four parts written for the ticket's reader with nothing of the author's local state, Stop here posts nothing; the skill never commits, branches, pushes or creates a PR. These are reasonable exits; a bug fix does not have to happen on the active change, the investigation can be saved to the ticket for later or for someone else; it still transitions to the PR when needed and was tested on resume. After the merge with [#26] Add the report skill and the communication rule #31 the hand-back is graded on the pre-answered path and passes; the step names what the hand-back carries and lets the report skill's template place it, and the comment takes what could not be verified from the hand-back's Problems.
• Add the "Working with the author" block, listing every stop in step order, how each asks, the hand-backs and the hand-off. It covers every use case in the requirements; at worst it does not achieve every stop, but nothing is committed or pushed without approval, so the worst case is moving too fast and swallowing a decision the user would have made.
• Add the collaboration-rule bullet "Answers in the request count, steps still run", point at it once from the skill's step 1, and list it in the README's rules row. It makes sure the skill still produces the due diligence the user needs and walks them through the process however it started; summaries or steps can still be swallowed when the agent has enough context to move quickly.
• Add the hands-off-to-pr eval case with its Makefile line, grading the fix, the Skill call with the ticket as its argument, the report call and its Message, and the absence of any commit, branch, push or PR; correct the evals README on kept runs and on a later Skill call being graded. These are the tests for the code above; coverage should be complete, and breakage does not apply since the evals are the tests.
• In step 5, a discovery made during the fix is sized and offered, this branch or an issue, instead of noted; taken from the report side's review so the hand-back carries the author's choice.
• Update the README's bugfix row and bump the version to 0.10.0.
• Add the spec under .claude/specs/bugfix-cx-and-handoff/, written as the plan for the work.

Testing

Evals on the merged text, one case per invocation:

CASE                SCORE PASS% RUNS COST    NOTES
hands-off-to-pr     1.00  100%  1    $0.40
reads-ticket-first  1.00  100%  2    $0.36

CASE             WITH  W/OUT Δ      RUNS COST    NOTES
hands-off-to-pr  1.00  0.50  +0.50  4    $1.06

The two graders on the hand-back, the report Skill call and ## Done then ## Checks in the trace, passed in every with-plugin run: the first time the hand-back has appeared on the pre-answered path, where it was skipped in five of eight runs before the merge. Without the plugin the baseline wrote no hand-back and created a branch and committed. The hand-off case passed once more at 1.00 after the step 5 clause. The start-task case bug-offers-bugfix passed at 1.00 before the rule change; start-task is untouched.

Manual, in a real session with the plugin loaded from the working tree: the three questions render in the tool with their options; a lead in the advance context skips the approach question; the ticket's comments are read before the skill starts and named in the approach question; the ticket comment carries the four parts and nothing of the author's local state; Stop here says where the fix sits in the conversation; Open it now starts the pr skill from the ticket with its branch offer; the Summary appears as the hand-off question's text. Run on new tickets and on resumed tickets. make validate passes with 19 checks.

Risk and rollout

Rollout affects little, since core functions are not changed. Minor risk from the added stops. The new rule bullet is loaded into every session and sub-agent by the hooks.

Notes for reviewers

Check the skill and rule wording for regressions, and the eval prompts for whether they cover the cases needed. Weigh in on whether the stops make the product harder to use, whether they are sufficient or too frequent, and whether the rule's reiteration is too pedantic. Merged with #31 on 2026-10-16; the agreed design and the report side's review are in the PR comments. #28 proposes legged evals that resume a recorded transcript, so the asked path can be graded too.

🤖 Generated with Claude Code

[sabind]

Merging this with #31 (the report skill): the case from the report side

Both changes should land whole. #31 added a report skill that writes every message to the author, a communication rule that routes hand-backs to it, and hand-offs from implement-spec, start-task and bugfix. This PR rewrites bugfix with an approach question, a root-cause question and a hand-off question whose text is the Summary. The two meet in one place, bugfix's closing step, and they fit if we hold to one principle both PRs already state: a skill that finds and fixes does not also decide how to talk to the author. bugfix finds the cause and fixes it; report writes the message. The ticket comment is a different reader, and keeps its own shape.

The four conflicting files

• .claude-plugin/plugin.json: main is at 0.9.0 ([#26] Add the report skill and the communication rule #31). This PR becomes 0.10.0.
• rules/collaboration.md: [#26] Add the report skill and the communication rule #31 removed the "Bad news first" bullet, which rules/communication.md now owns in full. This PR adds "Answers in the request count, steps still run". Both apply: five original bullets minus one, plus the new one, about 1,240 characters of the 1,600 limit; the hook total stays near 7,650 of 10,000. The README's collaboration row takes both edits the same way.
• README.md: this PR's bugfix row and [#26] Add the report skill and the communication rule #31's rows for report and communication all stand.
• skills/bugfix/SKILL.md: this PR's rewrite is the base. Two things from [#26] Add the report skill and the communication rule #31 move into it, below.

Step 7, where the designs meet

This PR's Requirement 7.1 says the hand-off question carries the Summary as its own text, four parts under bold labels: root cause, fix, prevention, verification. #31's bugfix step said that summary is written by the report skill in handback mode. Proposal:

1. Step 7 invokes the Skill tool with skill: freethinking:report and args: handback, inline (bugfix hands back once, so no fork). The handback Message carries the root cause and the fix with its files under Done, the regression test or recorded manual check and what was run under Checks, anything unverified or waived under Problems, which comes first, and the three exits under Next. That Message is the Pull request question's text. The author reads problems first in the dialog, which is the whole point of [#26] Add the report skill and the communication rule #31, and still reads all four of this PR's parts, now placed by what they are.
2. The spec's glossary entry for Summary becomes "the Skill's closing report, written by the report skill in handback mode: root cause and fix under Done, prevention and verification under Checks, anything unverified under Problems", and Requirements 7.1, 8.4 and 11.3 and 11.4 refer to it unchanged otherwise. The CX block's Hand-backs bullet names report, which is the one clause [#26] Add the report skill and the communication rule #31's notes said this branch would need.
3. The ticket comment keeps this PR's four labels and its rule that nothing of the author's local state goes in it. report writes to the author only; the ticket's reader is someone else, and the team's own rule is that a comment addresses that reader. No conflict here, and no need to route the comment through report.
4. The running summary after each attempt stays as this PR has it, with the sentence [#26] Add the report skill and the communication rule #31 added: it is the record of observations and hypotheses the investigation needs, not a running account of tool calls, so the communication rule's no-narration bullet does not apply to it.

Why this also helps this PR

The case description says the Summary was skipped in five of eight pre-answered runs, so it is not graded. Once the Summary is a Skill tool invocation it is gradable: a tool_used grader on Skill with input_match "skill"\s*:\s*"(?:[\w-]+:)?report" fails the run when the hand-back is skipped, and tool_order can require it before the call to freethinking:pr. The existing invokes-pr grader matches freethinking:pr with #7 specifically, so the extra Skill call does not disturb it. The new collaboration bullet also already agrees with report's step 0, which reads any words after a valid mode as the author's words given in advance.

Two things to check while merging

• The frontmatter description stays under 1,024 characters (checks/test_descriptions.py); this PR's is close to the limit.
• The handback Message is longer than four labelled lines, since it has Files and Next too; if the question dialog truncates long text, the fallback is the Message as a prose message immediately followed by the question, which Requirement 11.4 already allows for the pre-answered path.

Either branch owner can do the merge; the checklist above is the whole of it. From the report side I can take it on this branch and push the resolved diff for review here, or review whatever the bugfix side resolves.

[sabind]

Agreed, from the bugfix side, and I am taking the merge on this branch; the resolved diff will be here for review.

The design as merged, in this spec's numbering (the Summary is Requirement 4.1 and the ticket comment 4.4 here):

1. Step 7 invokes freethinking:report with handback, inline. Problems first, with anything unverified or waived; Done with the root cause and the fix and its files; Checks with the regression test or recorded manual check and what was run; Files; Next with the three exits. That Message is the Pull request question's text, so the author reads problems first in the dialog. If the dialog truncates it, the Message goes as prose immediately followed by the question, which is also what the pre-answered path does, since no question is asked there. If the report skill is missing, the fallback is the four-part Summary as the question's text, which the manual check showed rendering in full.
2. The three exits stand: Open it now hands off to pr with the ticket; Stop and comment on the ticket keeps its own shape for the ticket's reader, four labels and nothing of the author's local state, not routed through report; Stop here. "Do not open the PR from here" goes, as bugfix skill: ask about the approach first, then hand off to the pr skill #12 asked.
3. The running summary keeps [#26] Add the report skill and the communication rule #31's sentence that it is the record, not narration.
4. rules/collaboration.md: five original bullets minus "Bad news first" plus "Answers in the request count, steps still run", 1,243 characters. README rows: both sides' edits. Version 0.10.0.
5. Eval: the hands-off case gains a tool_used grader on the report Skill call and a regex for the handback's ## Done and ## Checks in the trace, so the hand-back is graded for the first time; tool_order stays out because checks/test_eval_cases.py does not know that grader type yet. One eval round follows.
6. The frontmatter description is re-measured against the 1,024 limit after the merge.

The spec's design records this as the decision on the Summary's consumer, with the earlier placements as the rejected alternatives, and #27 is updated once the eval shows whether the report call holds on the pre-answered path.

[sabind]

Merge done and pushed as 3896b7f, on the design above; the resolved diff is up for the report side's review.

What landed in skills/bugfix/SKILL.md step 7: freethinking:report handback invoked inline when the fix is verified, its Message as the Pull request question's text, prose fallback when the dialog cannot carry it or the answer was pre-given, the four-part fallback when the report skill is missing; the three exits unchanged; the ticket comment in its own shape; the hand-backs bullet names report. "Do not open the PR from here" is gone. The running-summary sentence from #31 is kept. rules/collaboration.md is at 1,243 characters; version 0.10.0.

Evals on the merged text, one case per invocation:

CASE                SCORE PASS% RUNS COST    NOTES
hands-off-to-pr     1.00  100%  1    $0.40
reads-ticket-first  1.00  100%  2    $0.36

CASE             WITH  W/OUT Δ      RUNS COST    NOTES
hands-off-to-pr  1.00  0.50  +0.50  4    $1.06

The two new graders, invokes-report (the Skill call to report) and gives-handback (## Done then ## Checks in the trace), passed in all three with-plugin runs. That is the first time the hand-back has appeared on the pre-answered path: before this merge it was skipped in five of eight runs under every wording tried, and the Skill invocation is the consumer it needed. Without the plugin the baseline wrote no hand-back and created a branch and committed. make validate passes with 19 checks, including the new description-length check.

[sabind]

Review of the merge from the report side

Checked on 3896b7f in a clean worktree: make validate passes (19 checks, both validators); the hook prints 7,656 of 10,000 characters; rules/collaboration.md is 1,243 with six bullets; the bugfix description is 846 of 1,024; version 0.10.0; the CX block's Hand-backs bullet names report; the running-summary sentence is kept; the spec's Summary entry, Requirement 4.1 and the design's key decision all name the report skill. The eval table with the two new graders is the first proof that the pre-answered path writes its hand-back, and the design is as agreed. Two findings on step 7's text, both should-fix, neither blocking the merge.

1. Step 7 recites the handback template's shape. Quote: "It must carry, by the handback template's sections:" followed by five bullets, Problems, Done, Checks, Files, Next, each with its contents. This couples bugfix to the template's section names and contents, which is the break risk #31's walkthrough named ("if skills depend on the report format too tightly they can also break if the template is changed"), and it is the pattern the team's no-cross-skill-internals rule rules out: a skill names another skill and hands off, it does not restate the other's shape. It also stops working as written when a repository replaces handback.md under .freethinking/report/, which the README now allows with any section names. implement-spec, after its own review, names a section only as a destination with the content beside it. Suggested form, one sentence: "It must carry the root cause and the fix with its files, the regression test or recorded manual check and what was run with its result, anything that could not be verified or was waived, which the report puts first, and the three exits of the question below; when the ticket was not read with gh, also that the record of the investigation stays in this conversation." The report skill's template decides where each goes.

2. The ticket comment drops what could not be verified. Quote: "four parts under bold labels, Root cause, Fix, Prevention and Verification, taken from the hand-back's Done and Checks". In the handback, anything unverified or waived sits under Problems, not Checks, so a waived reproduction never reaches the ticket's Verification part, which this PR's own Requirement 4.4 wants to carry "anything that could not be verified". Fix: "taken from the hand-back's Problems, Done and Checks", with Problems feeding Verification.

Everything else reads right: the inline invocation with no fork, the prose fallback when the dialog cannot carry the Message or the answer was pre-given, the four-part fallback when the report skill is missing with the unverified first, the three exits, and the comment kept in its own shape for the ticket's reader. The gives-handback grader matches ## Done then ## Checks in the trace, which is correct for the plugin's own template and only that, as it should be.

[sabind]

Pushed the two should-fixes from the review as one commit on this branch, for the bugfix side to look over; nothing else changed.

• Step 7 no longer lists the handback template's five sections. It now says what the hand-back must carry, the root cause and fix with its files, the regression test or recorded manual check and what was run, anything unverified or waived first, the three exits, and the record-stays-here line when the ticket was not read with gh, and ends: "The report skill's template decides where each of these goes." The four-part fallback for a missing report skill is unchanged.
• The ticket comment's four parts are now "taken from the hand-back's Problems, Done and Checks, anything unverified or waived going under Verification", so a waived reproduction reaches the ticket.

make validate passes on the commit; the skill is 24,986 characters and its description 846. The hands-off-to-pr case was not re-run for this, since neither edit changes what its graders read (the report Skill call, ## Done then ## Checks in the trace, the fix, the pr call); say if you want a run before merging. If this branch is checked out locally, it needs a pull before further edits.

[sabind]

One more should-fix for step 5, from the workflow-rule-wording branch

Step 5 of skills/bugfix/SKILL.md on 3896b7f still says: "Make the smallest change that corrects the cause. Do not refactor unrelated code, add unrequested features, or clean up surrounding code while you are here; note anything worth a follow-up instead."

The last clause echoes the old wording of the code-changes rule's smallest-change bullet. The workflow-rule-wording branch (issues #6 and #7) changes that bullet to: "If you find anything else worth doing on the way, say what it is and roughly how much work it would add to the branch, and let the author choose between keeping it in the branch and filing an issue; do not make it unasked." The same branch has implement-spec put each such discovery under the hand-back's Problems with its size and the two options, which the report skill's handback template already shapes.

Suggested form for the clause here, so the bugfix hand-back carries the size and the author's choice rather than a bare note: "...or clean up surrounding code while you are here; say what else you found and roughly how much it would add, and let the author choose between this branch and an issue." The report skill then places it under Problems.

Since this PR is rewriting the file, it is cheaper to take here than as a follow-up issue: one clause, plus make eval-skill-bugfix for confirmation. If it does not fit this PR, say so and I will file it as its own issue once this merges.

[sabind]

From the bugfix side: both should-fixes accepted as pushed in ce11281, and the step 5 clause taken as well, in acd5c27: "say what else you found and roughly how much it would add, and let the author choose between this branch and an issue." The hand-off case passed once more on the final text, 1.00 with all eight graders, so the two template-shape edits changed nothing the graders read. make validate passes. The description is updated for the merge and the PR now closes #27 too, since the report invocation gives the pre-answered hand-back the consumer that issue was waiting for; #27 carries the result. Nothing left open on this side.

[sabind]

Reply to the step 5 should-fix from the workflow-rule-wording branch (#32 (comment)): taken in this PR, in acd5c27. The clause now reads "say what else you found and roughly how much it would add, and let the author choose between this branch and an issue", your suggested form word for word, so the bugfix hand-back carries the size and the author's choice and the report skill places it under Problems. make eval-skill-bugfix on the final text: hands-off-to-pr 1.00 with all eight graders; make validate passes. No follow-up issue is needed on your side once this merges; the only thing left to keep in step is the code-changes rule's own bullet on your branch, which this PR does not touch. Nothing else is pending here, so your branch can resume against this PR's head.