feat(han-core): add the pairing collaborative working mode - #179
Merged
Conversation
Compiles the research wave into docs/research/collaborative-output-style.md: 41 sources across Claude Code harness mechanics, collaborative-pairing prior art, and the Han codebase. Validation section is a placeholder pending the adversarial pass.
…research Ten validation findings, three of which changed the recommendation: - V1: the single-style constraint was asserted with no source; now cited to A1 and labeled as inferred from the documented settings schema. - V3: the readability precedent did not match what O2 proposed. readability-guidance is invoked automatically by 27 skills, not by hand, so O2 now requires wiring the companion skill the same way. - V4: adds O8, building the loop into the implementation skills directly. Also corrects the tdd stopping points, the operator-escalation-rule scope, and flags the instruction-stacking number as an extrapolation.
…search Runs the readability-editor over the report's prose regions and fixes the remaining self-check failures: splits over-long sentences, drops a blocklisted word, glosses "startup hooks" at first use in the Summary, and gives several paragraphs a single idea each. Citation identifiers, evidence labels, the Sources table, and every figure survive unchanged.
The operator accepted an opt-in workflow and declined to wire tdd or any other skill into this mode. That withdraws the always-on requirement, which was the only job the output style was doing, so the design collapses to a single skill carrying the whole loop. Dropping the style also retires the report's largest open question: the contradiction between Anthropic's docs and its own repo over the Explanatory and Learning styles only ever decided whether the style should have been a hook. Confidence rises to High for the mechanism, and stays Medium for the pacing details, which still have no outcome data behind them. Validation findings are preserved as written; they record how the earlier recommendation was tested, not the conclusion it reached.
No ticket exists, so the operator's typed request is the boundary. Quotes the three decisions verbatim: the original collaborative-loop goal, the choice of an opt-in workflow over forcing tdd into the mode, and the naming plus the opt-in tdd flag. Direction of travel is unanswered pending the confirmation turn.
All four named skills stay; nothing is being replaced. pair-with-me borrows code-walkthrough's pacing without changing it, and tdd's flag leaves existing invocations untouched. Notes the operator's follow-up question about which other skills should gain the flag.
The operator established that the mode is not specific to writing code: an API design pairing produces a decision rather than code, an open-ended pairing has no backing skill at all, and 'pair with me on implementing' must not assume tdd over refactoring over prototyping. The front door does not choose the discipline. Also records that the widening reopens the input to the no-output-style decision, since a mode covering any work has a larger surface than a code-only one. That decision stands until the operator revisits it. Planning is paused for a narrow research pass on what makes a reviewable stopping point when the work is not code.
Compiles a four-agent wave into docs/research/non-code-chunk-boundaries.md: 54 sources across design and decision review practice, editorial and knowledge-work practice, review psychology, and the Han codebase. Headline finding: stop where the kind of feedback changes, not where a word count is hit, with structure reviewed before surface. Corroborated by two national editing bodies, two peer-reviewed composition studies, and design practice in an unrelated field. Second finding, which changes the walkthrough design: passively presented explanations do not reduce over-reliance and can increase it. Validation section is a placeholder pending the adversarial pass.
…unk-boundary research Nine validation findings, three of which changed the report: - V1: the prose unit needed a finished draft before its first review, which is the exact precondition used to reject a competing option. Rewritten to one rung of a fidelity ladder, keeping the order of concerns the editorial evidence establishes while dropping that precondition. - V2: the coding-standard skill was described as running stop-free when it has a mid-draft gate on the globs its standard governs. - V3: a third in-repo review pattern was gathered as evidence and never used. Added as O7, alongside O8 for the no-chunking case. Also softens the walkthrough finding, whose two controlled studies share a research lineage this report demands independence for elsewhere.
Twelve decisions: five settled from the two research reports, seven from operator input across this session and the last. Three escalations this session: - The skill moves to han-core. The mode covers prose and decisions as well as code, so reaching into the coding plugin to pair on a stakeholder email reads wrong. - Feedback condemning the piece in hand is fixed in place and re-shown, with feedback reaching outside the piece reopening the chunk plan instead of being patched in. - The guard against nodding through applies only where a mistake is expensive to undo, because the study behind it also measured a satisfaction cost. No technical-notes file: no mechanic qualified as both load-bearing and not discoverable from the repository.
Three reviewers ran in parallel: junior-developer over the whole artifact set, user-experience-designer over the interaction model, and information-architect over routing, placement, and doc surfaces. Thirty-three findings, several raised independently by two reviewers and merged. Two escalations, both on findings that unsettled a recorded decision: - The skill stays in han-core, with tdd, refactor, and design-an-api treated as optional. han-coding already depends on han-core, so requiring it back would close a cycle; making the backing skills optional keeps han-core's "depends on no other Han plugin" invariant literally true. - design-an-api gains the collaborative flag. Pairing on an API design is a founding example, and sorting past that skill would have handed over a hand-rolled loop in place of its four rounds. The largest evidence fix: the guard against nodding through asked for your read after the piece was built. Both studies behind it work by having the person commit before the answer exists, so the ask now precedes the build. Also: an ordered sorting test with a first-match tie-break, the sort result disclosed in the plan, a readable feedback record, position and queue depth at every stop, a middle gear between full ceremony and no review, both sides of four routing collisions, and the stop softened from a guarantee to a directive because nothing can enforce it. Nine new decisions, three rewritten. Three open items remain, one blocking.
Classified all twenty-one decisions in one pass, after the review round rather than at draft time, because two promotion signals could not exist until findings arrived. All twenty-one are full; two only qualified once their empty driving-findings fields were filled. Repaired the reverse cross-reference direction, which was unsound while the forward direction was clean: two decisions claimed spec sections that never linked to them, and three spec sections carried no decision links while nine decisions claimed them. Five claims failed the evidence standard and were corrected. Two were mine: "each of those four sentences names another skill's strongest trigger word" is true of three, and a fix for an unsupported claim about silent approvals substituted a second unsupported claim about what they signal. Also softened an overstated corroboration claim, added a known gap for a single-sourced interruption figure, and rewrote a deferral that still contradicted the widened flag decision. One review resolution had been recorded but never applied to the spec.
The specification grew by roughly half during the review round, which left sections drafted at different times sitting next to each other. The editor reordered two sections that led with context before arriving at their point, split about a dozen sentences running past thirty words, converted several passive constructions, and removed two blocklisted words this author had written. Tables, headings, and all citation identifiers are byte-for-byte unchanged. Fact-preservation ledger reports no fact required blurring, including the three confidence ratings, the directive-not-a-guarantee framing of the stop, and the two measured checklist percentages.
All three items the specification opened are now closed as decisions with their rejected alternatives, so nothing is left open. The stopping convention becomes a canonical rule file owned by han-core. Han's existing escalation rule assumes a single stop per run, because it exists to minimize interruptions in autonomous work; this mode treats stopping as the deliverable. Five skills consume the handoff contract, which is what clears the bar for a shared file rather than inline text. Running the widened flag test across every skill in the plugins not ruled out added two: iterative-plan-review, which surfaces a disagreement between reviewers and then continues without waiting, and plan-implementation, which holds its only question until every round is finished. Both fail the same way tdd did. The rest fail in four groups, recorded in D10. The skill is renamed from pair-with-me to pairing, following the suite's gerund naming convention. "Pair with me on" stays as description wording, so nothing about how a person asks for the mode changes. This overrode my recommendation, which was to keep the original name and record an exception. The rename does not fix the scent problem, and D23 says so. Operator quotes in the boundary record are untouched; every amendment sits beside the quote it qualifies.
…covery Three passages had not caught up with the last two escalations, because an earlier find-and-replace ran against text the readability editor had since reworded. The surfaces list still said three skills gain the flag and had lost its rule-file item entirely, leaving the numbering skipping from two to four. The coordinations paragraph still said three skill rows. The YAGNI deferral still described a survey that has since been re-run and widened, and pointed at an open item that no longer exists. The decision log was unambiguous throughout, so these are clerical rather than design changes. Discovery notes for the implementation round record the tech stack, the absent coding standards, the single ADR, every surface confirmed to hold stale text, and five explicit gaps. Two are worth calling out: nothing in this repository can verify a skill's behavior or check that a description routes correctly, and the two skills with the highest ninety-day churn are both late additions to the flag list.
Three specialists in one round: structural-analyst on dependency direction, test-engineer on a feature nothing in this repo can test, and junior-developer on whether any of it is buildable as written. Twenty merged claims, eleven decisions, one escalation. The finding that shaped the build: three of the five flagged skills already carry an `arguments` key and branch on a mode selector passed at invocation. So the flag travels as an argument and no skill names the mode in its own text, which matters because the name already changed once. Verified directly against all five. The composition guidance settled the load-bearing question the generalist could not answer from the repo. Orchestration composition is supported, the caller stays thin, and the moment after a sub-skill call is when the caller most often stops. So the skill owning the boundary performs the stop, and the shared rule file is what makes every stop look alike. Two things removed rather than built. No plugin-detection script: nothing in the suite detects a sibling plugin, and naming the intended skill in the plan then reporting a failed invocation satisfies the same commitment. No prose snapshot test: the four files it would guard changed 22, 15, 12, and 8 times in ninety days, so it would fire on churn far more often than on a regression. One measured constraint that would have bitten mid-build: code-walkthrough has 69 characters left under the 1024 cap and needs a clause twice that long, so its description gets tightened before the clause goes in. Three stale passages in the spec corrected, one of them mine from the correction pass an hour earlier.
Two things I recorded but never landed. D-11, the operator's answer on prose granularity, existed in the decision log and the escalation register with no plan section carrying it, so only ten of eleven anchors were live. And the plan claimed seven mechanical checks while listing six; the missing one was the byte-equality check on the vendored rule copies, which is the only automated guard on the drift D-4 accepts as its cost. Four evidence corrections, three of them mine: - D-2 cited the thin-orchestrator rule as support when the design runs against it. This mode carries a plan, a feedback record, and the person's position across every stop, which is the opposite of thin. Now recorded as a named risk whose mitigation is the written record the spec already commits to. - Neither of the guidance's working examples has a sub-skill that ends its turn mid-run and resumes under its own instructions, which is exactly what the flag asks for. The round recorded that as unverified; the plan did not carry the disclosure. Both do now. - D-5 misstated its own rule. The question tool is barred from every skill's allowed-tools, not only a parent's, and only one backing skill calls it. - The plan attributed confidence ratings to the spec that the spec does not make. Also: design-an-api has 3 commits in ninety days, not zero. The discovery table had a cutoff and I read absence as none. Summary replaced with the template's Sources and Plan Records plus Recommendation, which closes a real gap: the plan now names which spec decisions it inherits.
…plan Synthesis rewrote several sections late, which left uneven prose behind. The editor split nine paragraphs carrying two ideas apiece and eight sentences running past thirty words, converted two heavily nested semicolon lists into bullets, removed a stale idiom and two blocklisted words, and glossed "backing skill" at first use from language already in the draft. Fact-preservation ledger reports every hedge intact: the unverified disclosure about a skill resuming mid-run, the statement that one guidance rule cuts against this design rather than supporting it, all six character headroom figures, and the note that the reversibility criterion is authored here rather than lifted. The editor also flagged that a churn count I asked it to preserve does not appear in this file. It is in D-3's evidence in the decision log; my constraint list mixed facts from both. It was right to flag rather than invent it. All 13 links and every citation identifier byte-for-byte unchanged.
Phase 1 of the pairing plan, and the only phase that lands on its own: nothing consumes it yet, so it makes no existing statement false. It fixes the four things five separate edits would otherwise each answer differently: how a skill detects the flag, what a stop presents and in what order, when the pre-build ask fires and what makes a choice expensive to walk back, and what to do with the answer. The reversibility test is authored here rather than lifted. The framework behind it separates reversible from irreversible decisions and supplies no way to tell them apart, so the file says the criterion is provisional and names the two ways it can be misapplied. Vendored byte-identical into han-coding and han-planning, matching how the config, evidence, and YAGNI rules already work. The canonical copy states its own vendoring status in a line that copies verbatim, so the copies stay byte-equal.
Phases 2 and 5 of the plan. The skill sorts the work with an ordered first-match test, proposes where it will stop, asks before building any piece the plan marked expensive to walk back, builds one piece, presents it, and ends the turn. The flag reaches backing skills as a named argument, so no skill names pairing in its own body. That was the point: the name already changed once. Seven descriptions now disambiguate in both directions, which the guidance requires because one-way disambiguation leaves a gap a request falls through. The five flagged skills each say they run to completion without pausing and name pairing as the way to review as it goes. code-walkthrough draws the line the two share vocabulary over: it paces through code that already exists, pairing builds work while pacing you through it. code-walkthrough had 69 characters of headroom against a clause twice that long, so its description was tightened first. It now sits at 904 with 120 free. Every description measured under the 1024 cap: pairing 929, tdd 961, design-an-api 978, refactor 836, iterative-plan-review 656, plan-implementation 617. AskUserQuestion is deliberately absent from allowed-tools. The guidance bars it from every skill, and a parent's rules stack onto the skills it calls, so declaring it here would silence the questions design-an-api asks underneath.
Phases 3 and 4. One short paragraph per skill at the boundary it already has, purely additive: 33 lines across five files, no frontmatter changed. D-1 said the flag would travel as a named argument, and that did not survive contact with the code. All three skills carrying `arguments: size` already use the second positional slot for free text — the goal and interface, the plan path, the specification path — so a second named positional would collide with the subject the person types. D-1's own known gap anticipated this and named the fallback, which is what shipped. The fallback is better than the original on two counts beyond avoiding the collision. Stating an override in the invocation is what the composition guidance prescribes. And tdd and refactor already gate when a request asks to review before implementation, so the flag extends a mechanism they have rather than adding a parallel one. That also answers OI-1: a pairing invocation does trip the existing review-first exception, and that is intended. Someone typing the same request directly gets the same behavior, consistent with what those skills already promise. design-an-api gets one paragraph governing all four of its dispatch rounds rather than four separate edits, and its two existing human gates are untouched.
Completes phase 2. The coverage rule requires a skill's operator manual to land with the skill rather than as a follow-up. Carries the four things the SKILL.md deliberately leaves out because they are reader-facing rather than process: why the reasoning does not lead at a stop, why the ask comes before the build, how the prose ladder scales, and what is not settled. The last of those names the two provisional parts, the per-kind units and the authored reversibility test, so an operator does not read them as firmer than the research supports. All relative links verified to resolve.
Branch-mode sweep over the 21 files this branch changed, mapping to seven skills plus the index surfaces. The new skill existed with a long-form doc and nothing pointing at it. It now appears in the skills index, the han-core front door, the project map, the workflow diagrams, the plugin index, the root README, and the concepts page. han-core stopped being what it said it was in five places. Its front door now separates the two kinds of thing it carries: material other plugins consume, and one working mode you invoke directly. The plugin index also promised an install with "no other skills", which stopped being true. Six boundaries were one-way. pairing named all six siblings and none named it back, so each gained a reverse link phrased for what that skill specifically gains. code-walkthrough gets the sharper version, since the two share their whole pacing vocabulary. In both workflow diagrams pairing is drawn as a dotted "drives" edge rather than a solid arrow, because it wraps those skills rather than chaining after them. One count violation removed, mine: a doc-map entry said "the five skills that hand control back" while naming all five in the same sentence.
mxriverlynn
changed the title
Step 2 sorted the whole request as one thing, so a request holding two asks produced one kind, one set of boundaries, and one uninterrupted run through both. A run asked to apply a code change and then help draft a reply about that same code went from the edit straight to the reply with neither reviewed. Splitting is now its own step ahead of the sort. A concern is one thing the person asked for with its own deliverable; concerns run in sequence, no piece spans two, and an ambiguous split resolves toward splitting. Changing code and understanding or answering a question are always separate, with no judgment call available. The sort, the plan, and the loop follow from that: each concern sorts independently, the plan names the concerns and their order, and a stop that closes a concern says so and names what comes next.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
/han-core:pairing, a collaborative working mode. It builds your work in reviewable pieces and hands each one backbefore starting the next, so you steer while the work happens instead of reviewing a finished result. It covers code,
design decisions, and writing alike.
Five existing skills gain an opt-in flag so they return control at the boundary each already has, and a new shared rule
file defines what a stop presents so a stop means the same thing whichever skill performed it.
How it works
You say what to pair on. The mode sorts the work with an ordered first-match test, proposes where it will stop and why,
builds one piece, hands it back with things you can check, and ends the turn. Your feedback goes into a written record
before it is acted on, so a correction given at the second stop still applies at the seventh.
For a piece the plan marks as expensive to walk back, it asks what you expect before it builds. Declining is a
complete answer.
What changed, by area
New in
han-coreskills/pairing/SKILL.mdand its operator manualreferences/collaborative-stop-rule.md, vendored byte-identical intohan-codingandhan-planningModified: five skills gain the flag —
tdd,refactor,design-an-api,iterative-plan-review,plan-implementation. One short paragraph each at the boundary they already have, 33 purely additive lines, nofrontmatter changed. An ordinary invocation of any of them is unchanged.
Modified: seven descriptions now disambiguate in both directions. The delegating relationship has no precedent in
the suite, because this mode runs the very skills it competes with, so both sides state it.
Modified: thirteen documentation surfaces.
han-corestopped being what it said it was in five places, and theplugin index promised an install with "no other skills," which stopped being true.
Design decisions worth reviewing
Two research reports back this, both adversarially validated. The specification carries 23 decisions and the
implementation plan 11, each with rejected alternatives.
han-corewith its backing skills optional.han-codingalready depends onhan-core, sorequiring it back would close a cycle. Optional keeps the no-dependencies invariant literally true.
not survive contact: all three skills carrying
arguments: sizealready use the second positional slot for free text.The fallback the plan had named is what shipped, and it reuses a gate
tddandrefactoralready have.cost, so the friction is spent where reversal is expensive rather than at every stop.
assistant's explanation does not reliably make a reviewer more careful and can make them less so.
What is not verified
Routing. Nothing in this repository can check that a description routes a request correctly. The specification
commits to five phrasings landing on specific skills, and that ships unverified until someone runs them in a live
session with all three plugins installed. This is the most consequential unchecked thing here.
The seven mechanical checks the plan specifies are designed but not written.
Two things stay provisional by design. The per-kind piece units sit at Medium confidence in the research, and the
test for a choice being expensive to walk back was authored for this skill rather than drawn from any source. Both say
so in the rule file and the operator manual.
Not included
Version bumps. Three plugins gained user-visible behavior;
/han-releaseowns that.Review notes
The planning artifacts under
docs/plans/pairing-skill/and the research underdocs/research/are the reasoningtrail, not the deliverable. The shipped surface is the
han-coreadditions, the five flag paragraphs, the sevendescriptions, and the documentation sweep.