diff --git a/CLAUDE.md b/CLAUDE.md index f4345f39..a4f15636 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,7 @@ surfaces the first two, the inline `explanation-guidance` skill that surfaces th the `readability-editor` agent, and the `han-readability` output style that applies the first two to every turn of a session; it depends on nothing and every prose-producing plugin depends on it), `han-core` (the shared foundation: the specialist agent roster the rest of the suite dispatches — every shared agent except the `readability-editor`, the -`research-analyst`, and the `discussion-facilitator` — plus the `project-discovery` skill and the canonical rule files; depends on no other Han plugin), +`research-analyst`, and the `discussion-facilitator` — plus the `project-discovery` skill, the `pairing` collaborative working mode, and the canonical rule files; depends on no other Han plugin), `han-documentation` (the documentation skills: `project-documentation`, `architectural-decision-record`, and `runbook`; depends on `han-communication` and `han-core` and is bundled by the `han` meta-plugin), `han-research` (the pre-planning knowledge-work skills — `research`, `gap-analysis`, and `issue-triage` — plus the `research-analyst` @@ -80,14 +80,14 @@ han-plugin-builder skill: │ ├── output-styles/ # han-readability.md: the readability rule and writing voice distilled into a selectable output style (auto-discovered default location; no plugin.json field) │ ├── docs/ # In-plugin long-form docs: docs/skills/{name}.md + docs/agents/readability-editor.md + docs/output-styles/han-readability.md │ └── references/ # Canonical readability-rule.md + writing-voice.md + explanation-rule.md (owned here; no vendored copies elsewhere), beside a vendored config-rule.md -├── han-core/ # Core plugin: the shared specialist agent roster (all agents except readability-editor and research-analyst) + project-discovery (depends on no other Han plugin) +├── han-core/ # Core plugin: the shared specialist agent roster (all agents except readability-editor and research-analyst) + project-discovery + pairing (depends on no other Han plugin) │ ├── README.md # Light front door; skills and agents grouped by purpose │ ├── .claude-plugin/ │ │ └── plugin.json │ ├── agents/ # Agent definitions (.md with frontmatter) -│ ├── skills/ # project-discovery skill directory, with SKILL.md + references/ +│ ├── skills/ # project-discovery and pairing skill directories, each with SKILL.md (+ references/ where used) │ ├── docs/ # In-plugin long-form docs: docs/skills/{name}.md + docs/agents/{name}.md -│ └── references/ # Cross-skill reference files (yagni-rule.md, evidence-rule.md, config-rule.md — canonical copies) +│ └── references/ # Cross-skill reference files (yagni-rule.md, evidence-rule.md, config-rule.md, collaborative-stop-rule.md — canonical copies) ├── han-documentation/ # Documentation plugin: project-documentation, architectural-decision-record, runbook (depends on han-communication and han-core; bundled by the han meta-plugin) │ ├── README.md # Light front door + scent-line skills list │ ├── .claude-plugin/ @@ -110,14 +110,14 @@ han-plugin-builder skill: │ ├── agents/ # discussion-facilitator agent definition │ ├── skills/ # Planning skill directories, each with SKILL.md + references/ │ ├── docs/ # In-plugin long-form docs: docs/skills/{name}.md + docs/agents/discussion-facilitator.md -│ └── references/ # Both kinds: han-planning-owned canonical files (planning-boundary-rule.md, scope-justification-rule.md, operator-escalation-rule.md) beside vendored copies (yagni-rule.md, evidence-rule.md, config-rule.md). Each owned file opens by saying so; do not overwrite one in a re-sync sweep +│ └── references/ # Both kinds: han-planning-owned canonical files (planning-boundary-rule.md, scope-justification-rule.md, operator-escalation-rule.md) beside vendored copies (yagni-rule.md, evidence-rule.md, config-rule.md, collaborative-stop-rule.md). Each owned file opens by saying so; do not overwrite one in a re-sync sweep ├── han-coding/ # Coding plugin: tdd, refactor, design-an-api, code-review, code-overview, code-walkthrough, architectural-analysis, automated-test-planning, manual-test-planning, investigate, coding-standard (the skills for working in code; depends on han-communication and han-core; bundled by the han meta-plugin) │ ├── README.md # Light front door + scent-line skills list │ ├── .claude-plugin/ │ │ └── plugin.json │ ├── skills/ # Coding-facing skill directories, each with SKILL.md + references/ (+ scripts/ where used) │ ├── docs/ # In-plugin long-form docs: docs/skills/{name}.md -│ └── references/ # Cross-skill reference files vendored for han-coding skills (yagni-rule.md, evidence-rule.md, config-rule.md) +│ └── references/ # Cross-skill reference files vendored for han-coding skills (yagni-rule.md, evidence-rule.md, config-rule.md, collaborative-stop-rule.md) ├── han-github/ # GitHub plugin: post-code-review-to-pr, update-pr-description, work-items-to-issues (depends on han-communication, han-core, and han-coding, whose code-review skill post-code-review-to-pr wraps) │ ├── README.md # Light front door + scent-line skills list │ ├── .claude-plugin/ @@ -238,6 +238,15 @@ such as Claude, should be referenced here. (schema tokens, precedence, containment, pool-join, degradation) every participating skill applies. Vendored byte-identical into every skill-carrying plugin's `references/`; edit the canonical copy and re-sync the others. +### Collaborative working mode + +- **[han-core/references/collaborative-stop-rule.md](./han-core/references/collaborative-stop-rule.md).** The shared + contract behind `/pairing`: how a skill detects the collaborative 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. Consumed by + `pairing` and by the skills that hand control back at their own boundaries — `tdd`, `refactor`, `design-an-api`, + `iterative-plan-review`, and `plan-implementation`. Vendored byte-identical into `han-coding/references/` and + `han-planning/references/`; edit the canonical copy and re-sync the others. + ### Writing voice - **[han-communication/references/writing-voice.md](./han-communication/references/writing-voice.md).** Voice profile diff --git a/README.md b/README.md index e4698a5a..655728ae 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Han ships as multiple plugins: | -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`han`** | parent | the parent plugin that brings in `han-communication`, `han-core`, `han-documentation`, `han-research`, `han-planning`, `han-coding`, `han-github`, and `han-reporting` | | `han-communication` | bundled | the foundational plugin beneath every other: the shared readability standard and writing-voice profile, plus the skills and agent that apply them | -| `han-core` | bundled | the shared specialist agent roster, the project-discovery skill, and the canonical rule files | +| `han-core` | bundled | the shared specialist agent roster, the project-discovery skill, the `/pairing` collaborative working mode, and the canonical rule files | | `han-documentation` | bundled | documentation skills: project docs, architectural decision records, and runbooks | | `han-research` | bundled | pre-planning knowledge-work skills: research, gap analysis, and issue triage, plus the research-analyst agent | | `han-planning` | bundled | planning skills you reach for before implementation | diff --git a/docs/choosing-a-han-plugin.md b/docs/choosing-a-han-plugin.md index d5491844..f8bd12ca 100644 --- a/docs/choosing-a-han-plugin.md +++ b/docs/choosing-a-han-plugin.md @@ -34,7 +34,8 @@ description of what it does. The `han` meta-plugin is a convenience wrapper that plus the skills and agent that apply them and a `Han Readability` output style that applies the readability standard to a whole session. Bundled; depends on nothing. - **[`han-core`](../han-core/README.md).** The shared foundation: the specialist agent roster the other plugins - dispatch, the project-discovery skill, and the canonical rule files. Bundled; depends on no other Han plugin. + dispatch, the project-discovery skill, the canonical rule files, and the `/pairing` working mode that builds any kind + of work in reviewable pieces. Bundled; depends on no other Han plugin. - **[`han-documentation`](../han-documentation/README.md).** The documentation layer: feature and system docs, architectural decision records, and runbooks. Bundled; depends on `han-communication` and `han-core`. - **[`han-research`](../han-research/README.md).** The pre-planning knowledge-work layer: open-ended research, gap @@ -73,13 +74,14 @@ So you might expect installing one to give you that slice of Han with nothing el their skills dispatch the shared specialist agents that live there, and on `han-communication`, because their skills produce prose and source the readability standard from it. When you install a plugin that declares a dependency, Claude Code resolves and installs the dependency for you automatically and tells you what it added. So installing any of them -installs both alongside it, and you get the shared agent roster, project discovery, and the readability standard either -way. (`han-reporting` is the exception: it depends on `han-communication` alone.) +installs both alongside it, and you get the shared agent roster, project discovery, the pairing working mode, and the +readability standard either way. (`han-reporting` is the exception: it depends on `han-communication` alone.) That means **every layer install comes with the shared agents.** The real choice comes down to: - **A layer plus the foundations** (for example `han-documentation` or `han-coding`): that layer's skills, plus the - shared agent roster and project discovery from `han-core` and the readability standard from `han-communication`. + shared agent roster, project discovery, and the pairing working mode from `han-core`, and the readability standard + from `han-communication`. - **The bundled suite** (`han`): every layer at once. The opt-in plugins (`han-feedback`, `han-atlassian`, `han-linear`, `han-plugin-builder`) sit outside that choice. The @@ -98,7 +100,7 @@ to. | You work with GitHub from Claude Code (review PRs, write PR descriptions, publish work items as issues) | `han` (the bundled suite includes the GitHub skills) | `/plugin install han@han` | | You want only the documentation skills (project docs, ADRs, runbooks) | `han-documentation` (brings the `han-core` agents along) | `/plugin install han-documentation@han` | | You want only the pre-planning research skills (research, gap analysis, issue triage) | `han-research` (brings the `han-core` agents along) | `/plugin install han-research@han` | -| You want only the shared agents and project discovery, with no other skills | `han-core` | `/plugin install han-core@han` | +| You want the shared agents, project discovery, and the pairing working mode | `han-core` | `/plugin install han-core@han` | | You installed a single layer and now want the planning skills | `han-planning` (alongside what you already have) | `/plugin install han-planning@han` | | You installed a single layer and now want the coding skills | `han-coding` (alongside what you already have) | `/plugin install han-coding@han` | | You want to send post-session feedback on Han skills to the maintainers | `han-feedback` (alongside whatever you already have) | `/plugin install han-feedback@han` | diff --git a/docs/concepts.md b/docs/concepts.md index 265c6086..3bf0d10f 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -232,7 +232,7 @@ Direct invocation uses the `Agent` tool with `subagent_type: {plugin}:{agent-nam ## How Han is packaged Han ships as a family of plugins in one marketplace. `han-core` carries the shared specialist agent roster the other -plugins dispatch, the project-discovery skill, and the canonical rule files. +plugins dispatch, the project-discovery skill, the `/pairing` collaborative working mode, and the canonical rule files. `han-documentation` adds the documentation skills (`/project-documentation`, `/architectural-decision-record`, and `/runbook`). `han-research` adds the pre-planning knowledge-work skills (`/research`, `/gap-analysis`, and diff --git a/docs/plans/pairing-skill/artifacts/.discovery-notes.md b/docs/plans/pairing-skill/artifacts/.discovery-notes.md new file mode 100644 index 00000000..0c2be786 --- /dev/null +++ b/docs/plans/pairing-skill/artifacts/.discovery-notes.md @@ -0,0 +1,125 @@ +# Discovery Notes: pairing implementation + +Project context gathered before the specialist round. Read this first; do not re-grep for what is already here. Search +further only for what your domain needs that this file does not cover. + +## Tech stack + +- **Languages:** Markdown for all skill, agent, and documentation content. Bash for skill `scripts/`. +- **Package manager:** npm, dev tooling only. No application build and no dev server. +- **Install:** `npm install` puts prek, Prettier, and Bats on the local path only, nothing global. +- **Lint:** `npm run lint` runs `prek run --all-files`, covering Prettier, ShellCheck, and file-hygiene hooks. +- **Test:** `npm test` runs Bats over every `*.bats` file outside `node_modules`. A script's tests sit beside it in the + same directory; harness-level checks live in `test/`. +- **Default branch:** `main`. Current work is on `han-collaboration-output-style`. + +This matters more than usual here: the artifact being built is a Markdown skill definition, not code. There is no unit +test that can prove a skill behaves correctly. The only executable checks are Prettier, ShellCheck, file hygiene, and any +Bats tests written for a script. + +## ADRs found + +- `docs/adr/0001-project-configurable-default-swarm-size.md` — the only ADR in the repository. It covers configurable + swarm size, which the specification explicitly says does not apply to this mode, because it takes no size argument and + dispatches no team. + +No ADR governs skill placement, cross-plugin dependency direction, or working modes. That absence is itself a finding: +the placement reasoning behind the specification's D12 has no architectural record to rest on. + +## Coding standards found + +None. `docs/coding-standards/` does not exist and no `.github/CODING_STANDARDS.md` is present. + +The equivalent authority for this work is the plugin-authoring guidance in +`han-plugin-builder/skills/guidance/references/skill-building-guidance/`, which carries path-scoped rules that apply to +`**/skills/**/*.md`. The files most likely to govern this work: + +- `skill-description-frontmatter.md` — the description is the routing mechanism, so this governs every collision the + specification's routing table describes. +- `naming-conventions.md` — the rule behind the rename to `pairing`. +- `graceful-degradation.md` — directly relevant. It distinguishes hard prerequisites, where a skill stops, from partial + context, where a skill detects what is available, names an execution mode, and continues. The specification's optional + backing skills are exactly the second case. It also requires detection through a script that exits 0 on every path. +- `skill-composition.md`, `agent-dispatch-namespacing.md`, `skill-reference-files.md`, `progressive-disclosure.md`, + `workflow-patterns.md`, `context-hygiene.md`, `writing-effective-instructions.md`, `success-criteria-and-testing.md`. + +## Code touch points + +**The new skill.** + +- `han-core/skills/pairing/SKILL.md` — does not exist. `han-core/skills/` currently holds `project-discovery` only, so + this is the second skill in that plugin and the first a person invokes as a working mode. + +**The new rule file.** + +- `han-core/references/` holds `config-rule.md`, `evidence-rule.md`, `yagni-rule.md`. The stopping convention joins them. +- Precedent for an owned-versus-vendored rule file: `han-planning/references/` carries three owned files that open by + saying so, beside vendored copies. + +**The five skills gaining the flag**, across three plugins: + +- `han-coding/skills/tdd/SKILL.md` — unit closes at "Cross the completed item off the list" in its red-green-refactor + loop. Currently states it "runs autonomously after the initial request: it does not stop for confirmation," with one + gate when the human explicitly asks to review the plan first, and one hard blocker for a missing test command. +- `han-coding/skills/refactor/SKILL.md` — unit closes at "Green: cross the item off." Its plan step states "this is a + report, not a gate," with the same explicit-request exception. +- `han-coding/skills/design-an-api/SKILL.md` — runs in rounds and already surfaces open items one at a time. +- `han-planning/skills/iterative-plan-review/SKILL.md` — runs review rounds against a stop rule computed from finding + counts. Between rounds it surfaces disagreements and continues without waiting. +- `han-planning/skills/plan-implementation/SKILL.md` — runs resolution rounds, with its only user escalation pass after + all of them. + +**Surfaces that stop being accurate**, all confirmed to contain the stale text: + +- `han-core/.claude-plugin/plugin.json` — description names the agent roster, project-discovery, and the rule files. +- `han-core/.codex-plugin/plugin.json` — carries `description`, plus `interface.shortDescription`, + `interface.longDescription`, `interface.defaultPrompt`, and `keywords`, currently `["han", "agents", + "project-discovery", "foundation"]`. +- `.claude-plugin/marketplace.json` — its own `han-core` description, worded differently from the plugin.json one. +- `.agents/plugins/marketplace.json` — the Codex-format manifest. +- `han-core/README.md`, `docs/choosing-a-han-plugin.md`, `docs/skills/README.md`, `docs/workflows.md`, root `CLAUDE.md`, + `CHANGELOG.md`. + +**Cross-plugin invocation precedent**, which bears on whether a `han-core` skill may reach into `han-coding`: +`han-communication:readability-guidance` is invoked 29 times, `han-communication:readability-editor` 15 times, and +`han-communication:explanation-guidance` 13 times, from skills in `han-planning` and `han-coding`. In every one of those +cases the invoking plugin declares the dependency. This work has no such declaration available, because +`han-coding` and `han-planning` both already depend on `han-core`. + +## Recent activity + +Churn over ninety days, in the files this work touches: + +| File | Commits | +| --------------------------------------------------- | ------- | +| `han-planning/skills/plan-implementation/SKILL.md` | 22 | +| `han-core/.claude-plugin/plugin.json` | 16 | +| `han-planning/skills/iterative-plan-review/SKILL.md` | 15 | +| `han-coding/skills/tdd/SKILL.md` | 12 | +| `han-core/skills/project-discovery/SKILL.md` | 11 | +| `han-coding/skills/refactor/SKILL.md` | 8 | + +The two highest-churn skill files are both new additions to the flag list, settled late in the specification round. A +change landing in a file that moved twenty-two times in ninety days carries more conflict risk than the same change in a +quiet file, and the plan should sequence accordingly. + +## Format precedent + +Five existing implementation plans share this repository's format, including +`docs/plans/han-communication-plugin/feature-implementation-plan.md`, which is the closest analogue because it also +created a plugin-level artifact rather than application code. The template lives at +`han-planning/skills/plan-implementation/references/feature-implementation-plan-template.md` and changed seven times in +ninety days. + +## Gaps: searched for and not found + +- **No coding standards directory.** The plugin-authoring guidance substitutes. +- **No ADR on plugin placement or dependency direction.** The invariant that `han-core` depends on no other Han plugin + is stated in prose in the root `CLAUDE.md` and enforced only by the absence of a `dependencies` key in its manifest. +- **No test that can verify skill behavior.** Bats covers scripts. Nothing executable checks whether a skill's + instructions produce the described behavior, and nothing checks whether a description routes correctly. The + specification's routing decisions therefore ship unverified unless the plan adds a way to check them. +- **No existing example of a delegating boundary between two skills.** Every boundary clause found is exclusive. The + specification says this outright and it was confirmed here. +- **No existing working-mode skill anywhere in the suite**, so there is no precedent for how one is structured, where + its convention lives, or how it coexists with the skills it wraps. diff --git a/docs/plans/pairing-skill/artifacts/decision-log.md b/docs/plans/pairing-skill/artifacts/decision-log.md new file mode 100644 index 00000000..dd9a2c4d --- /dev/null +++ b/docs/plans/pairing-skill/artifacts/decision-log.md @@ -0,0 +1,595 @@ +# Decision Log: pairing + +This file records every decision settled while specifying `pairing`. Behavioral statements live in +[../feature-specification.md](../feature-specification.md); this file carries the history, rationale, evidence, and +rejected alternatives. + +Two research reports back this specification. Both were produced in the same session, adversarially validated, and are +cited below by their titles rather than repeated: + +- **The collaborative-mode report** — whether the mode belongs in an output style or a skill. Recommends one skill and no + output style, at High confidence for the mechanism. +- **The chunk-boundary report** — what makes a reviewable stopping point when the work is not code. Recommends stopping + where the kind of feedback changes, at High confidence for staging by concern, Medium for the per-kind units, and Low + for open-ended work. + +## Trivial decisions + +None. Every decision was classified once, here, after the review round returned. Each one carries at least one promotion +signal: a driving finding, a dependent decision that rests on it, or evidence beyond the operator's framing. The seven +settled by operator input are not trivial for that reason alone, because each is either depended on by a later decision +or was reshaped by review. No D# number moved, so every inline link in the specification still resolves. + +## Full decisions + +### D1: The mode covers any kind of work, not only code + +- **Question:** Is this a code-pairing mode, or a general working mode? +- **Decision:** A general collaborative working mode. Code is one case among several. +- **Rationale:** The operator widened the scope explicitly, giving two examples the code-only framing could not hold: a + design pairing that produces a decision rather than code, and an open-ended request to pair on writing a response. +- **Evidence:** User input. The operator's exact words are quoted in + [scope-boundary.md](scope-boundary.md) under "The widening." +- **Rejected alternatives:** + - A code-only pairing mode — rejected because two of the operator's three named examples produce no code. +- **Linked technical notes:** — +- **Driven by findings:** — +- **Dependent decisions:** D3, D5, D11, D12 +- **Referenced in spec:** Outcome + +### D2: Every existing skill keeps its current default behavior + +- **Question:** Do the skills this mode builds on change how they run when invoked normally? +- **Decision:** No. Every collaborative flag is opt-in, and an existing invocation behaves exactly as it does today. +- **Rationale:** The operator stated this as an exclusion, preferring an opt-in workflow over changing any skill's + defaults. It also keeps the change reversible: nothing about this work degrades an existing workflow if the mode turns + out to be wrong. +- **Evidence:** User input, recorded in [scope-boundary.md](scope-boundary.md) under "Stated Exclusions." +- **Rejected alternatives:** + - Making the collaborative loop the default for the skills that gain it — rejected because the operator excluded it in + the same sentence that accepted the opt-in shape. +- **Linked technical notes:** — +- **Driven by findings:** — +- **Dependent decisions:** D10, D15 +- **Referenced in spec:** Actors and Triggers, Out of Scope, Coordinations + +### D3: The mode sorts the work before planning anything, using a named test + +- **Question:** How does the mode know what shape the work has, and what happens when a request fits more than one shape? +- **Decision:** It applies a fixed ordered test and stops at the first match: skill-backed, then decision work, then prose + work, then a fall-through to open-ended. The order is the tie-break, so drafting a decision record sorts as decision work + rather than prose work. The sort result is named in the plan, so you can correct it. +- **Rationale:** The chunk-boundary report found a different established unit for each kind of work and no single unit that + spans them, so sorting first is what lets one loop serve them all. Review found two problems with the first draft, both + now fixed. The kinds were not mutually exclusive and nothing broke a tie, which meant two runs on the same request could + sort differently and produce different loops; an ordered test with a first-match rule settles that the way this suite + already settles it elsewhere, by naming the test rather than saying the mode identifies the right answer. And the sort + was never disclosed, which made the single largest determinant of your experience the one thing you could not correct. +- **Evidence:** The chunk-boundary report's recommendation for the per-kind units. D1 established that more than one kind of + work is in scope. The named-test form follows `code-walkthrough`, which does not ask for important steps but names what + earns one. Review findings F7 and F8 drove the ordered test and the disclosure. +- **Rejected alternatives:** + - One universal unit across all work — rejected because no source defines one, and the report searched for one. + - Asking you which kind it is — rejected because the request usually says, and D4's reasoning applies. + - Four kinds with open-ended as a peer category — rejected on review as a distinction that changed no behavior. The + open-ended branch produces whatever the plan named, which is what the plan does regardless, so it is a fall-through + rather than a kind. Keeping it as a fourth kind made the sort harder for no gain. +- **Linked technical notes:** — +- **Driven by findings:** F7, F8, F9 +- **Dependent decisions:** D5, D11, D13 +- **Referenced in spec:** Primary Flow + +### D4: The mode proposes the plan of stopping points rather than asking you to supply one + +- **Question:** Who decides where the work stops, and how is that decision reached? +- **Decision:** The mode proposes a plan naming the pieces and the reason for each boundary. You accept, change, or + replace it, and either side can renegotiate as the work reveals itself. +- **Rationale:** Fifty years of goal-setting research finds that when difficulty is held constant, an assigned goal + reaches commitment equivalent to a negotiated one as long as it comes with a rationale. So a proposal costs little + against asking first, and buys a cheap early correction. A proposal also gives you something concrete to react to, + where a blank question at the start asks you to plan work you have not seen. +- **Evidence:** The chunk-boundary report's option 2, resting on the goal-setting research and on `design-an-api`, which + already surfaces open items one at a time on the stated reasoning that each answer reshapes the ones behind it. +- **Rejected alternatives:** + - Asking you where to stop before proposing anything — rejected on judgment rather than evidence. The same research + shows participation's real effect is that people set themselves harder targets, which licenses asking first too. The + report says plainly that preferring a proposal is a judgment call, and this decision inherits that caveat. + - Fixed-cadence stops decoupled from the work's shape — rejected because a cadence rule never says what should be ready + at the stop, and its supporting sources describe visual design critique rather than this. +- **Linked technical notes:** — +- **Driven by findings:** — +- **Dependent decisions:** D5, D9, D11 +- **Referenced in spec:** Primary Flow, Alternate Flows and States, Edge Cases and Failure Modes +- **Known gap:** No study compares how carefully someone reviews at a checkpoint they helped choose against one imposed + on them. The claim that negotiation improves review quality is not evidenced and is not part of this rationale. + +### D5: A piece ends where the kind of feedback changes, not at a size threshold + +- **Question:** What makes one piece of work one piece? +- **Decision:** The boundary falls where the kind of feedback changes. One unit of a backing skill's own work, one + decision, one rung of a fidelity ladder for prose, or whatever the negotiated plan named for open-ended work. +- **Rationale:** This is the strongest-evidenced finding in either report, and it converges from four independent + directions. Reviewing the shape before the surface matters because polish applied before the shape is settled gets + thrown away when the shape changes. +- **Evidence:** The chunk-boundary report's option 1. Two national editing bodies define the same stages in the same + order, one in the United States and one in the United Kingdom. Two peer-reviewed composition studies find that + inexperienced writers revise at the word level while experienced writers revise for meaning and structure first. Design + practice reaches the same conclusion from an unrelated field: low-fidelity work draws structural feedback, high-fidelity + work draws only cosmetic feedback. For the decision unit, the originating architectural-decision-record source states + that one record describes one significant decision, and an independently maintained community reference says the same. +- **Rejected alternatives:** + - A word count, line count, or file count — rejected because no source supports a size threshold, and every source that + addresses the question defines the unit by concern instead. + - One concern pass over a whole finished draft, which is what the editorial evidence literally prescribes — rejected + because it requires a finished draft before the first review, and this loop produces work in pieces. Adversarial + validation caught this as the chunk-boundary report's sharpest internal contradiction, and the fidelity ladder is the + resolution: it keeps the order of concerns the editorial evidence establishes while dropping the finished-draft + precondition. + - A bounded whole artifact reviewed in one piece — rejected for the same precondition, though it names a real risk this + decision must live with: parts reviewed in isolation can each look right while the whole does not. +- **Linked technical notes:** — +- **Driven by findings:** — +- **Dependent decisions:** — +- **Referenced in spec:** Primary Flow +- **Known gap:** The prose unit is a reconciliation the report performed, not a practice any single source documents. Its + confidence is Medium, and for open-ended work the report found no unit at all, which is why D4 carries that case. + +### D6: A stop hands you checkable claims rather than a case for the work + +- **Question:** What does a stop actually present? +- **Decision:** The specific things you can verify and what changed, stated plainly, with the reasoning available but not + leading. +- **Rationale:** Explaining your reasoning to a reviewer does not reliably make them more careful and can make them less + so. Explanations act as a signal of competence regardless of whether their content holds up, and a polished one invites + agreement. What works instead is lowering the cost of checking a claim independently. +- **Evidence:** The chunk-boundary report's option 6. One study of five experiments with 731 participants found + explanations reduce over-reliance only when they lower the cost of checking the claim; hard-to-parse explanations make + things worse. A second study found passive explanations do not reduce over-reliance and sometimes increase it. +- **Rejected alternatives:** + - A narrative walkthrough leading with why each choice was made — rejected because that is precisely the shape the + studies found ineffective or harmful. +- **Linked technical notes:** — +- **Driven by findings:** — +- **Dependent decisions:** D7 +- **Referenced in spec:** Primary Flow, User Interactions +- **Known gap:** Adversarial validation established that the two supporting studies are not independent of each other. + They belong to the same research conversation about over-reliance and explanation, in the same venue, with one + reframing the other's line of findings. Discounting both would leave this decision resting only on general habituation + research, which addresses a different question. + +### D7: The mode asks for your read first only where a mistake is expensive to undo + +- **Question:** Should a stop require your own judgment before showing its work, and if so, how often? +- **Decision:** Only for a piece the plan marked as containing a choice that is expensive to walk back. The ask comes + before the build. Declining to answer is a first-class response that advances the stop unchanged, and the reveal + afterward presents the work in the same form as any other stop, without restating your read, scoring it, or defending a + divergence from it. +- **Rationale:** Asking the reviewer to commit to their own judgment before seeing the assistant's reasoning was the one + intervention that measurably reduced over-reliance, and the same study measured its cost in reduced satisfaction. + Amazon's reversibility framework says where to spend that cost: slow, deliberate review for irreversible choices and + fast review for ones you can walk back. Paying the friction on every stop of a long session is how a mode stops getting + used. + + Three details came out of review and matter as much as the frequency. The ask has to precede the build, because both + studies work by having the person commit before the answer exists; an ask arriving after the work is on disk buys the + cost and none of the benefit. A non-answer has to be accepted, because the study's benefit concentrated in people + already inclined toward effortful thinking, and a mandatory guess taxes the fatigued, the second-language, and the + newly-arrived reader hardest while returning them the least. And the reveal must not grade the guess, because a stop + that scores you teaches you to answer noncommittally, and a stop that defends itself leads with the fluent case D6 + rules out on evidence. +- **Evidence:** User input, choosing this option over never asking and over asking at every stop. The options presented + rested on the chunk-boundary report's options 5 and 6. The three refinements come from review findings F1, F2, and F3. +- **Rejected alternatives:** + - Never asking first — rejected because it drops the one intervention controlled studies found effective, leaving the + expensive stops unguarded too. + - Asking at every stop — rejected because the measured satisfaction cost applies at every stop, and the operator judged + that too high a price for a mode meant to be lived in. + - Keeping the ask at the stop after the build, as first drafted — rejected because it inverts the mechanism its own + evidence depends on. +- **Linked technical notes:** — +- **Driven by findings:** F1, F2, F3 +- **Dependent decisions:** D14 +- **Referenced in spec:** Primary Flow, User Interactions + +### D8: Your feedback goes into a readable written record rather than being carried in memory + +- **Question:** How does feedback given at an early stop still apply at a much later one? +- **Decision:** Every piece of feedback is written into a running record before it is acted on, and the record is read + before each piece is planned. You can read that record whenever you ask, and when the mode applies a recorded entry to a + later piece it names which entry it applied. +- **Rationale:** Model accuracy drops substantially when relevant information sits in the middle of a long context, which + is exactly where a correction given at the second stop sits by the seventh. A written record also survives a session + compaction, which memory does not. +- **Evidence:** The chunk-boundary report. The strongest empirical anchor is surgical: teams using a written checklist + missed about 6 percent of critical steps against about 23 percent working from memory, in simulated crisis scenarios. + Professional editing implements the same idea as the style sheet, a running record of decisions and reasons kept so a + decision is not re-argued or misremembered. Han already carries an equivalent convention in the escalation register. +- **Rejected alternatives:** + - Relying on the conversation itself to carry feedback forward — rejected because a compaction destroys it and because + mid-context information is the least reliably retrieved. + - Keeping the record as the mode's private notes, as first drafted — rejected on review. A misrecorded correction would + then govern every later piece and surface only as work that feels subtly wrong, which is the failure this decision + exists to prevent, inverted onto the person. + - Detecting contradictions across the record automatically — rejected as the expensive way to reach the same place. + Naming which entry was applied lets you catch the conflict yourself, with the entry in front of you, and has no false + positives. The detection behavior moved to the deferred list. +- **Linked technical notes:** — +- **Driven by findings:** F5, F6 +- **Dependent decisions:** — +- **Referenced in spec:** Outcome, Primary Flow, User Interactions, Edge Cases and Failure Modes, Coordinations +- **Known gap:** No study tests written-versus-remembered feedback for this kind of work. The surgical evidence is an + analogy from an adjacent domain, and is labeled as such. + +### D9: Feedback condemning the piece in hand is fixed in place and re-shown + +- **Question:** When your feedback says the piece just built is wrong, does it get fixed now or become the next piece? +- **Decision:** Fixed now, and shown to you again before anything new is built, with the re-show naming the correction + it applied and what it touched before it restates the piece. When the feedback would change work outside the piece in + hand, the mode says it reads the feedback that way before acting on it, and you can accept the reopened plan, change + it, or decline the reopening and have the feedback recorded as scoped to later work. +- **Rationale:** Nothing gets layered on top of work you already flagged. The reopening clause is what stops one piece + from absorbing an unbounded fix loop: feedback that reaches outside the piece is a signal the plan was wrong, not that + the piece needs more patching. Review added the two halves that keep the person in the lead through it. A re-show that + only says "here it is again" makes you re-read reviewed material to confirm the fix landed, which raises the cost of + checking at the moment you are most invested, against the evidence behind D6. And a reopening the mode decided on its + own replaces a plan you agreed to, which is the wrong answer for someone thinking out loud. +- **Evidence:** User input, choosing this over deferring the correction to the next piece and over asking each time. + Review findings F24 and F25 added the declined reopening and the named correction. +- **Rejected alternatives:** + - Recording the correction and fixing it as the next piece — rejected because the corrected version would not reach you + until a full round later, and anything built in between would rest on work you had already called wrong. + - Asking each time whether it is an in-place fix or the next piece — rejected because it adds a second question at + exactly the stops that are already slowest. +- **Linked technical notes:** — +- **Driven by findings:** F24, F25 +- **Dependent decisions:** — +- **Referenced in spec:** Primary Flow, Alternate Flows and States + +### D10: Five skills gain an opt-in collaborative flag + +- **Question:** Which existing skills hand control back to the pairing loop at their own boundaries? +- **Decision:** `tdd`, `refactor`, `design-an-api`, `iterative-plan-review`, and `plan-implementation`. All five already + have a unit and already close it explicitly. The flag changes only what happens at that existing close, and none of them + gains a new boundary. +- **Rationale:** This was settled in three passes, and the test widened at each one. + + The first survey asked whether a skill changes files on its own, across a sequence, where each step builds on the last. + Only `tdd` and `refactor` passed, and the operator confirmed both. + + Review then found the mode's own founding example falling outside that answer. The skill covering an API design runs + discovery, an options document, a question round, and a validation round, and sorting past it would have handed you a + thinner hand-rolled loop instead, silently. The operator gave it the flag rather than accept that trade, which widened + the test to: does the skill produce its result across a sequence of units, where each unit stands on its own and later + units build on earlier ones? + + Running the widened test across every skill in the plugins the operator did not rule out found two more. Both fail for + the same reason `tdd` did, which is that they have a real unit boundary and run straight past it. + `iterative-plan-review` runs review rounds against a stop rule computed from finding counts, and between rounds it + surfaces a disagreement between two reviewers and then continues without waiting for the answer. + `plan-implementation` runs resolution rounds and holds its only user escalation until after all of them are finished. + + The rest fail in four groups. The inline guidance skills produce no result of their own. The publishing and export + skills push a finished artifact to a shared system and already gate before writing. The one-document skills hand you a + single synthesized artifact rather than a sequence of standalone units. And `plan-a-feature` and `code-walkthrough` + would gain nothing from the flag, because the first already interviews one question per turn through its design tree + and the second already stops after every step. +- **Evidence:** User input at all three points, each time confirming a survey result. The two additions were verified + against the skills themselves: `iterative-plan-review`'s round loop states that it surfaces a finding and continues if + the user answers before the next round, and `plan-implementation` places its user escalation pass after its iterative + resolution loop. D2 constrains every flag to be opt-in. +- **Rejected alternatives:** + - `tdd` only — rejected because the operator confirmed both after the first survey. + - Routing API-design work to `design-an-api` unpaired — rejected because it answers a founding example with "here is the + right skill, but you are not pairing on it." + - Letting the mode's own decision loop supersede that skill — rejected because it silently drops a discovery pass and an + adversarial validation round the person would otherwise have had. + - Stopping at three skills — rejected because the original reason for ruling out planning skills was that they already + interview, and neither of these two stops between its rounds, so that reasoning does not reach them. + - Flagging `plan-implementation` alone — rejected because `iterative-plan-review` is the one that currently continues + past a disagreement it has already surfaced to you, which is the sharper of the two problems. +- **Linked technical notes:** — +- **Driven by findings:** F10 +- **Dependent decisions:** D21, D22 +- **Referenced in spec:** Alternate Flows and States, Coordinations, Open Items, What Else Has To Change When This Ships + +### D11: The front door never picks the discipline for you + +- **Question:** When you ask to pair on implementing something, does the mode decide whether to drive it from tests, + restructure what is there, or sketch a shape first? +- **Decision:** No. The proposed plan names which approach it intends and why, and that proposal is what you accept or + redirect. A single request may span more than one approach, and when the plan sequences more than one backing skill it + orders them so each skill's own preconditions hold when its turn arrives. +- **Rationale:** The operator established this directly, correcting an earlier framing that treated the request as a + routing problem to be solved by guessing. It also follows from D4: the mode proposes rather than decides, and the + approach is one more thing the proposal names. +- **Evidence:** User input. The operator's exact words are quoted in [scope-boundary.md](scope-boundary.md) under "The + widening." Review finding F27 added the ordering requirement: `refactor` refuses to run alongside an in-flight + test-driven loop, so a plan that sequences the two in the wrong order trips that skill's own precondition and reads as + the mode contradicting its own plan. +- **Rejected alternatives:** + - Inferring the discipline from the request's wording and proceeding silently — rejected because the operator named it + as the thing not to do, and because sketching a shape before a full test-driven build is a legitimate answer no + keyword match would find. +- **Linked technical notes:** — +- **Driven by findings:** F27 +- **Dependent decisions:** — +- **Referenced in spec:** Alternate Flows and States, Out of Scope + +### D12: The skill lives in han-core, and its backing skills are optional + +- **Question:** Which plugin carries a pairing mode that covers prose, decisions, and code alike, given that the skills it + hands work to live in a different plugin? +- **Decision:** `han-core`, invoked as `/han-core:pairing`. The backing skills are an optional enhancement rather than + a requirement: the mode works on its own for prose, decisions, and open-ended work, and gains the skill-backed paths only + when the plugin carrying that skill is installed. Three of the five live in `han-coding` and two in `han-planning`, so + the two plugins go missing independently. When a backing skill is absent, the mode names it and offers you the choice rather than + substituting silently. +- **Rationale:** D1 established that the mode covers any kind of work, and `han-core` is the shared foundation every Han + install already carries. Reaching into the coding plugin to pair on a stakeholder email reads wrong. + + Review found the placement had a problem the original reasoning never checked. `han-coding` already depends on + `han-core`, so a `han-core` skill that requires `han-coding` would close a dependency cycle, and `han-core`'s stated + invariant is that it depends on no other Han plugin. Treating the backing skills as optional resolves it honestly rather + than by omission: nothing is undeclared, because nothing is required. The general path is the point of the mode, and the + skill-backed paths are the enhancement. + + Two consequences follow and are part of the work. The plugin's own front door, index entry, and manifests describe it as + the agents, project discovery, and the rule files, and all of them must now say it carries a working mode. The plugin + index also offers an install described as having no other skills, which stops being true. +- **Evidence:** User input at both points: choosing `han-core` on fit, then confirming it after review finding F11 named + the dependency cycle and the labeling mismatch. The cycle was verified directly against the plugin manifests. +- **Rejected alternatives:** + - `han-coding`, as originally named — rejected because the mode covers work with no code in it, and that plugin's front + door groups it with `tdd`, `refactor`, and `code-review`. + - A new `han-collaboration` plugin — rejected twice. First as a whole plugin for one skill on no evidence a second is + coming, then again after the cycle was found, because treating the backing skills as optional achieves the same + correctness without the new plugin. + - Requiring `han-coding` from `han-core` — rejected because it is a dependency cycle and breaks a stated invariant. +- **Linked technical notes:** — +- **Driven by findings:** F11 +- **Dependent decisions:** D21 +- **Referenced in spec:** Actors and Triggers, Edge Cases and Failure Modes, What Else Has To Change When This Ships + +### D13: Three kinds of work plus a fall-through, not four kinds + +- **Question:** Is open-ended work a category the mode sorts into, or the place a request lands when nothing else matches? +- **Decision:** A fall-through. The sort has three tests and anything failing all three is open-ended, where the plan + supplies the boundaries with no rule behind them. +- **Rationale:** Naming it a fourth kind implied a rule existed. None does: the research searched for a unit for + open-ended work and found none, at Low confidence, which is the lowest rating in either report. Treating it as a + fall-through says the same thing honestly and makes the sort simpler at no cost, because the open-ended branch produces + whatever the plan named, which is what the plan does for every kind anyway. +- **Evidence:** The chunk-boundary report's Low confidence rating and its explicit statement that no source defines a unit + for this case. Review finding F9 raised the no-op branch under the YAGNI rule. +- **Rejected alternatives:** + - Four peer kinds — rejected because the fourth changed no behavior and made the sort harder. + - Dropping the loop entirely for open-ended work and simply conversing — rejected because it gives you nothing to + redirect before the work exists, which is the one thing a proposed plan buys. +- **Linked technical notes:** — +- **Driven by findings:** F9, F23 +- **Dependent decisions:** — +- **Referenced in spec:** How Confident Each Part of This Design Is, Primary Flow + +### D14: The reversibility call is announced in the plan, and the ask precedes the build + +- **Question:** Who judges that a choice is expensive to walk back, when, and can you argue with the call? +- **Decision:** The plan proposed before work starts names which pieces it expects to carry such a choice. That makes the + call visible and contestable at plan time, when contesting is cheap, and it means the ask in D7 can come before the + build rather than after. +- **Rationale:** The framework this rests on treats reversibility as an explicit shared classification whose whole value is + in being visible and arguable. Left silent, the friction arrives unpredictably, you cannot budget attention around it, + and you can neither wave off a call that is wrong nor flag a piece the mode missed. The person who knows which choices + are expensive in their own codebase is you, and without this there is no channel for you to say so. +- **Evidence:** The reversibility framework in the chunk-boundary report, which that report records as corroborated by + an independent secondary source describing it identically. Review findings F1 and F4 established that the call was + silent and that the ask was ordered wrongly against its own evidence. +- **Rejected alternatives:** + - Judging reversibility silently at each stop — rejected because it makes the promise that friction arrives only where + it is warranted unverifiable from your seat. +- **Linked technical notes:** — +- **Driven by findings:** F1, F4 +- **Dependent decisions:** — +- **Referenced in spec:** Primary Flow + +### D15: For skill-backed work the pre-work plan names the unit, and the first stop carries the list + +- **Question:** How can the mode promise a plan of pieces before a backing skill has produced its own list? +- **Decision:** It cannot, so the promise splits. For skill-backed work, the plan before any work starts names the backing + skill, the unit it will stop at, and the reason. That skill's own list of units is surfaced as the plan of pieces at the + first stop, where you can still redirect it. +- **Rationale:** The backing skills build their lists partway into their own runs and report them without stopping. At the + moment the pre-work plan is made, the list does not exist. The original promise was therefore either unmet or a silent + change to a backing skill's gating, and D2 forbids the second. Splitting the promise keeps both intact. +- **Evidence:** The structure of `tdd` and `refactor`, both of which report their plan and continue immediately rather than + gating on it. D2 forbids changing that. Review finding F12. +- **Rejected alternatives:** + - Making the backing skills gate on their list so the plan can include it — rejected because it changes their default + behavior, which D2 excludes. + - Promising the full list up front anyway — rejected because it is a promise the mode cannot keep. +- **Linked technical notes:** — +- **Driven by findings:** F12 +- **Dependent decisions:** — +- **Referenced in spec:** Primary Flow + +### D16: Every stop names your position in the plan, and the plan stays available + +- **Question:** How does the person know where they are, how much is left, and what the plan currently says? +- **Decision:** Each stop names which piece this is against the plan and what remains. The current plan is available on + request, and a revised plan is named as revised. On resuming after a compaction or interruption, the mode restates the + piece in hand and its position before continuing. +- **Rationale:** The person agreed at plan time to a queue depth they then could not see. Without it they cannot answer + "do I have the attention for two more, or should I stop cleanly here", which is the decision the faster gear in D19 + exists to serve, and after a renegotiation they cannot answer "what did I agree to" at all. Two conventions already in + this suite carry exactly this and were dropped in translation: the walkthrough keeps a step counter, and the escalation + rule states how many questions are pending so the operator knows the queue depth they are agreeing to. +- **Evidence:** The two in-repo conventions above. The measured cost of an interruption, at an average of 23 minutes and 15 + seconds to return to full focus, is what makes the resume case worth specifying rather than assuming. Review findings + F13 and F14. +- **Rejected alternatives:** + - Naming only what comes next, as first drafted — rejected because a one-step lookahead is not a position. +- **Linked technical notes:** — +- **Driven by findings:** F13, F14 +- **Dependent decisions:** D19 +- **Referenced in spec:** Primary Flow, User Interactions, Edge Cases and Failure Modes +- **Known gap:** The interruption figure is one study, which the research marks single-source and caveats for this + application. It is why the resume case was specified rather than assumed; no part of the behavior depends on the + number being exact. + +### D17: The stop is a directive the mode follows, not a guarantee + +- **Question:** Can the mode be prevented from building past a stop? +- **Decision:** No, and the specification says so rather than claiming otherwise. When an overrun happens, the next thing + the mode says names it, states which pieces were built without review, and offers to walk back through them. +- **Rationale:** The collaborative-mode research is explicit that nothing can force a stop at a chunk boundary; every + option it examined ultimately relies on the assistant following an instruction, and they differ in how much weight the + instruction carries rather than in whether it can be enforced. Claiming a guarantee the mechanism cannot provide is + worse than naming the limit, because it leaves the most likely real failure of this feature unspecified. The tendency is + real in exactly the skill being flagged: `tdd` today runs to completion without further human input. +- **Evidence:** The collaborative-mode report's finding on enforceability. The structure of `tdd`. Review finding F15. +- **Rejected alternatives:** + - Stating the stop as a hard guarantee, as first drafted — rejected because no mechanism backs it and no behavior was + specified for the case where it fails. +- **Linked technical notes:** — +- **Driven by findings:** F15 +- **Dependent decisions:** — +- **Referenced in spec:** Primary Flow, Edge Cases and Failure Modes + +### D18: Ending the loop is the person's call, and nothing computes it + +- **Question:** What ends the loop, given that the plan can be reopened at any point? +- **Decision:** You do. The mode reports when the plan is finished, but with the plan reopenable on any out-of-piece + feedback, "finished" is not a fixed target, and no rule computes a stopping point. However the loop ends, the report + covers the state of any work a backing skill left mid-cycle and names where the feedback record was written. +- **Rationale:** The suite's review-round skills, `iterative-plan-review` and `plan-implementation`, end their rounds on + a rule computed from finding counts and the number of specialists raising them, which is the only pattern where "are + we done" has an answer nobody argues about. It needs a countable signal to gate on, and work being built produces + none. Rather than invent one, the specification states that ending is deliberate rather than an oversight. +- **Evidence:** The chunk-boundary report's option 7 and its stated reason for not transferring. Review findings F16 and + F26, the second of which found that a loop ended mid-cycle leaves edited and possibly failing files with nothing said + about them. +- **Rejected alternatives:** + - A computed stop rule — rejected because there is nothing to compute over. + - Leaving it unstated — rejected because a reader would read it as a gap rather than a choice. +- **Linked technical notes:** — +- **Driven by findings:** F16, F26 +- **Dependent decisions:** — +- **Referenced in spec:** Primary Flow, Alternate Flows and States, Out of Scope + +### D19: You can ask for several pieces at once, and the loop returns to its normal pace after + +- **Question:** What can the person do when full ceremony on every piece is more than they want, but turning review off is + less than they want? +- **Decision:** Ask for more than one piece, in whatever words. The mode honors it as asked and returns to its normal pace + at the following stop without being asked to. +- **Rationale:** Without this, the only two gears are full ceremony and no review at all, and the person who is tired at + their eleventh stop has to choose between them. That is the failure the whole mode exists to prevent, reached through + the mode's own controls. The walkthrough convention this specification claims to inherit already carries the exception + and honors an explicit request for more than one step; it was dropped in translation. +- **Evidence:** The walkthrough skill's stated exception. Two practitioner sources describing review quality decaying into + rubber-stamping past a volume threshold. Review finding F17. +- **Rejected alternatives:** + - Only stop-or-finish-unattended, as first drafted — rejected because the middle case is the common one. + - Requiring the person to re-request normal pace afterward — rejected as friction on the person already economizing. +- **Linked technical notes:** — +- **Driven by findings:** F17 +- **Dependent decisions:** — +- **Referenced in spec:** Alternate Flows and States, Edge Cases and Failure Modes, User Interactions + +### D20: Both entry paths are supported, and the phrase path has to win its collisions + +- **Question:** Does the mode start only when named outright, or also when described in the person's own words? +- **Decision:** Both. Naming it outright bypasses competition entirely. Saying it in your own words competes against every + skill available in the session, and this mode's arrival therefore changes what several existing skills say about + themselves. +- **Rationale:** Three of the four phrasings the operator offered as founding examples name another skill's strongest + trigger word, and the fourth names no competing skill at all. For the three that collide, left unmanaged the person + types their own sentence and gets the uninterrupted run this mode exists to replace, or gets stopped at every step + when they wanted a straight run. + + The relationship needing description has no precedent here. Every existing boundary between two skills is exclusive: one + does the job and the other does not. This one is not, because the mode runs the very skills it competes with. Stating it + on one side only leaves a gap the request falls through, so both sides state it. +- **Evidence:** The four phrasings quoted in the scope boundary record, each checked against the routing text of the + skill it names, which found a competing skill for three of them and none for the fourth. The suite's own guidance that + one-way disambiguation is a gap. Review findings F18, F19, and F20. +- **Rejected alternatives:** + - Supporting only the named invocation — rejected because the operator's own examples are all phrase-shaped. + - Copying the existing exclusive boundary form — rejected because it cannot express a delegating relationship. +- **Linked technical notes:** — +- **Driven by findings:** F18, F19, F20 +- **Dependent decisions:** — +- **Referenced in spec:** Actors and Triggers, Which Skill Answers When You Say It In Your Own Words, Coordinations + +### D21: The surfaces that stop being accurate are part of this work + +- **Question:** Is updating the documentation and manifests this mode invalidates part of shipping it, or a follow-up? +- **Decision:** Part of it. The specification names the three groups: the plugin's own identity in its front door, index + entry, and manifests; the operator manuals and routing text of the five skills gaining the flag; and the usual surfaces + a new skill needs. +- **Rationale:** The placement in D12 changes what `han-core` is, and the flag in D10 changes user-visible behavior of three + existing skills. Both make existing text false on the day this ships. This repository's own rule is that a skill's + long-form documentation lands in the same pull request as the skill, not as a follow-up. Naming the surfaces in the + specification is what stops them being discovered one review comment at a time. +- **Evidence:** The repository's contribution guide and its documentation coverage rule. Review findings F11 and F22: + F22 found the specification named no documentation surface at all, and F11 is where the plugin's own identity stopped + matching what it carries. +- **Rejected alternatives:** + - Leaving the surface list to the implementation plan — rejected because two of the three groups exist only as + consequences of decisions made here, and would not be obvious to someone reading the implementation plan alone. +- **Linked technical notes:** — +- **Driven by findings:** F11, F22 +- **Dependent decisions:** — +- **Referenced in spec:** What Else Has To Change When This Ships + +### D22: The stopping convention is a canonical rule file owned by han-core + +- **Question:** What owns the convention for how this mode stops and asks questions? +- **Decision:** A new canonical rule file owned by `han-core`, beside the YAGNI, evidence, and configuration rules that + plugin already owns. +- **Rationale:** Han has an escalation rule already, and it does not fit. That rule assumes a single stop per run, because + it exists to minimize interruptions in work meant to run on its own. This mode treats stopping as the deliverable. The + research reached the same conclusion independently, saying a collaborative loop would need its own convention rather + than an exception to that one. + + Owning it as a shared file rather than carrying it inline clears the evidence bar on a named direct dependency rather + than on speculation. Five skills consume the handoff contract, not one: this mode needs the whole convention, and each + flagged skill needs to know what returning control means at its own boundary. `han-core` is where the suite's canonical + rule files already live, so the file has a home that matches what it is. +- **Evidence:** User input, choosing this over carrying the convention inline and over extending the existing escalation + rule. The mismatch with the existing rule is stated in the collaborative-mode report and confirmed against that rule, + whose named consumers are four planning skills and no coding or core skill. +- **Rejected alternatives:** + - Carrying it inline in each skill — rejected because the handoff contract would then exist in five places with nothing + canonical, which is the drift problem in a different shape. Simpler on the day it ships and worse afterward. + - Extending the existing escalation rule to cover both — rejected because bending a rule built around a single stop to + also serve a loop that stops constantly weakens it for the four planning skills depending on it today. +- **Linked technical notes:** — +- **Driven by findings:** — +- **Dependent decisions:** — +- **Referenced in spec:** Open Items, What Else Has To Change When This Ships + +### D23: The skill is named pairing, and the phrase people type lives in its description + +- **Question:** Does the skill keep the name the operator first gave it? +- **Decision:** No. It is `pairing`, invoked as `/han-core:pairing`. "Pair with me on" stays as wording in the skill's + description, so nothing about how a person asks for the mode changes. +- **Rationale:** The original name was a sentence addressed to the assistant, where every other skill in the suite is + named for an activity or an artifact. The suite's own naming guidance asks for a gerund process name, which `pairing` + is. Nothing about routing depends on the change, because a request is matched against a skill's description rather than + its name, and the phrase that makes this mode easy to ask for stays exactly where it does its work. +- **Evidence:** User input, choosing this over keeping the original name with a recorded exception and over a name + describing the loop. The naming convention is a checked-in rule in the plugin-building guidance, with a stated heuristic + the original name violated. Review finding F34. +- **Rejected alternatives:** + - Keeping `pair-with-me` and recording why the convention was set aside — rejected in favor of following the convention + rather than carving an exception into it. + - A name describing the loop, such as `collaborative-build` — rejected because `build` pulls back toward code, which is + the framing this mode was deliberately widened away from. +- **Known gap:** The rename fixes the convention complaint and does not fix the scent complaint. `pairing` carries the + same pair-programming associations the original name did, so someone scanning the skills index for help drafting a + stakeholder response is no likelier to stop at it. That load falls on the skill's description, which has to carry the + non-code triggers regardless of what the skill is called. +- **Linked technical notes:** — +- **Driven by findings:** F34 +- **Dependent decisions:** — +- **Referenced in spec:** Open Items diff --git a/docs/plans/pairing-skill/artifacts/implementation-decision-log.md b/docs/plans/pairing-skill/artifacts/implementation-decision-log.md new file mode 100644 index 00000000..56078f40 --- /dev/null +++ b/docs/plans/pairing-skill/artifacts/implementation-decision-log.md @@ -0,0 +1,332 @@ +# Implementation Decision Log: pairing + +Every implementation decision settled while planning how to build `pairing`. Behavioral commitments live in +[../feature-specification.md](../feature-specification.md) and its own decision log; this file records how the work gets +done, not what it does. + +Round-by-round discussion is in +[implementation-iteration-history.md](implementation-iteration-history.md). + +## D-1: The flag travels in the invocation, not as a named caller + +- **Question:** What carries "invoked through the pairing mode" into a backing skill? +- **Decision:** An invocation-scoped argument, in the same shape three of the five skills already use for their size + argument. No backing skill names the mode in its own text. +- **Rationale:** `design-an-api`, `iterative-plan-review`, and `plan-implementation` already declare an `arguments` key + and branch on a selector passed at invocation, without knowing who passed it. Reusing that shape means the + coupling is "this skill accepts an argument," which every reader of this suite recognizes, rather than "this skill + knows a specific other skill can call it." + + The alternative reading of the specification's wording, that each skill's prose says "when invoked through pairing," + is tighter and more fragile. The mode's name already changed once during specification, and five files naming it would + each have needed editing again. +- **Evidence:** Verified directly. `design-an-api`, `iterative-plan-review`, and `plan-implementation` carry + `arguments: size`; `tdd` and `refactor` carry only `argument-hint` and gain an `arguments` key as part of this work. + The suite's composition guidance points the same way twice: it tells an orchestrator to forward the user's request and + the `size` argument through a sub-skill call unchanged, and it tells the orchestrator to state any behavior change as + an explicit instruction in the call rather than assuming the sub-skill will infer it. +- **Rejected alternatives:** + - Prose in each skill naming the mode — rejected as tighter coupling that breaks on a rename, which has already + happened once here. + - A marker file on disk — rejected as invisible state in a working tree that two of the backing skills actively inspect. + - A new frontmatter field or shared detection script — rejected under the YAGNI rule as inventing a mechanism where a + proven one exists. Reopening trigger: the flag needs to carry more than a yes-or-no value. +- **Corrected during implementation.** The argument form did not survive contact with the three skills that already + carry one. Each of them uses the second positional slot for free text — the goal and interface for `design-an-api`, + the plan path for `iterative-plan-review`, the specification path for `plan-implementation` — so a second named + positional argument would collide with the subject the person actually types. The known gap recorded here anticipated + the risk and named the fallback, which is what shipped: the flag rides in the invocation text, and each skill checks + whether the request asks to review each unit as it lands. + + That turned out better than the argument form on two counts beyond avoiding the collision. It is what the composition + guidance prescribes, which is to state an override in the invocation rather than let the sub-skill infer it. And `tdd` + and `refactor` already carry an exception of exactly this shape, gating when the request explicitly asks to review + before implementation, so the flag extends a mechanism those skills have rather than adding a parallel one. + + It also answers OI-1, which asked whether a pairing invocation trips that existing exception. It does, and that is the + intended behavior rather than a conflict. A person who types the same request directly gets the same collaborative + behavior, which is consistent with what those skills already promise rather than a violation of the opt-in rule. + + No skill gained an `arguments` key. The five insertions are one short paragraph each, purely additive, totalling + thirty-three lines across five files. +- **Referenced in plan:** What you are building +- **Driven by rounds:** R1 + +## D-2: The backing skill performs the stop, and the shared rule file is why both sides agree on its shape + +- **Question:** When a backing skill reaches its unit boundary, which skill performs the stop? +- **Decision:** The backing skill does. It owns the boundary and knows when it has reached one. What it presents at that + stop is specified by the shared rule file, which the mode also follows, so a stop looks the same whoever performed it. +- **Rationale:** The mode cannot detect when a behavior has been driven to green or a refactoring has completed; only the + skill doing the work can. Having the mode reach back in would require it to track state inside another skill's loop. + + The suite's composition guidance names this general shape as supported, calling it orchestration composition, and + carries two warnings. The moment after a sub-skill call is when the calling model is most likely to stop and treat the + sub-skill's output as its own final answer, so continuation is instructed explicitly rather than assumed. And the more + the caller carries across the call, the more likely it loses its own workflow. + + The second warning runs against this design rather than supporting it, and the plan says so rather than claiming the + guidance endorses what it does not. The guidance's discipline is a thin orchestrator with little state to lose; this + mode carries a plan, a running feedback record, and the person's position across every stop. What makes that + survivable is that the state is written to a file rather than held in the thread, which the specification already + commits to at D8. Treat the thin-orchestrator rule as a named risk with a named mitigation, not as evidence for the + design. + + This is what makes the rule file load-bearing rather than a convenience. If the five skills each performed a stop in + their own words, a stop would mean five different things. +- **Evidence:** The suite's skill-composition guidance, which names orchestration composition as supported with care and + gives both the thin-orchestrator rule and the explicit-continuation rule. The structure of the five skills, each of + which already closes a unit explicitly. Specification decision D8 for the written feedback record. +- **Rejected alternatives:** + - The mode performs every stop by inspecting the backing skill's progress — rejected because it requires tracking + another skill's internal state, and the guidance says to keep the caller thin for exactly that reason. + - Re-invoking the backing skill once per unit — rejected because none of the five accepts a resume-from-here input, so + each invocation would rebuild its list from scratch. +- **Known gap:** The specific mechanic this decision needs is outside what the guidance covers. Both of its working + examples call a sub-skill once and let it run to completion; neither has a sub-skill that ends its turn partway + through its own run and later resumes with its own instructions still governing. Unverified: could not inspect + whether a skill can end its turn mid-run and resume under its own instructions, because no running session exists in + this repository. Phase 3 observes it on the lowest-churn skill before the contract reaches the two hardest ones. +- **Referenced in plan:** The one thing to get right first +- **Driven by rounds:** R1 + +## D-3: Flag the five skills lowest-churn first + +- **Question:** In what order do the five flag edits land? +- **Decision:** `design-an-api`, `refactor`, `tdd`, `iterative-plan-review`, `plan-implementation`. +- **Rationale:** Two reasons point the same way. Ascending churn puts the edits most likely to collide with in-flight + work last, and the two highest-churn files are also the two whose stop contract is least obvious, because a review + round produces findings rather than a built artifact. Proving the contract on three skills that build something real + means the harder two are written against a pattern that already works. +- **Evidence:** Ninety-day commit counts against each skill file, re-run at synthesis: `plan-implementation` 22, + `iterative-plan-review` 15, `tdd` 12, `refactor` 8, `design-an-api` 3. The discovery pass omitted `design-an-api` from + its churn table because it sat below the table's cutoff, not because it had no commits. +- **Rejected alternatives:** + - Highest-churn first, to get the risky edits over with — rejected because it writes the least-defined contract first. + - All five together — rejected because a mistake in the shared paragraph then exists in five files before anyone sees + it once. +- **Referenced in plan:** Build order, Phase 3, Phase 4 +- **Driven by rounds:** R1 + +## D-4: Vendor the rule file, following the established han-core pattern + +- **Question:** Does the new rule file get vendored into the consuming plugins, or reached some other way? +- **Decision:** Vendored, byte-identical, into `han-coding/references/` and `han-planning/references/`, matching how the + shared configuration, evidence, and YAGNI rules already work. +- **Rationale:** This follows the pattern the consuming skills already use. `tdd` links the YAGNI rule at a path + resolving inside its own plugin, not across into the foundation plugin, and both consuming plugins already declare a + dependency on the foundation, so the direction is sound and declared. + + The competing pattern is real and was weighed. The communication plugin keeps a single canonical copy of its + readability and explanation rules and exposes them through inline skills other plugins invoke by name, with no + vendoring anywhere. That is a genuine alternative and it avoids the re-sync obligation. + + Vendoring won on two grounds. It matches what the five consuming skills already do for every other shared rule, so a + reader meets one pattern rather than two. And the invoke-by-name route would mean adding another skill purely to serve + five consumers, where the existing example serves far more: the discovery pass counted twenty-nine invocations of the + readability-guidance skill alone. +- **Evidence:** The root project map states the vendoring convention and the edit-canonical-then-re-sync obligation + outright. Verified that the three existing shared rules are byte-identical across both consuming plugins. Verified the + communication plugin has no vendored copies of its two canonical rules. +- **Rejected alternatives:** + - An inline guidance skill invoked by name — rejected as adding a skill for five consumers when the proven analogue + serves an order of magnitude more, though it is the better answer if the consumer count ever grows. + - One canonical file with no copies, read across plugin boundaries — rejected because no skill in this repository reads + a reference file from another plugin's installed tree, and the suite's own recorded finding on cross-plugin sourcing + is that `${CLAUDE_PLUGIN_ROOT}` and every relative path resolve inside the reading skill's own plugin, so a + cross-plugin path read would not resolve at all. + - One canonical file consumed only by the mode, with each flagged skill carrying a single inline sentence — rejected + once D-2 settled that the backing skill performs the stop, which means it needs the whole contract rather than one + sentence. +- **Known gap:** Nothing in the repository re-syncs a vendored copy after its canonical file changes, and the only trace + of past sync effort is a manual sweep. D-9 commits a byte-equality check across the copies, which catches a divergence + once it lands but does not prevent one and does not perform the re-sync. Separately, the rule file joins a directory in + the planning plugin that already mixes owned and vendored files, and the project map warns against overwriting an owned + file during a re-sync sweep. The new file is vendored, not owned, and should carry the same header the vendored copies + carry so a future sweep can tell. +- **Referenced in plan:** Build order, Phase 1 +- **Driven by rounds:** R1 + +## D-5: The mode does not declare AskUserQuestion + +- **Question:** Which tools does the mode declare? +- **Decision:** It declares the `Skill` tool, because it invokes others. It does not declare `AskUserQuestion`. +- **Rationale:** The authoring guidance bars `AskUserQuestion` from every skill's `allowed-tools`, not only a parent's. + `allowed-tools` is an auto-approve list, and the permission evaluator returns early on a match, handing back empty + answers without ever rendering the question. Declaring it therefore breaks the tool for the declaring skill outright. + + A parent's always-allow rules also stack onto the skills it calls, so declaring it here would break questions asked + underneath as well. That consequence is concrete rather than hypothetical: `design-an-api` surfaces its open items one + at a time through `AskUserQuestion`, and it works today precisely because no skill in the chain declares the tool. + + Nothing is lost by leaving it out. The mode stops by ending its turn, which needs no tool. Where the specification does + call for candidate options, such as the one question it asks about a request too vague to sort, the tool still works + undeclared; the person sees a one-time permission prompt before the question renders. +- **Evidence:** The suite's authoring guidance on this tool, which states the rule as universal, explains the early + return in the permission evaluator, records the stacking behavior for child skills, and notes that removing the tool + from `allowed-tools` does not break it. Verified that `design-an-api` calls `AskUserQuestion` and that the tool is + absent from its `allowed-tools`. +- **Rejected alternatives:** + - Declaring it for the pre-build ask — rejected because the guidance's rule is universal, that ask is an ordinary turn + ending anyway, and declaring the tool would silently break both the mode's own questions and `design-an-api`'s. +- **Revisit criterion:** The upstream Claude Code bug the guidance cites ships a fix and the guidance is updated to allow + the declaration. +- **Referenced in plan:** Build order, Phase 2 +- **Driven by rounds:** R1 + +## D-6: For a review round, the findings are the checkable claims + +- **Question:** What does a stop present when the backing skill produces findings rather than a built artifact? +- **Decision:** The findings are what you can check, and the plan edits the round made are what changed. The stop keeps + the same shape as any other; only what fills it differs. +- **Rationale:** The stop contract asks for the specific things you can verify and what changed. A review round supplies + both, just not as a file diff. A finding with its citation is precisely a checkable claim, which is the property the + contract is built around. + + Two consequences follow and are settled here rather than left to the implementer. A person's redirect at a stop does + not consume a round against the size-band cap, because a round is a unit of review work and a redirect is not. And at + the smallest size band, `plan-implementation` runs one round and then escalates to the person anyway, so the flag adds + a stop beside one that already exists. That is acceptable rather than a defect: the existing escalation asks a + question, and the flag's stop presents the round's findings, which are different things. +- **Evidence:** Both planning skills cap rounds by size band at one to three. `plan-implementation` places its user + escalation pass immediately after its resolution loop. +- **Rejected alternatives:** + - A separate stop contract for review rounds — rejected because the shared contract already fits once findings are + recognized as checkable claims, and a second contract would defeat the rule file's purpose. +- **Referenced in plan:** Build order, Phase 4 +- **Driven by rounds:** R1 + +## D-7: code-walkthrough's description is tightened to fit its boundary clause + +- **Question:** How do seven descriptions absorb new routing text under a hard character cap? +- **Decision:** Four have room and take the clause as written. `code-walkthrough` does not, so its existing description + is tightened to make room before the clause is added. +- **Rationale:** The authoring standard holds every description to 1024 characters, which is the stricter of the two real + limits: a hard cap where a skill is uploaded rather than listed, against a looser per-entry cap in the listing path. + Measured headroom against that target: `code-walkthrough` 69, `design-an-api` 137, `tdd` 169, `refactor` 315, + `iterative-plan-review` 482, `plan-implementation` 544. The clause `code-walkthrough` needs, distinguishing pacing + through work that already exists from building work while pacing you through it, runs roughly twice its remaining + budget. + + This is worth settling in the plan rather than discovering mid-edit, because the obvious reaction to hitting the cap is + to shorten the new clause, and the new clause is the entire point of the change. +- **Evidence:** Measured against all six existing descriptions with the measurement script the description-length + guidance ships, so the numbers are reproducible by the same method the standard prescribes. +- **Rejected alternatives:** + - Shortening the new boundary clause to fit — rejected because the clause is what prevents a request landing on the + wrong skill, and it is already the shorter half of a bidirectional pair. + - Leaving `code-walkthrough` unchanged — rejected because one-sided disambiguation leaves a gap the request falls + through, which is the failure the pairing has to prevent. +- **Referenced in plan:** Build order, Phase 5 +- **Driven by rounds:** R1 + +## D-8: Three plugins bump, and the meta-plugin follows its existing rule + +- **Question:** Which plugin versions change? +- **Decision:** The three plugins gaining user-visible behavior bump: the foundation plugin gains a skill and a rule + file, and the two plugins carrying flagged skills gain a new argument on those skills. The meta-plugin bumps only if + the repository's existing release practice requires it when a bundled child bumps. +- **Rationale:** Each of the three has a version string appearing in more than one file, so the bump is a multi-file edit + per plugin rather than one. Naming this in the plan prevents the common failure of updating a plugin manifest and + forgetting the marketplace entry carrying the same number. + + The meta-plugin question is deliberately deferred to the release skill rather than answered here. That skill owns + version policy and reads each plugin's manifest to propose bumps, so duplicating its rule in a feature plan is how the + two drift apart. +- **Evidence:** Each plugin's version appears in both its own manifest and the marketplace manifest. The repository has a + dedicated release skill that owns per-plugin versioning and tagging. +- **Rejected alternatives:** + - Deciding the meta-plugin bump here — rejected as duplicating a rule another skill owns. + - One bump covering all three — rejected because the plugins version independently, which is what their separate tags + exist for. +- **Referenced in plan:** Build order, Phase 6 +- **Driven by rounds:** R1 + +## D-9: Seven mechanical checks, and no prose snapshot + +- **Question:** What gets automated? +- **Decision:** Seven checks: the foundation plugin still declares no dependency on the two plugins whose skills it + calls; each changed description stays under its character budget; the rule file resolves from all five consumers; the + vendored copies match the canonical file byte for byte; the four manifests mention the mode; the standard skill + surfaces exist; and each colliding pair names the other in both directions. No snapshot test pins existing prose. +- **Rationale:** Each of the seven can genuinely fail and each failure would mean something real. The dependency check + guards the invariant the whole placement decision rests on, and today that invariant is enforced only by the absence of + a key in a file. The byte-equality check is the only automated guard on the drift D-4 accepts as its cost. + + The snapshot test is the tempting one to add and the right one to skip. It would pin the sentences in each flagged + skill that promise an uninterrupted run, catching a deletion. But the four files it would guard changed twenty-two, + fifteen, twelve, and eight times in ninety days, so it would fire on routine unrelated edits far more often than on a + real regression. A check that cries wolf gets ignored, then deleted. +- **Evidence:** The repository already has a working cross-reference check in Bats to model the resolution check on, and + the description-length guidance ships its own measurement script. Churn figures from the discovery pass. +- **Rejected alternatives:** + - A prose snapshot on the five flagged skills — rejected on the churn evidence above. Running each skill directly plus + ordinary diff review covers the same concern. Reopening trigger: a flagged skill's default behavior actually + regresses into a release. + - A structural additive-only diff check — rejected as tooling that reproduces what review already does at merge time. +- **Referenced in plan:** How anyone knows it worked +- **Driven by rounds:** R1 + +## D-10: No detection script; the mode reacts rather than predicts + +- **Question:** How does the mode know whether a backing skill's plugin is installed? +- **Decision:** It does not check in advance. It names the backing skill it intends to use in the plan it proposes, and + if that skill does not resolve when invoked, it says so and offers the choice between the open-ended path and + installing the plugin. +- **Rationale:** No precedent exists for what a check would even do. Every availability probe in the suite tests for an + external command-line tool; nothing anywhere detects another Han plugin, and the install path such a probe would + inspect is not referenced anywhere in this repository. + + The manifest format cannot express the relationship either. A plugin's `dependencies` entries carry a name, an + optional version range, and an optional marketplace, and every declared dependency is required and auto-installed on + install. There is no optional-dependency form, which is why the specification's "optional backing skills" has to be a + runtime posture rather than a declaration. + + The graceful-degradation guidance that would otherwise apply is about environment state, meaning a missing git history + or configuration file, not about sibling plugins. Stretching it here would mean inventing a path probe on no evidence. + The composition guidance's preflight rule does not reach this either: it says to validate hard requirements before an + expensive sub-skill call, and the specification makes the backing skills explicitly not a requirement. + + Reacting satisfies the same commitment more simply. The specification requires that the mode never substitute + silently, and a failed invocation reported plainly does that. The person also learns the same thing at the same + moment, because the plan named the intended skill one step earlier. +- **Evidence:** Verified that every availability check in the suite probes for an external binary. No plugin-detection + example exists in any plugin. The plugin-manifest reference documents `dependencies` with no optional form. The two + plugins carrying flagged skills go missing independently, so a predictive check would need to run twice. +- **Rejected alternatives:** + - A detection script exiting zero on all paths, per the degradation guidance — rejected under the YAGNI rule as + building a mechanism with no precedent to serve a case the reactive path already handles. It would also need a Bats + test, making it two new artifacts. Reopening trigger: the reactive path proves confusing in real use, or a platform + surface for querying installed plugins appears. + - Declaring the two plugins as manifest dependencies — rejected because the format has no optional form, so declaring + them would make them required and close the dependency cycle the specification's D12 exists to avoid. + - Asking the person up front which plugins they have — rejected because it adds a question to the top of every run and + breaks the specification's promise that the mode needs no precondition beyond a task you can describe. +- **Referenced in plan:** Deferred (YAGNI) +- **Driven by rounds:** R1 + +## D-11: The prose ladder climbs per section once the work is long enough + +- **Question:** Does the fidelity ladder apply to a whole piece of writing or to each of its sections? +- **Decision:** Short work climbs the ladder once, whole. Longer work agrees the shape for the whole artifact first, then + climbs the remaining rungs section by section, with the plan naming the sections up front so they can be redirected. +- **Rationale:** A fixed three-stop ladder breaks at both extremes. On a four-sentence reply it means three stops on four + sentences. On a long document the middle rung is one piece the size of the whole job, which is the unreviewable lump + the mode exists to prevent. The operator's own founding example, pairing on writing a response, could land on either + side of that. + + Agreeing the shape for the whole artifact before sectioning preserves what the evidence actually supports, which is + that structural feedback has to come before surface feedback. Sectioning only the later rungs keeps that order intact. +- **Evidence:** User input, choosing this over a fixed three stops and over letting each plan decide case by case. +- **Rejected alternatives:** + - Always three stops per artifact — rejected because it produces an unreviewable middle rung on long work. + - Letting the proposed plan decide each time — rejected because it drops prose to the same footing as the case the + research rates Low confidence, when prose has a Medium-confidence unit available. +- **Known gap:** Neither the section boundary nor the length threshold has evidence behind it. The underlying prose unit + is already the Medium-confidence part of this design, described in the research as a reconciliation rather than a + documented practice, and this decision adds a second judgment on top of it. Both should be treated as provisional and + revisited after real use. This is also the one commitment in this file that is behavioral rather than procedural: it + answers a question the specification left open rather than deciding how to build something the specification already + settled, so it is written into the mode in Phase 2 and belongs upstream if the specification is ever reopened. +- **Referenced in plan:** Build order, Phase 2 +- **Driven by rounds:** R1 diff --git a/docs/plans/pairing-skill/artifacts/implementation-iteration-history.md b/docs/plans/pairing-skill/artifacts/implementation-iteration-history.md new file mode 100644 index 00000000..43dee748 --- /dev/null +++ b/docs/plans/pairing-skill/artifacts/implementation-iteration-history.md @@ -0,0 +1,163 @@ +# Implementation Iteration History: pairing + +Round-by-round record of the specialists engaged, what each raised, and how every open question was settled. Decisions +committed from these rounds are in [implementation-decision-log.md](implementation-decision-log.md); the plan itself is +[../feature-implementation-plan.md](../feature-implementation-plan.md). + +## R1 + +**Specialists engaged:** `han-core:structural-analyst`, `han-core:test-engineer`, `han-core:junior-developer`. Launched +in parallel with domain-scoped briefs plus the discovery notes. + +**Size:** Medium, two chosen specialists, round cap 2. Three plugins and four manifests put it past small; nothing +crosses a service, touches authentication or personal data, or moves data, so the large-band signals are all absent. + +**New input provided:** The feature specification and its three artifacts, the discovery notes, and the recorded scope +boundary. + +### Claim ledger + +Merged by substance first. Findings raised independently by two specialists carry both identifiers. + +| # | Claim | Raised by | Status | Where it landed | +| --- | --- | --- | --- | --- | +| I1 | The flag needs a carrier, and three of the five skills already have the mechanism | S3, S8, JD-002 | Evidenced, verified directly | D-1 | +| I2 | How control returns from a backing skill is the load-bearing unspecified mechanic | JD-001 | Partly unverified; general shape resolved from guidance, mid-run handback left open | D-2, and D-2's known gap | +| I3 | The faster-gear offer outlived the removal of its own premise | JD-017 | Evidenced | Deferred in the specification | +| I4 | The rule file's access mechanism was not settled by the decision that placed it | S4, JD-008, JD-016 | Evidenced | D-4 | +| I5 | Four descriptions must grow under a hard cap, and one has almost no room | T2, T6 | Evidenced, measured directly | D-7 | +| I6 | No precedent exists for detecting whether a sibling plugin is installed | JD-004, T7 | Unverified, resolved by removing the need | D-10 | +| I7 | The prose ladder yields three pieces regardless of size | JD-006 | Escalated | D-11, and plan phase 2 | +| I8 | A review round produces findings, not an artifact, and the stop contract has no shape for that | JD-010 | Evidenced | D-6 | +| I9 | The two highest-churn files in the repository are both flagged skills | S5, JD-015 | Evidenced | D-3 | +| I10 | Verification is entirely manual and was unplanned | JD-013, T8–T11 | Evidenced | D-9, plan verification section | +| I11 | A prose snapshot would fire on churn far more often than on a regression | S1 (deferral), JD-013 | Evidenced | D-9 | +| I12 | Granting the question tool at the parent would silently break every child's questions | JD-002 (secondary) | Evidenced, narrowed at synthesis | D-5 | +| I13 | The manifest format has no optional-dependency mechanism | S2 | Evidenced, verified at synthesis | D-10 | +| I14 | The specification said the flag reaches three plugins; it reaches two | JD-011 | Evidenced, corrected | Specification | +| I15 | Two decision-log entries still described three skills and one plugin | JD-012 | Evidenced, corrected | Specification decision log | +| I16 | Step 8 routed the in-place-fix branch to a pre-build ask on a piece already built | JD-007 | Evidenced, corrected | Specification | +| I17 | Both coding skills already gate when asked to review first, which a pairing invocation may trip | JD-003 | Open, non-blocking | OI-1 | +| I18 | The foundation plugin gains a second kind of responsibility | S6 | Accepted, already decided at specification stage | Plan, phase 6 | +| I19 | Five near-identical flag paragraphs risk drifting apart | S7 | Evidenced | D-2, D-9; plan phases 3 and 4 | +| I20 | The documentation tail is a phase, not a checklist item | JD-014 | Evidenced | Plan, phase 6 | + +### Unverified findings + +Three findings carried a disclosure that their author could not inspect the input the finding rests on. Under the +unverified rule none of them carries build-blocking severity, whatever their author's own severity rating said. + +- **I2**, on how control returns: could not inspect whether a skill can end its turn mid-run and resume with its + instructions still governing, because no running session exists in this repository. +- **I6**, on plugin detection: could not inspect the runtime plugin-discovery surface, for the same reason. +- **I4**, in part: could not inspect whether a skill in one plugin can read a reference file from another plugin's + installed tree. + +A fourth disclosure was checkable and I checked it. The generalist could not read the chunk-boundary research report and +raised the possibility that it already carries a test for a choice being expensive to walk back. It does not. The +framework there separates reversible from irreversible decisions and prescribes different review depth for each, but +defines no criterion for telling them apart. The report says as much itself, noting that the framework calibrates how +much scrutiny rather than where the boundary falls. The hopeful reading was wrong, so the criterion had to be authored +rather than lifted. + +### Open questions and how each resolved + +Nine were raised. One reached the operator. + +**Resolved from evidence, without reframing:** + +- **The flag's carrier.** Verified directly that `design-an-api`, `iterative-plan-review`, and `plan-implementation` + already declare an `arguments` key, while `tdd` and `refactor` do not. The composition guidance independently + prescribes forwarding arguments through a sub-skill call. Settled as D-1. +- **How control returns.** The composition guidance documents orchestration composition as supported, tells the caller + to stay thin, and warns that the moment after a sub-skill call is when the calling model most often stops and treats + the sub-skill's output as final. That settles the shape: the skill owning the boundary performs the stop, and the + shared rule file is what makes every stop look alike. Settled as D-2, with the part the guidance does not cover + recorded as a known gap rather than treated as answered. +- **The rule file's access mechanism.** Verified that the three existing shared rules are byte-identical across both + consuming plugins and that the communication plugin uses the competing pattern with no copies at all. Both patterns + are real; vendoring won because it matches what the five consuming skills already do. Settled as D-4, with the + re-sync obligation recorded as a known gap rather than waved off. +- **Description budgets.** Measured all six with the script the description-length guidance ships. Settled as D-7. +- **Plugin detection.** Verified that every availability check in the suite probes for an external binary and that no + plugin-detection example exists anywhere. Rather than invent one, the need was removed: the mode names its intended + backing skill in the plan and reports a failed invocation. Settled as D-10. +- **The review-round stop contract.** A finding with its citation is already a checkable claim, which is what the stop + contract asks for. Settled as D-6. +- **The faster-gear offer.** Synthesis had already struck the claim that a run of approvals means anything; the offer + built on it survived. Deferred with a reopening trigger. + +**Escalated to the operator:** + +- **The prose ladder's granularity.** Not resolvable from evidence, because the research supplies no unit for prose at + either granularity and the specification already rates this the Medium-confidence part of the design. Both failure + shapes were concrete: three stops on a four-sentence reply, or one unreviewable middle rung on a long document, with + the operator's own founding example landing on either side. See E-1. + +**Left open, non-blocking:** + +- **Whether a pairing invocation trips the existing review-first gate** in the two coding skills. Recorded as OI-1. It is + settled by building the first flag insertion and observing the behavior, and the answer changes one paragraph in two + skills rather than the design. + +### Corrections applied to upstream records + +Three errors in the specification and its decision log were found by the round and corrected rather than escalated, +because the underlying decisions were unambiguous and only the prose had gone stale. + +- The specification said the flag reaches three plugins. It reaches two: three skills in `han-coding` and two in + `han-planning`. This error was mine, introduced in the correction pass immediately before this round. +- Two decision-log entries still described three skills and named only `han-coding` as the plugin whose absence matters. + Both plugins go missing independently, which widens the degradation case. +- The primary flow routed the in-place-fix branch back to the step that asks for a read before building, on a piece + already built. Split into its two branches with distinct return targets. + +### Corrections applied at synthesis + +A reconciliation pass after the round re-checked every claim in the ledger against the three cited guidance documents +and against the plan. It changed no decision, and it changed what several of them rest on. + +- **D-2 overstated the guidance.** The thin-orchestrator rule was cited as support for the design when the design runs + against it: this mode carries a plan, a feedback record, and the person's position across every stop. The rule is now + recorded as a named risk whose mitigation is the specification's written feedback record. The mid-run handback the + flag depends on is outside anything the guidance covers, and is now a known gap on D-2 and a named paragraph in the + plan rather than an implicit assumption. +- **D-5 misstated its own rule.** The prohibition on `AskUserQuestion` in `allowed-tools` is universal across every + skill, not a parent-only concern, and the tool still works when left undeclared. The stacking effect is a second + consequence rather than the whole reason, and its concrete victim is `design-an-api`, the one backing skill that calls + the tool today. +- **I13 had no home.** It was recorded as landing in D-4's reasoning, which never carried it. Verified against the + plugin-manifest reference that `dependencies` has no optional form, and moved it to D-10, where it does work. +- **I19 was mapped to D-2 and D-4 with no treatment of its own.** Its mitigation now appears where it acts: the + insertion into each flagged skill points at the rule file rather than restating it, in both phase 3 and phase 4, and + D-9's byte-equality check across the vendored copies is the automated half. +- **The plan had lost a mechanical check.** D-9 commits seven; the plan listed six, having dropped the byte-equality + check on the vendored copies. Restored, and D-4's known gap corrected, since it claimed content equality was + unchecked. +- **D-11 was absent from the plan.** The operator's escalation answer was recorded here and in the decision log but + reached no plan section. It now lands in phase 2, where the mode is written. +- **Description budgets re-measured** with the script the description-length guidance ships. All six figures held. + +### Spec-maturity + +No technical-notes file exists for this feature, so the contradiction classification does not apply and the gate reduces +to the specification-level threshold alone. One finding qualified as specification-level, I7, and it was escalated and +answered within the round. The gate did not trip, and no facilitation pass was dispatched. + +### Next-step recommendation + +**Go to synthesis.** The round produced no unresolved blocking finding. Every open question is settled by evidence, by +operator answer, or recorded as non-blocking. The round cap was 2 and one round was used. + +## Escalation register + +### E-1: How should the prose fidelity ladder scale with the size of the writing? + +- **Asked because:** A fixed three-rung ladder means three stops on a four-sentence reply, and on a long document the + middle rung is one piece the size of the whole job, which is the outcome the mode exists to prevent. +- **Answer:** Per section once the work is long enough. Short work climbs the ladder once, whole. Longer work agrees the + shape for the whole artifact first, then climbs the remaining rungs section by section, with the plan naming the + sections up front. The operator chose this over a fixed three stops per artifact and over letting each proposed plan + decide case by case. +- **Landed in:** [D-11](implementation-decision-log.md#d-11-the-prose-ladder-climbs-per-section-once-the-work-is-long-enough), + and phase 2 of the plan. diff --git a/docs/plans/pairing-skill/artifacts/scope-boundary.md b/docs/plans/pairing-skill/artifacts/scope-boundary.md new file mode 100644 index 00000000..ee5133d4 --- /dev/null +++ b/docs/plans/pairing-skill/artifacts/scope-boundary.md @@ -0,0 +1,110 @@ +# Scope Boundary: pairing collaborative working-mode skill + +## Work Item + +No ticket, issue, or pull request exists. The operator's typed request across this session is the only boundary this run +has. The request was refined over five turns, widened materially at the fifth, and is backed by a research report the +same session produced at `docs/research/collaborative-output-style.md`. + +## Stated Scope + +Quoted from the operator, in the order stated. The last quote governs where it widens the earlier ones. + +The original goal: + +> the goal is for me to let claude loose on implementation, have it build out the first chunk, walk me through it like +> the code-walkthrough skill, let me review and ask questions to help guide it's implementation, have it make +> adjustments based on my feedback and questions, have it use that feedback in the next steps to help guide it better, +> and then loop this whole process for the next chunk of work it's going to do. i want to collaborate with claude, not +> just direct it. think "human in the lead", not "human in the loop" + +The decision on shape: + +> i'm ok with an opt-in workflow. i'd rather have that, than force tdd or any other skill into this mode. + +The decision on naming and handoff: + +> i would prever to go with option 2. tdd gains the opt-in collaborative flag. i'd also like to call this new skill +> `/han-coding:pair-with-me` with the intent of a prompt like "pair with me on tdd for this", "pair with me on +> refactoring", "pair with me on implementing", etc. + +The decision on which skills gain the flag, answering a survey of every skill in the plugins not ruled out: + +> Both, in this spec + +That is `tdd` and `refactor`. The operator ruled out `han-reporting`, `han-feedback`, and `han-plugin-builder` from the +survey up front. + +**Amended during the review round.** Two operator answers given after this record was last rewritten change what it says +above, and are recorded here so this record does not read as governing on its own. Both are in the escalation register in +[team-findings.md](team-findings.md). + +- The survey answer above is no longer the whole set. `design-an-api` also gains the collaborative flag (E5), and + re-running the widened test across every skill in the plugins not ruled out added `iterative-plan-review` and + `plan-implementation` (E7, E8). Five skills carry the flag. +- The skill is invoked as `/han-core:pairing` rather than the `/han-coding:pair-with-me` name quoted above (E1, + reconfirmed at E4 and renamed at E9), and the skills it hands work to are optional rather than required. + +**The widening.** At the fifth turn the operator established that the mode is not specific to writing code: + +> consider, for example, "pair with me on designing an API for {thing i'm working on}" - this isn't an implementation +> pairing. instead, it's an api design pairing that would be followed up by an implementation (either pairing or claude +> running on it's own). also, consider "pair with me on writing a response to this question ..." - this is more open +> ended. generally, though, "pair with me on implementing {thing}" shouldn't assume tdd vs refactoring vs prototyping +> the shape of the code and then doing the full tdd or refactoring, etc. + +The scope is therefore a collaborative working mode over any kind of work, with code as one case among several. Three +kinds are named: pairing backed by an existing skill, pairing on design work that produces a decision rather than code, +and open-ended pairing with no backing skill at all. The front door does not choose the discipline for the operator. + +## Stated Exclusions + +Quoted from the operator. + +> force tdd or any other skill into this mode + +No mandatory change to any existing skill's default behavior. Every flag added is opt-in, and an existing invocation +behaves exactly as it does today. + +The operator accepted the research report's recommendation of one skill and no output style, which excludes building an +output style, a session-start hook, or a post-edit hook as part of this work. The widening above reopens the reasoning +behind that choice, because a mode covering any kind of work has a larger surface than a code-only mode. The operator's +decision stands until they revisit it; it is recorded here as a known input change rather than a settled re-decision. + +## Operator-Stated Scope + +> run /plan-a-feature with that context. commit and push as you go + +and, on the widened scope: + +> The general one, with a narrow research pass first. + +The operator asked for a feature specification, not an implementation, and directed that a narrow research pass on one +open question run before planning resumes. Committing and pushing as the run proceeds is a process instruction rather +than feature behavior, and is recorded here so a later skill does not read it as scope. + +## Direction of Travel + +Answered. The operator stated: + +> All four stay, nothing is being replaced. + +The four are `tdd`, `refactor`, `code-walkthrough`, and the wider set of skills someone might pair on. None is being +deprecated, replaced, or migrated away from. `pairing` borrows `code-walkthrough`'s pacing without changing it, and +every flag added leaves every existing invocation behaving as it does today. + +## Visual Material Received + +None received. + +## Record Provenance + +Established by `han-planning:plan-a-feature` in this run. Not inherited from another folder. + +Rewritten once, at the fifth turn, when the operator widened the scope from a code-only collaborative loop to a general +collaborative working mode. The narrower first version is in this file's git history. No conflict was resolved between +two work items, because only one exists: the operator's own request. + +Amended again during synthesis, to record the two operator answers the review round produced, and once more when the +specification's three open items were settled. No quoted material has been changed at any point. Every amendment sits +beside the quote it qualifies, so the operator's original words still read as they were typed. diff --git a/docs/plans/pairing-skill/artifacts/team-findings.md b/docs/plans/pairing-skill/artifacts/team-findings.md new file mode 100644 index 00000000..4fd03400 --- /dev/null +++ b/docs/plans/pairing-skill/artifacts/team-findings.md @@ -0,0 +1,507 @@ +# Team Findings: pairing + +This file records every finding raised by the review team for `pairing`, and how each was resolved. Behavioral +outcomes live in [../feature-specification.md](../feature-specification.md); the decisions those findings affected live in +[decision-log.md](decision-log.md). No `feature-technical-notes.md` was created for this feature, because no mechanic +qualified as load-bearing and not discoverable from the repository. + +Three reviewers ran in parallel: `han-core:junior-developer` over the whole artifact set, `han-core:user-experience-designer` +over the interaction model, and `han-core:information-architect` over routing, placement, and documentation surfaces. +Several findings were raised by two reviewers independently and are merged into one record here, carrying both original +identifiers. + +## Major findings + +### F1: The guard against nodding through fired after the choice it was meant to guard + +- **Agent:** junior-developer, user-experience-designer +- **Reviewer identifiers:** JD-004, UX-008 +- **Finding:** The ask sat at the stop, which comes after the piece is built. Both studies behind it work by having the + person commit before the assistant's answer exists. With the work already produced, the ask is retrospective: it buys + the measured satisfaction cost and none of the measured benefit. The junior developer traced this to the reversibility + framework, which prescribes deliberate review before an irreversible choice, not after. +- **Resolution:** The ask moved ahead of the build, for pieces the plan marked as carrying a hard-to-reverse choice. The + operator's answer about frequency is untouched; only the ordering changed. +- **Resolved by:** evidence +- **Affected decisions:** D7, D14 +- **Changed in spec:** Primary Flow + +### F2: A stop could demand a judgment with no accepted way to decline + +- **Agent:** user-experience-designer +- **Reviewer identifiers:** UX-007 +- **Finding:** Nothing said whether "I don't know" or "just show me" was an acceptable answer. The study behind the ask + found its benefit concentrated in people already inclined toward effortful thinking, so a mandatory guess taxes the + fatigued, the second-language, and the newly-arrived reader hardest while returning them the least. Without an accepted + non-answer the friction becomes a gate, and the rational response to a gate is to leave the mode. +- **Resolution:** Declining is now a first-class answer that advances the stop unchanged. +- **Resolved by:** evidence +- **Affected decisions:** D7 +- **Changed in spec:** Primary Flow, User Interactions + +### F3: The reveal after the ask was unspecified, and two of its likely shapes break the design + +- **Agent:** user-experience-designer +- **Reviewer identifiers:** UX-007 +- **Finding:** The specification ended at the ask. If the reveal grades the guess, the stop becomes a quiz that corrects + you at the highest-stakes moment in the session, and you learn to answer noncommittally. If it defends a divergence, it + leads with the fluent case that D6 rules out on evidence, at the stop where over-reliance costs most. +- **Resolution:** The reveal presents the work in the same form as any other stop. It does not restate your read, score + it, or defend a divergence from it. +- **Resolved by:** evidence +- **Affected decisions:** D7 +- **Changed in spec:** Primary Flow + +### F4: The reversibility judgment was silent and uncontestable + +- **Agent:** user-experience-designer, junior-developer +- **Reviewer identifiers:** UX-008, JD-004 +- **Finding:** No test said what "expensive to walk back" meant, nothing disclosed the call, and nothing let the person + overturn it. The framework it rests on treats reversibility as an explicit shared classification whose value is in being + visible and arguable. Unannounced, the friction is unpredictable, and the promise that it fires only where warranted is + unverifiable from the person's seat. +- **Resolution:** The plan proposed before work starts names which pieces it expects to carry such a choice, making the + call contestable at plan time. +- **Resolved by:** evidence +- **Affected decisions:** D14 +- **Changed in spec:** Primary Flow + +### F5: The record governing every later piece was one the person could never read + +- **Agent:** user-experience-designer, junior-developer +- **Reviewer identifiers:** UX-006, JD-013 +- **Finding:** The record was written, read by the mode, and survived compaction, but nothing said the person could read + it. A misrecorded correction would then govern the rest of the session and surface only as work that feels subtly wrong. + That is the mid-context recall failure the record exists to prevent, imposed on the person instead. +- **Resolution:** The record is readable on request, and when the mode applies a recorded entry to a later piece it names + which entry it applied. +- **Resolved by:** evidence +- **Affected decisions:** D8 +- **Changed in spec:** Primary Flow, User Interactions, Coordinations + +### F6: Contradiction detection was the expensive way to reach a cheap outcome + +- **Agent:** user-experience-designer, junior-developer +- **Reviewer identifiers:** UX-016, JD-016 +- **Finding:** `Category: YAGNI candidate`. No user-described need, incident, or measurement supported it, and it was the + most expensive behavior proposed for this mode: a semantic comparison of every new remark against the whole record, at + every stop. A false positive costs a turn defending feedback never contradicted; a false negative protects nothing. +- **Resolution:** Deferred with a reopening trigger. F5's entry attribution satisfies the same concern with no detection + capability and no false positives, and the person catches the conflict with the entry in front of them. +- **Resolved by:** evidence +- **Affected decisions:** D8 +- **Changed in spec:** Edge Cases and Failure Modes, Deferred (YAGNI) + +### F7: The four kinds were not mutually exclusive and nothing broke a tie + +- **Agent:** junior-developer +- **Reviewer identifiers:** JD-003 +- **Finding:** Drafting a decision record produces a decision and prose. The operator's own prose example was described by + the operator as open-ended, so a single example spanned two kinds. Everything downstream keys off the sort, so two runs + on the same request could sort differently and produce different loops. The suite's own precedent is to name the test + rather than say the mode identifies the answer. +- **Resolution:** An ordered test with a first-match rule, so the order is the tie-break. +- **Resolved by:** evidence +- **Affected decisions:** D3 +- **Changed in spec:** Primary Flow + +### F8: The sort was never disclosed, so its premise could not be corrected + +- **Agent:** user-experience-designer +- **Reviewer identifiers:** UX-009 +- **Finding:** The sort is the largest single determinant of the experience, setting how often the person is interrupted + and what they review. A proposal is correctable only if the person can see it. Someone whose design document sorted as + open-ended rather than prose would see a plan they vaguely dislike with no vocabulary for what is wrong. +- **Resolution:** The proposed plan names which kind the work sorted into. +- **Resolved by:** evidence +- **Affected decisions:** D3 +- **Changed in spec:** Primary Flow + +### F9: The fourth kind changed no behavior + +- **Agent:** junior-developer +- **Reviewer identifiers:** JD-015 +- **Finding:** `Category: YAGNI candidate`, named anti-pattern symmetry. The open-ended branch produced "whatever the plan + named," which is what the plan does regardless of kind. A four-way sort with a no-op fourth branch makes the sort harder + for no behavior change, and later skills would copy the pattern. +- **Resolution:** Collapsed to three tests plus a fall-through. +- **Resolved by:** evidence +- **Affected decisions:** D3, D13 +- **Changed in spec:** Primary Flow + +### F10: The mode's own founding example routed to a thinner result + +- **Agent:** information-architect +- **Reviewer identifiers:** IA-003 +- **Finding:** Pairing on an API design is one of the operator's three founding examples, and the skill covering it was + given no flag. The request therefore sorted past the skill-backed branch into decision work, and the mode would build its + own decision loop beside a skill that already runs discovery, an options document, a question round, and an adversarial + validation round. No description clause fixes it, because there was no paired variant to delegate to. Notably, the + decision to propose rather than ask cites that same skill as its precedent without noticing it is also a competitor. +- **Resolution:** Escalated. The operator gave that skill the flag, which widens the test behind the original survey. The + re-survey under the wider test is recorded as an open item. +- **Resolved by:** user input +- **Affected decisions:** D10 +- **Changed in spec:** Actors and Triggers, Alternate Flows and States, Coordinations, Open Items + +### F11: The plugin placement closed a dependency cycle and broke a documented install + +- **Agent:** junior-developer, information-architect +- **Reviewer identifiers:** JD-001, JD-014, IA-007, IA-008 +- **Finding:** `han-coding` already depends on `han-core`, so a `han-core` skill requiring `han-coding` closes a cycle, and + `han-core`'s stated invariant is that it depends on no other Han plugin. The placement was argued entirely on where the + skill reads right and never checked for whether it builds. Separately, the plugin index offers an install described as + having only the shared agents and project discovery, under which two of the three coordinations do not exist and no + behavior was specified. The information architect added that the plugin's organizing principle, stated identically in its + front door, the plugin index, and three manifests, is shared infrastructure other plugins consume, which a user-facing + working mode is not. +- **Resolution:** Verified directly against the plugin manifests before escalating; the cycle is real. Escalated. The + operator kept the placement and made the backing skills optional, which keeps the invariant literally true because + nothing is required. The relabeling the information architect identified became part of the work. +- **Resolved by:** user input +- **Affected decisions:** D12, D21 +- **Changed in spec:** Actors and Triggers, Edge Cases and Failure Modes, What Else Has To Change When This Ships + +### F12: The pre-work plan promised a list of pieces that did not exist yet + +- **Agent:** user-experience-designer +- **Reviewer identifiers:** UX-010 +- **Finding:** For skill-backed work the pieces are the backing skill's own units, and both backing skills build their + lists partway into their own runs and report them without gating. At the moment the pre-work plan is made, the list does + not exist. The promise was therefore either unmet or a silent change to a backing skill's gating, which D2 forbids, and + the specification did not say which. This lands on the operator's own first named example. +- **Resolution:** The promise splits by kind. For skill-backed work the pre-work plan names the skill, its unit, and the + reason; the skill's own list becomes the plan of pieces at the first stop, where it can still be redirected. +- **Resolved by:** evidence +- **Affected decisions:** D15 +- **Changed in spec:** Primary Flow + +### F13: No stop said where the person was in the plan + +- **Agent:** user-experience-designer +- **Reviewer identifiers:** UX-002 +- **Finding:** Both commitments were local to the piece in hand plus a one-step lookahead. Neither named the current + position, what remained, or the plan as it stands after a renegotiation. Two conventions already in this suite carry + exactly this, and the backing skills carry it too by crossing items off a list. Without it the person cannot decide + whether they have the attention for two more pieces. +- **Resolution:** Each stop names which piece this is against the plan and what remains, and the plan is available on + request. +- **Resolved by:** evidence +- **Affected decisions:** D16 +- **Changed in spec:** Primary Flow, User Interactions + +### F14: The compaction row restored the assistant's continuity and not the person's + +- **Agent:** user-experience-designer, junior-developer +- **Reviewer identifiers:** UX-015, JD-007 +- **Finding:** The row addressed only the record surviving. The person returns to a terminal where the last stop has + scrolled away and must reconstruct which piece was in hand. The mode's own evidence measures that cost at an average of + 23 minutes and 15 seconds to resume at full focus. Continuity solved for the assistant and left unsolved for the person + inverts the premise that the person is in the lead. +- **Resolution:** On resuming, the mode restates the piece in hand and its position before continuing. +- **Resolved by:** evidence +- **Affected decisions:** D16 +- **Changed in spec:** Edge Cases and Failure Modes + +### F15: The specification claimed a guarantee its own research says nothing can provide + +- **Agent:** junior-developer +- **Reviewer identifiers:** JD-006 +- **Finding:** "Nothing further is built until you respond" was stated as a hard guarantee. The collaborative-mode research + is explicit that every option relies on the assistant following an instruction, and options differ in how much weight + the instruction carries rather than in whether it can be enforced. No behavior was specified for an overrun, which is + the most likely real failure of the feature, and the tendency is real in the very skill being flagged. +- **Resolution:** Softened to a directive, with an edge-case row specifying that an overrun is named, its unreviewed pieces + listed, and a walk-back offered. +- **Resolved by:** evidence +- **Affected decisions:** D17 +- **Changed in spec:** Primary Flow, Edge Cases and Failure Modes + +### F16: Nothing bounded replanning, and the specification did not say that was deliberate + +- **Agent:** junior-developer +- **Reviewer identifiers:** JD-021 +- **Finding:** With the plan reopenable on any out-of-piece feedback, "the plan is finished" is not a fixed target and + ending is left entirely to the person. That may be right, but unstated it reads as a gap. +- **Resolution:** Stated as deliberate, beside the entry explaining why a computed stop rule does not transfer here. +- **Resolved by:** evidence +- **Affected decisions:** D18 +- **Changed in spec:** Primary Flow, Out of Scope + +### F17: The loop had two gears and the only gear change was one-way + +- **Agent:** user-experience-designer +- **Reviewer identifiers:** UX-001 +- **Finding:** The person at their eleventh stop, tired but not finished reviewing, could continue at full ceremony or turn + review off for the remainder. That is the shape the mode's own evidence warns about, since review quality decays into + rubber-stamping past a volume threshold and the only escape offered is to stop reviewing entirely. The walkthrough + convention the specification claims to inherit already carries an exception for an explicit request for several steps, + and it was dropped in translation. The switch to unattended finishing also had no committed acknowledgement. +- **Resolution:** An explicit request for more than one piece is honored as asked and the loop returns to its normal pace + at the following stop. The switch to unattended finishing is acknowledged in the turn it is requested, naming what will + now go unreviewed. +- **Resolved by:** evidence +- **Affected decisions:** D19 +- **Changed in spec:** Alternate Flows and States, Edge Cases and Failure Modes, User Interactions + +### F18: The invocation contract named two mechanisms and settled neither + +- **Agent:** information-architect +- **Reviewer identifiers:** IA-001 +- **Finding:** One bullet named both a slash command, where everything after it is argument text and no competition occurs, + and open phrasing, where the sentence is matched against every available skill. Whether every collision below fires at + all depends on which is supported, and an implementer could not tell. +- **Resolution:** Split into two named entry paths, with both supported and their different consequences stated. +- **Resolved by:** evidence +- **Affected decisions:** D20 +- **Changed in spec:** Actors and Triggers + +### F19: Every quoted trigger phrase contained another skill's strongest trigger word + +- **Agent:** information-architect +- **Reviewer identifiers:** IA-002 +- **Finding:** The mode's own example phrasings name `tdd` and `refactor` directly, and neither of those skills' routing + text mentions pairing, collaboration, or stopping for review. Whichever answers, one of two failures follows: the person + gets the uninterrupted run this mode exists to replace, or gets stopped at every step when they wanted a straight run. + The deeper problem is that every boundary in the suite is exclusive, and the correct relationship here is delegating, + which the exclusive form cannot express. The suite's own guidance calls one-way disambiguation a gap requests fall + through; here it was zero-way. +- **Resolution:** The specification now commits both sides to saying it, and carries a table of which skill answers for + which kind of phrasing. The routing surface is named as a coordination in its own right. +- **Resolved by:** evidence +- **Affected decisions:** D20 +- **Changed in spec:** Which Skill Answers When You Say It In Your Own Words, Coordinations + +### F20: The pacing skill shares the entire vocabulary and was absent from the coordinations + +- **Agent:** information-architect +- **Reviewer identifiers:** IA-004 +- **Finding:** Every load-bearing phrase in the User Interactions section already belongs to `code-walkthrough`'s trigger + vocabulary. The specification acknowledged the shared convention in prose and then omitted that skill from the + coordination table. The real distinction was available and stated nowhere: that skill paces you through work that already + exists and writes nothing, while this mode builds work while pacing you through it. A person mid-branch asking to be + walked through as it gets built could get a silent no-op. +- **Resolution:** Added as a routing coordination with no runtime handoff, and the produced-versus-existing distinction is + now committed on both sides. +- **Resolved by:** evidence +- **Affected decisions:** D20 +- **Changed in spec:** Which Skill Answers When You Say It In Your Own Words, Coordinations + +### F21: Requests to understand something would receive a plan to build things + +- **Agent:** information-architect +- **Reviewer identifiers:** IA-005 +- **Finding:** All the kinds presupposed a produced artifact. "Help me understand this module" produces understanding, so + it fell through to open-ended and the mode would propose a plan of pieces to build. It sorts cleanly, so the too-vague + guard never trips. The backing research addresses producing and never explanation. +- **Resolution:** An edge-case row stating this is not the mode's work and naming where it goes. A fifth kind was not added, + because no evidence defines a unit for it and adding one would be speculative. +- **Resolved by:** evidence +- **Affected decisions:** — +- **Changed in spec:** Edge Cases and Failure Modes + +### F22: The specification named no documentation surface, specifying the skill as an orphan + +- **Agent:** information-architect +- **Reviewer identifiers:** IA-009 +- **Finding:** The contribution guide enumerates the stops a new skill must make and the specification named none, and the + coverage rule requires the long-form document to land in the same pull request rather than as a follow-up. Two further + groups become inaccurate on the day this ships: the plugin's identity in its front door, index entry, and manifests, and + the operator manuals plus routing text of the skills gaining the flag. +- **Resolution:** A specification section naming the three groups, plus the note that the mode takes no size argument so + the sizing documentation does not apply. +- **Resolved by:** evidence +- **Affected decisions:** D21 +- **Changed in spec:** What Else Has To Change When This Ships + +### F23: Confidence caveats sat only in the artifact that declares itself non-normative + +- **Agent:** junior-developer, information-architect +- **Reviewer identifiers:** JD-011, JD-005, JD-010, IA-010 +- **Finding:** The research rates staging by concern High, the per-kind units Medium, and open-ended work Low, and says + that if the prose reconciliation is wrong then prose work has no evidenced unit at all. The specification presented all + rows at equal weight, and the decision log that carries the caveats states in its own opening that behavior lives in the + specification. An implementation plan reading the specification alone would treat the prose ladder and the + skill-backed unit as equally settled. The nodding-through row separately attributed the whole guard to how a stop is + presented, which the research does not support: that is a trend over time, and no study compares degradation with and + without an objective gate. +- **Resolution:** A confidence section in the specification naming which parts are High, Medium, and Low. The + nodding-through row's rationale was corrected to say what the mode declines to do rather than claiming the guard works. + The corrected row initially replaced the unsupported claim with a second one, that a run of silent approvals more + likely signals a wish for a different pace than a lapse in care; synthesis removed it, because no evidence in either + report speaks to what a run of approvals signals. The row now states only that the mode does not read approvals as a + lapse in care and may offer the faster gear once. +- **Resolved by:** evidence +- **Affected decisions:** D13 +- **Changed in spec:** How Confident Each Part of This Design Is, Edge Cases and Failure Modes + +### F24: A plan reopening the person did not request had no way back + +- **Agent:** user-experience-designer +- **Reviewer identifiers:** UX-005 +- **Finding:** The mode, not the person, decides that a remark reaches outside the piece, and that determination replaces + the plan the person agreed to. The stated exits were accept or change, neither of which is "keep the plan, treat that as + a note for later." Someone thinking out loud, which is the working style this mode is built for, triggers a replan they + did not ask for. +- **Resolution:** The mode names its reading before acting on it, and a third exit declines the reopening and records the + feedback as scoped to later work. +- **Resolved by:** evidence +- **Affected decisions:** D9 +- **Changed in spec:** Alternate Flows and States + +### F25: The re-show after a fix said nothing about what changed + +- **Agent:** user-experience-designer +- **Reviewer identifiers:** UX-003 +- **Finding:** "Shown to you again" was the whole commitment. To confirm the correction landed and nothing else moved, the + person had to re-read reviewed material and hold the first version in memory to compare. That works directly against the + evidence behind presenting checkable claims, whose mechanism is lowering the cost of checking, and raises it at the + moment the person is most invested. +- **Resolution:** The re-show names the correction it applied and what it touched before restating the piece, in prose so + it reads aloud rather than depending on a side-by-side comparison. +- **Resolved by:** evidence +- **Affected decisions:** D9 +- **Changed in spec:** Primary Flow + +### F26: Ending the loop left in-flight work in an unstated state + +- **Agent:** junior-developer +- **Reviewer identifiers:** JD-020 +- **Finding:** If a backing skill was mid-cycle when the person stopped, files are edited and possibly failing. The exit + said nothing about whether the mode reports the state of the tree. The backing skills' own stop rules do report where + things stand, but the loop's exit did not say it inherits that. +- **Resolution:** The exit report covers the state of any work a backing skill left mid-cycle, and names where the feedback + record was written. +- **Resolved by:** evidence +- **Affected decisions:** D18 +- **Changed in spec:** Alternate Flows and States + +### F27: A multi-approach plan reliably trips a backing skill's own precondition + +- **Agent:** junior-developer +- **Reviewer identifiers:** JD-017 +- **Finding:** The specification permits a request spanning approaches, such as sketching a shape and then building it + test-first. One backing skill refuses to run alongside an in-flight test-driven loop. A plan sequencing them will hit + that stop if the first loop is not fully closed, and the person experiences it as the mode contradicting its own plan. + The reviewer noted it had read only the stop-rule regions of both skills rather than their full precondition sets. +- **Resolution:** The plan orders sequenced backing skills so each skill's own preconditions hold when its turn arrives. +- **Resolved by:** evidence +- **Affected decisions:** D11 +- **Changed in spec:** Alternate Flows and States + +### F34: The name broke the suite's own naming convention and under-scented for non-code work + +- **Agent:** information-architect +- **Reviewer identifiers:** IA-006 +- **Finding:** The name was an imperative sentence addressed to the assistant, where every other skill in the suite is + named for an activity or an artifact, and the plugin-building guidance asks for a gerund process name with a stated + heuristic the original name violated. Three costs followed: it set a precedent a future skill author would read as + sanctioned, it carried pair-programming associations the mode does not meet, and someone scanning the skills index for + help with prose would not stop at it. +- **Resolution:** Escalated after the review round closed, and the operator renamed the skill to `pairing`. "Pair with me + on" stays as description wording, so nothing about how a person asks for the mode changed. The reviewer noted that + routing matches on description rather than name, which is what made the rename free. +- **Resolved by:** user input +- **Affected decisions:** D23 +- **Changed in spec:** the whole document, by rename; Open Items + +## Minor edits + +- F28: The vague-request re-ask posed a blank question, which the same specification rejects elsewhere; it now names what + was ambiguous, offers candidate readings, and defines what happens if the answer is still not enough — + user-experience-designer (UX-013) — Edge Cases and Failure Modes +- F29: "The reasoning is available" was an affordance nothing announced, so in a conversational surface it was functionally + absent; the stop now says so in one line — user-experience-designer (UX-012) — Primary Flow +- F30: The ask posed an open question where the suite's convention gives named candidates; it now names the dimension the + choice turns on, without supplying the answer, which would anchor the guess — user-experience-designer (UX-011) — + Primary Flow +- F31: A coordination row described one component setting a value another reads rather than a behavior; restated as + behavior — junior-developer, user-experience-designer (JD-022, UX-017) — Coordinations +- F32: A hardcoded skill count and plugin count in the boundary record violated the repository's count-free convention; + both removed rather than corrected — junior-developer, information-architect (JD-018, IA-012) — scope-boundary.md +- F33: The summary reported zero open items while the review round had not run — junior-developer (JD-019) — Summary + +## Unaudited evidence classes + +- The two research reports backing this specification. The junior developer and the information architect read them under + explicit authorization; the user-experience designer was authorized for the chunk-boundary report only, so no finding of + theirs rests on the collaborative-mode report, and they said so. No reviewer independently re-verified the external web + sources behind either report, which the reports themselves already flag as a limitation of their own validation. +- Claude Code's live skill-routing behavior. The information architect could not observe how a request naming both a slash + command and a competing skill's trigger word actually routes, because no running session exists in this repository. Every + routing finding therefore rests on reading the competing description text rather than on observed behavior, and the + reviewer disclosed this on each affected finding. The suite's own documented probe would settle it before the skill + ships. +- The full precondition sets of the backing skills. Two reviewers read only the stop-rule and unit-boundary regions + returned by targeted search rather than those skills end to end, and both disclosed it. F27 rests on a partial read. + +Per the unverified rule, no finding above carries build-blocking severity on the strength of an input nobody inspected. +F27's blocking status is limited accordingly. + +## Escalation register + +### E1: Which plugin should carry a pairing mode you would also use on a stakeholder email? + +- **Answer:** `han-core`, invoked as `/han-core:pairing`. The operator chose it over keeping the originally-named + `han-coding` home and over creating a new `han-collaboration` plugin. +- **Landed in:** [D12](decision-log.md#d12-the-skill-lives-in-han-core-and-its-backing-skills-are-optional), and the Actors + and Triggers section of the specification. + +### E2: When your feedback says the piece just built is wrong, does it get fixed now or become the next piece? + +- **Answer:** Fixed now, then shown again before anything new is built. The operator chose this over deferring the + correction to the next piece and over asking each time. +- **Landed in:** [D9](decision-log.md#d9-feedback-condemning-the-piece-in-hand-is-fixed-in-place-and-re-shown), plus the + Primary Flow and Alternate Flows sections of the specification. + +### E3: How much of the guard against nodding through do you want, given that it measurably annoys reviewers? + +- **Answer:** Ask for the operator's own read first only at stops where a mistake is expensive to undo. The operator chose + this over never asking and over asking at every stop. +- **Landed in:** [D7](decision-log.md#d7-the-mode-asks-for-your-read-first-only-where-a-mistake-is-expensive-to-undo), + plus the Primary Flow and User Interactions sections of the specification. + +### E4: The placement creates a dependency cycle and breaks a documented install. How should it resolve? + +- **Answer:** Stay in `han-core` and treat the backing skills as optional. The operator chose this over a new + `han-collaboration` plugin and over returning to `han-coding`. +- **Landed in:** [D12](decision-log.md#d12-the-skill-lives-in-han-core-and-its-backing-skills-are-optional) and + [D21](decision-log.md#d21-the-surfaces-that-stop-being-accurate-are-part-of-this-work), plus the Edge Cases and What Else + Has To Change sections of the specification. + +### E5: Pairing on an API design would route past the skill that already covers it. What should happen? + +- **Answer:** Give that skill the collaborative flag too. The operator chose this over routing to it unpaired and over + letting the mode's own decision loop supersede it. +- **Landed in:** [D10](decision-log.md#d10-five-skills-gain-an-opt-in-collaborative-flag), + plus the Actors and Triggers, Alternate Flows, Coordinations, and Open Items sections of the specification. + +### E6: Where should the stopping and question-asking convention for this mode live? + +- **Answer:** A new canonical rule file owned by `han-core`. The operator chose it over carrying the convention inline + and over extending the existing escalation rule. +- **Landed in:** [D22](decision-log.md#d22-the-stopping-convention-is-a-canonical-rule-file-owned-by-han-core), plus the + Open Items and What Else Has To Change sections of the specification. + +### E7: When should the widened flag test be run against the rest of the suite? + +- **Answer:** Now, before the implementation plan. The operator chose this over deferring it to the implementation plan + and over closing the question at three skills. +- **Landed in:** the survey recorded in E8 below. + +### E8: Two more skills qualify under the widened test. Should they get the flag? + +- **Answer:** Flag both. The operator chose this over flagging `plan-implementation` alone and over keeping the mode at + three skills. The survey covered every skill in the plugins the operator did not rule out; + `iterative-plan-review` and `plan-implementation` were the only additions, and the reasons every other skill failed are + recorded in D10. +- **Landed in:** [D10](decision-log.md#d10-five-skills-gain-an-opt-in-collaborative-flag), plus the Alternate Flows, + Coordinations, and What Else Has To Change sections of the specification. + +### E9: Does the skill keep the name pair-with-me? + +- **Answer:** No. It is renamed to `pairing`, with "pair with me on" kept as description wording. The operator chose this + over keeping the original name with a recorded exception and over a name describing the loop. This overrode the + recommendation, which was to keep the original name. +- **Landed in:** [D23](decision-log.md#d23-the-skill-is-named-pairing-and-the-phrase-people-type-lives-in-its-description), + the specification's Open Items section, and the name of this plan folder. diff --git a/docs/plans/pairing-skill/feature-implementation-plan.md b/docs/plans/pairing-skill/feature-implementation-plan.md new file mode 100644 index 00000000..f69523fc --- /dev/null +++ b/docs/plans/pairing-skill/feature-implementation-plan.md @@ -0,0 +1,298 @@ +# Implementation Plan: pairing + +How to build the `pairing` collaborative working mode, the shared stopping convention it rests on, and the opt-in flag +five existing skills gain. + +The specification is at [feature-specification.md](./feature-specification.md) and settles what the mode does. This plan +settles how it gets built, in what order, and how anyone knows it worked. + +## What you are building + +Seven things, in three groups. + +**The mode itself.** One new skill in `han-core` that sorts the work, proposes where it will stop, builds one piece, +hands it back with things you can check, and waits. + +**The shared contract.** One new rule file in `han-core` describing what a stop presents and what returning control +means. The specification settled that it is a canonical rule file rather than inline text repeated in each skill, +because six places need to agree on the answer and five of them live in other plugins +([D22](artifacts/decision-log.md#d22-the-stopping-convention-is-a-canonical-rule-file-owned-by-han-core)). + +**The flag.** An opt-in argument on five existing skills, so each returns control at the boundary it already has instead +of continuing, with no backing skill — the existing skill doing the work while the mode watches — naming the mode in its +own text +([D-1](artifacts/implementation-decision-log.md#d-1-the-flag-travels-in-the-invocation-not-as-a-named-caller)). +Three of those skills live in `han-coding` and two in `han-planning`. + +Then the tail: seven skill descriptions change, four manifests stop being accurate, and roughly a dozen documentation +surfaces describe a `han-core` that no longer matches what ships. + +## The one thing to get right first + +Everything else in this plan depends on how a backing skill hands control back, so that is settled before anything is +written. + +The suite's authoring guidance documents the general shape, calling it orchestration composition: a calling skill +invokes a sub-skill that owns a whole artifact, and the caller stays thin. + +That guidance carries two warnings that shape this design. The first: the moment after a sub-skill call is when the +calling model is most likely to stop and treat the sub-skill's output as the final answer, so continuation has to be +instructed rather than assumed. The second: the more the caller carries across that call, the more likely it loses its +own thread. + +The second warning cuts against this mode rather than for it, and that is worth saying plainly. Both working examples +the guidance cites call a sub-skill once, let it run to completion, and carry almost nothing across the call. This mode +carries a plan, a running feedback record, and the person's position in that plan across every stop, which is the +opposite of thin. + +What makes that survivable is that the state is written down rather than remembered. The specification already commits +the feedback record to a file +([D8](artifacts/decision-log.md#d8-your-feedback-goes-into-a-readable-written-record-rather-than-being-carried-in-memory)), +so the thread the guidance warns about losing can be re-read rather than recalled. + +So the stop is performed by the skill that owns the boundary, not by the mode reaching back in +([D-2](artifacts/implementation-decision-log.md#d-2-the-backing-skill-performs-the-stop-and-the-shared-rule-file-is-why-both-sides-agree-on-its-shape)). +`tdd` knows when it has finished a behavior; the mode does not. What the mode owns is the plan, the record, and the +shape a stop takes. That shape lives in the rule file, which is why the rule file is load-bearing rather than +documentation. + +One part of this the guidance does not settle, and nothing in this repository can. Neither working example has a +sub-skill that ends its turn partway through its own run and later resumes with its own instructions still governing. +That is exactly what the flag asks the five skills to do. Unverified: could not inspect whether a skill can end its +turn mid-run and resume under its own instructions, because no running session exists in this repository. Phase 3 is +where that first gets observed, on the lowest-churn of the five. + +## User stories + +The specification commits to these behaviors. Each work unit below advances one of them. + +1. **As someone building a feature test-first, I want to review each behavior as it lands**, so I catch a wrong turn at + the second behavior instead of the twelfth. +2. **As someone designing an interface, I want to weigh one decision at a time**, so I am not handed a finished design to + approve or reject whole. +3. **As someone drafting a response, I want to agree the shape before anyone writes sentences**, so the polish is not + thrown away when the shape changes. +4. **As someone whose feedback was recorded early, I want it still applied late**, so I do not repeat myself at every + stop. +5. **As someone who installed only the foundation plugin, I want the mode to work anyway**, so a missing sibling plugin + degrades what I get rather than breaking it. + +## Build order + +Six phases. The order is driven by one constraint and one risk. + +The constraint is mutual reference: the mode's description names the five skills, and each of the five names the mode as +the way to review as it goes. Neither half is accurate alone, so neither ships alone. They can be separate commits +behind one release. + +The risk is churn. Over ninety days `plan-implementation` changed twenty-two times and `iterative-plan-review` fifteen, +which makes them the two most likely to collide with an in-flight edit. + +They are also the two whose stop contract is least obvious, because a review round produces findings rather than an +artifact. They go last, so the contract is proven on easier skills first +([D-3](artifacts/implementation-decision-log.md#d-3-flag-the-five-skills-lowest-churn-first)). + +### Phase 1: The shared rule file + +The only phase that can land on its own. It references nothing and makes no existing statement false, because nothing +consumes it yet. + +It defines what a stop presents, what returning control means, how the flag is detected, and the test for a piece being +expensive to walk back. Fixing all four here is the point: five separate edits in three plugins would otherwise invent +five slightly different answers, which is the drift the file exists to prevent. + +The fourth of those is the one to write carefully, because it has no source. The reversibility framework the +specification rests on says how much scrutiny a choice deserves once you know which kind it is, and says nothing about +how to tell the two kinds apart. That criterion is authored here rather than lifted from anywhere, and it is one of the +two things listed below that nobody can check before real use. + +Touch points: a new file in `han-core/references/`, vendored into `han-coding/references/` and +`han-planning/references/` the way the shared YAGNI, evidence, and configuration rules already are +([D-4](artifacts/implementation-decision-log.md#d-4-vendor-the-rule-file-following-the-established-han-core-pattern)). + +### Phase 2: The mode + +The skill, its detection-free degradation path, and its long-form documentation. + +Touch points: `han-core/skills/pairing/SKILL.md` and `han-core/docs/skills/pairing.md`. + +The skill declares the `Skill` tool in its allowed tools, because it invokes others. It must **not** declare +`AskUserQuestion`. The authoring guidance bars that tool from every skill's allowed-tools list, and a parent's rules +stack onto the skills it calls, so declaring `AskUserQuestion` here would silence the questions `design-an-api` asks +underneath as well +([D-5](artifacts/implementation-decision-log.md#d-5-the-mode-does-not-declare-askuserquestion)). + +Each backing-skill invocation also needs an explicit instruction to return to the loop afterward, because the guidance +names the moment after a sub-skill call as the most common place an orchestration ends early. + +Prose work needs one more thing settled here, the round's only question to reach the operator: a fixed three-rung +fidelity ladder does not scale. On a four-sentence reply it means three stops on four sentences; on a long document, the +middle rung alone is the size of the whole job. Short work climbs the ladder once, whole. Longer work agrees the shape +for the whole artifact first, then climbs the remaining rungs section by section, with the plan naming the sections up +front so they can be redirected +([D-11](artifacts/implementation-decision-log.md#d-11-the-prose-ladder-climbs-per-section-once-the-work-is-long-enough)). + +The specification left this unanswered rather than answering it differently, and neither the section boundary nor the +length threshold has evidence behind it, so both are provisional. + +### Phase 3: The three coding skills + +`design-an-api` first, then `refactor`, then `tdd`, in ascending order of churn. + +Each gains an argument entry and one short paragraph at its existing close, pointing at the vendored rule file rather +than restating the convention. Two reasons to keep that insertion small and referential. A future edit to the +surrounding loop is less likely to absorb or orphan a short paragraph than a long one. Five near-identical +paragraphs each restating the convention in their own words would drift apart edit by edit. That is the failure the +rule file exists to prevent, reintroduced one file at a time. + +`tdd` and `refactor` also gain an `arguments` key, which they lack today. The other three already have one. + +### Phase 4: The two planning skills + +`iterative-plan-review`, then `plan-implementation`. + +The insertion keeps the same shape as Phase 3, short and pointing at the rule file rather than restating it, for the +same anti-drift reason. + +These need something the coding skills do not: a stop contract for a round that produces findings and plan edits rather +than a built artifact. The checkable claims at such a stop are the findings themselves, and what changed is the set of +plan edits the round made +([D-6](artifacts/implementation-decision-log.md#d-6-for-a-review-round-the-findings-are-the-checkable-claims)). + +Both cap their rounds by size band, at one to three. A person's redirect at a stop does not consume a round, because a +round is a unit of review work and a redirect is not. + +### Phase 5: The routing text + +Seven descriptions change: the mode's own, the five flagged skills, and `code-walkthrough`. + +**`code-walkthrough` has a budget problem.** The authoring standard holds every description to 1024 characters, which is +a hard cap on the surface where a skill is uploaded rather than listed. The current one runs 955, leaving 69. The clause +it needs, saying it paces you through work that already exists while this mode builds work as it paces you, runs about +twice that. Its description has to be tightened elsewhere to make room. + +The others have more headroom: 137 characters for `design-an-api`, 169 for `tdd`, 315 for `refactor`, 482 for +`iterative-plan-review`, and 544 for `plan-implementation` +([D-7](artifacts/implementation-decision-log.md#d-7-code-walkthroughs-description-is-tightened-to-fit-its-boundary-clause)). + +### Phase 6: The surfaces and the version bump + +Four manifests describe `han-core` and stop being accurate. So do the plugin front door, the plugin index (including its +now-false install description), the skills index, the workflow chains, the project map, six existing long-form skill +docs, and the changelog. + +The version bump reaches further than those four. Three plugins gain user-visible behavior, and each one's version +appears in more than one file, so every bump is a multi-file edit in that plugin plus its marketplace entry. Whether the +meta-plugin bumps alongside them is settled in +[D-8](artifacts/implementation-decision-log.md#d-8-three-plugins-bump-and-the-meta-plugin-follows-its-existing-rule). + +## How anyone knows it worked + +Nothing in this repository can execute a skill's instructions or check that a description routes a request correctly. +That is not a gap in this plan; it is the state of the tooling, and pretending otherwise would be worse than naming it. + +So verification splits three ways. + +**Seven checks a script can run**, all mechanical and all able to genuinely fail +([D-9](artifacts/implementation-decision-log.md#d-9-seven-mechanical-checks-and-no-prose-snapshot)): + +- The foundation plugin still declares no dependency on the two plugins whose skills it calls. +- Every changed description stays under its character budget. +- The rule file resolves from all five consumers. +- The vendored copies match the canonical file byte for byte. +- The four manifests mention the mode. +- The standard skill surfaces exist. +- Each colliding pair names the other in both directions. + +**Four procedures a person follows**, written down before the work starts rather than improvised at review: + +- Run the five routing phrasings verbatim and record which skill answers. +- Run each flagged skill directly and confirm it still finishes unpaused. +- Run the mode with a backing plugin absent. +- Walk one full session on skill-backed work and one on prose, through at least three stops each, checking each stop + against the primary flow and the edge-case table in the [specification](./feature-specification.md), which are where + the behaviors to walk against are written down. + +No separate checklist artifact exists, and none is needed while the specification carries them. + +**Two things nobody can check before someone uses it**, named rather than faked. The first: whether the sorting test +classifies real future requests the way a person would expect. The second: whether the reversibility call lands on the +pieces people find expensive. The specification rates open-ended work, which is where the sorting test falls through, at +Low confidence, and rates the per-kind units at Medium. The reversibility criterion carries no rating at all, because it +has no source and Phase 1 authors it. No test should claim to settle what the research does not. + +The routing procedure is the most consequential of the four. It is the only check on the collision the mode exists to +resolve, and every one of the seven descriptions can steal routing from the others. + +## Deferred (YAGNI) + +### A snapshot test pinning the current wording of each flagged skill's uninterrupted-run sentence + +- **Why deferred:** It would catch a deleted sentence, but the four files it would guard are among the highest-churn in + the repository, at twenty-two, fifteen, twelve, and eight commits in ninety days. It would fire on routine unrelated + edits far more often than on a real regression, and a check that raises false alarms gets deleted or ignored. Running + each skill directly, plus ordinary diff review confirming the flag is additive, covers the same concern. +- **Reopen when:** A flagged skill's default behavior regresses and reaches a release. +- **Source:** R1, `structural-analyst` and `junior-developer` (claim I11). + +### A script that detects whether a sibling plugin is installed + +- **Why deferred:** No precedent exists. Every availability check in the suite probes for an external command-line tool. + Nothing anywhere detects another Han plugin, and the install path a probe would look at is not referenced anywhere in + this repository. The manifest format cannot express the relationship either, since a declared dependency is always + required and auto-installed. The mode does not need one: it names the backing skill it intends to use in the plan, and + if the invocation does not resolve it reports that and offers the choice. Reacting is simpler than predicting and + satisfies the same commitment, which is never to substitute silently + ([D-10](artifacts/implementation-decision-log.md#d-10-no-detection-script-the-mode-reacts-rather-than-predicts)). +- **Reopen when:** The reactive path proves confusing in real use, or a platform surface for querying installed plugins + appears. +- **Source:** R1, `junior-developer` and `test-engineer`. + +### An automated check that the five routing phrasings land correctly + +- **Why deferred:** It needs a harness that can drive a live session, which this repository has never had and which no + other feature needs. The manual procedure satisfies the same evidence at a fraction of the cost. +- **Reopen when:** A routing regression ships more than once, making the infrastructure cheaper than the failures. +- **Source:** R1, `test-engineer`. + +### A validator for whether a description covers what, when, boundary, and breadth + +- **Why deferred:** Length and name-presence are mechanical and already covered. Judging whether prose satisfies four + qualitative components needs semantic judgment no tool here performs, and building one is speculative tooling scoped to + a single feature. +- **Reopen when:** A description-routing bug ships that ordinary review failed to catch twice. +- **Source:** R1, `test-engineer`. + +## Open Items + +- **OI-1:** Whether a pairing invocation trips the review-first exception `tdd` and `refactor` already carry. Both gate + on their plan when the request explicitly asks to review before implementation. An invocation from a mode whose whole + purpose is reviewing before each unit reads like that trigger. If it fires, the test list exists at plan time for + those two, and the specification's arrangement for surfacing it at the first stop is unnecessary for them. + - **Resolves when:** Phase 3 drafts the first flag insertion and the behavior is observed in a live session. + - **Blocks implementation:** No. It is settled by building the first of the three, and the answer changes one paragraph + in two skills rather than the design. + +## Sources and Plan Records + +- **Feature specification:** [feature-specification.md](./feature-specification.md) +- **Specification companions:** [decision log](artifacts/decision-log.md), + [team findings](artifacts/team-findings.md), [scope boundary](artifacts/scope-boundary.md). No technical-notes file + exists for this feature. +- **Specification decisions inherited:** D2 (every existing skill keeps its default behavior), D5 (a piece ends where + the kind of feedback changes), D8 (the feedback record is written down), D10 (five skills gain the flag), D12 (the + skill lives in `han-core` and its backing skills are optional), D13 (three kinds of work plus a fall-through), D21 + (the invalidated surfaces are part of this work), D22 (the stopping convention is a canonical `han-core` rule file), + D23 (the skill is named `pairing`). The specification closed with no open items to respect. +- **Decision rationale and rejected alternatives:** + [artifacts/implementation-decision-log.md](artifacts/implementation-decision-log.md) +- **Team composition and round-by-round history:** + [artifacts/implementation-iteration-history.md](artifacts/implementation-iteration-history.md) + +## Recommendation + +Ship as planned. One round settled every question that evidence could settle. The one it could not settle was escalated +and answered, and the single open item is non-blocking and resolves inside Phase 3. The one thing to watch is the +mechanic named above as unverified: whether a backing skill can end its turn mid-run and resume under its own +instructions. Phase 3 is deliberately sequenced so that is observed on the lowest-churn skill before the contract +reaches the two hardest ones. diff --git a/docs/plans/pairing-skill/feature-specification.md b/docs/plans/pairing-skill/feature-specification.md new file mode 100644 index 00000000..62abf2bf --- /dev/null +++ b/docs/plans/pairing-skill/feature-specification.md @@ -0,0 +1,409 @@ +# Feature Specification: pairing + +A collaborative working mode where Claude builds your work in reviewable pieces and hands each one back to you before +starting the next, so you stay in the lead rather than reviewing a finished result. + +## Outcome + +You get the work done, in pieces you reviewed, with your feedback shaping every piece after the one that +prompted it. + +This mode fills a gap in how Han skills work today. A skill either interviews you before it starts or runs to +completion and reports afterward, and neither lets you steer while the work is happening. Here, you see a piece, +react to it, and your reaction changes what gets built next. + +Your feedback is written down as it arrives, so a correction you gave at the second stop still applies at +the seventh ([D8](artifacts/decision-log.md#d8-your-feedback-goes-into-a-readable-written-record-rather-than-being-carried-in-memory)). + +The mode works on any kind of work, not only code +([D1](artifacts/decision-log.md#d1-the-mode-covers-any-kind-of-work-not-only-code)). Pairing on a design decision, +a written response, or a test-driven build are all the same loop with a different sense of what counts as a piece. + +## Actors and Triggers + +- **Actor** — one person doing their own work, who wants to stay in the lead while an assistant does the building. Han + targets solo and small-team engineers, and this mode assumes a single reviewer rather than a group. +- **Triggers** — two entry paths, and the mode supports both + ([D20](artifacts/decision-log.md#d20-both-entry-paths-are-supported-and-the-phrase-path-has-to-win-its-collisions)): + - **Naming the mode outright.** You invoke `/han-core:pairing` and say what you want to pair on. Nothing competes + for the request. + - **Saying it in your own words.** "Pair with me on tdd for this", "pair with me on refactoring", "pair with me on + designing an API for the export flow", "pair with me on writing a response to this question." Here, the mode + matches your request against every skill available in the session, and the first three of those sentences each name + another skill's strongest trigger word. The fourth names no competing skill, so nothing contests it. +- **Precondition** — none beyond a task you can describe. The mode works on its own for prose, decisions, and + open-ended work, and gains the skill-backed paths only when the skills behind them are installed + ([D12](artifacts/decision-log.md#d12-the-skill-lives-in-han-core-and-its-backing-skills-are-optional)). + When the work needs something the mode cannot supply on its own, the backing skill's own preconditions apply. + +The mode is opt-in and changes nothing about how any skill behaves when you do not invoke it +([D2](artifacts/decision-log.md#d2-every-existing-skill-keeps-its-current-default-behavior)). + +### Which Skill Answers When You Say It In Your Own Words + +The rule in every case: whichever skill answers, the person gets what they asked for +([D20](artifacts/decision-log.md#d20-both-entry-paths-are-supported-and-the-phrase-path-has-to-win-its-collisions)). +Because the second entry path competes, this mode's arrival changes what several existing skills have to say about +themselves. + +| You say something like | What should answer | What each side has to say about itself | +| ------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| "pair with me on tdd", "pair on refactoring" | This mode, which then runs the skill | This mode says it runs those skills collaboratively. Each of those skills says it otherwise runs to completion without pausing, and names this mode as the way to review as it goes. | +| "do TDD on this", "refactor this module" | The skill, running as it does today | Unchanged behavior, stated so the person who wanted an uninterrupted run keeps getting one. | +| "pair with me on designing an API for this" | This mode, which then runs `design-an-api` | Same delegating shape as the first row. That skill already runs discovery, an options document, a question round, and a validation round, and the mode gets those rather than re-deriving them. | +| "walk me through this code" | `code-walkthrough` | That skill paces you through work that already exists and builds nothing. This mode builds work while pacing you through it. Both have to say which side they are on. | +| "help me understand this module" | Not this mode | A request to understand something produces no artifact, so this mode declines it and names where it goes. | + +The delegating relationship in the first row has no precedent in the suite. Every existing boundary between two skills +is exclusive: one does the job and the other does not. This one is not exclusive, because this mode runs the very skill +it competes with. Saying so on only one side leaves a gap the request can fall through, so both sides say it. + +## How Confident Each Part of This Design Is + +The research behind this specification does not support every part of it equally, and the difference is large enough that +an implementation should know about it. + +- **High confidence.** Stopping where the kind of feedback changes rather than at a size threshold. Four independent + directions converge on it. +- **Medium confidence.** The specific unit for each kind of work. One decision per decision record is well corroborated. + The fidelity ladder for prose is a reconciliation the research performed itself, not a practice any single source + documents. +- **Low confidence.** Open-ended work. No source defines a unit for it, which is why the mode negotiates rather than + applying a rule ([D13](artifacts/decision-log.md#d13-three-kinds-of-work-plus-a-fall-through-not-four-kinds)). + +## Primary Flow + +1. **You say what you want to pair on, and the mode sorts the work.** It applies a fixed test, in this order, and stops + at the first match + ([D3](artifacts/decision-log.md#d3-the-mode-sorts-the-work-before-planning-anything-using-a-named-test), + [D13](artifacts/decision-log.md#d13-three-kinds-of-work-plus-a-fall-through-not-four-kinds)): + + 1. Does a Han skill carrying the collaborative flag cover this work? Then the work is **skill-backed**. + 2. Does the work produce a choice among options that commits you to something? Then it is **decision work**. + 3. Does the work produce prose someone will read? Then it is **prose work**. + 4. Otherwise it is **open-ended**, and the plan in step 2 supplies the boundaries with no rule behind them. + + The order is the tie-break. A request that fits more than one kind sorts as the earliest match, so drafting a decision + record sorts as decision work rather than prose work. + +2. **The mode proposes where it will stop, and why.** Before any work starts, you get a short plan. It names which kind + the work sorted into, the pieces it intends to build, the reason for each boundary, and which of those pieces it + expects to contain a choice that is expensive to walk back + ([D4](artifacts/decision-log.md#d4-the-mode-proposes-the-plan-of-stopping-points-rather-than-asking-you-to-supply-one), + [D14](artifacts/decision-log.md#d14-the-reversibility-call-is-announced-in-the-plan-and-the-ask-precedes-the-build)). + You accept it, change it, or replace it. Either side can renegotiate later as the work reveals its actual shape. + + Naming the sort matters because the sort determines everything downstream. It is the one part of the plan you cannot + correct if you cannot see it. + + For skill-backed work the plan names the backing skill, the unit that skill stops at, and the reason. The backing + skill's own list of units does not exist yet at this point. Instead, the mode surfaces it as the plan of pieces at + the first stop, where you can still redirect it + ([D15](artifacts/decision-log.md#d15-for-skill-backed-work-the-pre-work-plan-names-the-unit-and-the-first-stop-carries-the-list)). + +3. **For a piece the plan marked expensive to walk back, the mode asks for your read before it builds.** The ask names + the dimension the choice turns on and stops there, rather than posing a blank question or offering candidate answers + that would anchor your guess. You say what you expect, or you decline. Declining is a first-class answer and advances + the stop exactly as a considered one does + ([D7](artifacts/decision-log.md#d7-the-mode-asks-for-your-read-first-only-where-a-mistake-is-expensive-to-undo)). + + The ask comes before the build, not after. The studies behind it work because you commit before the answer exists. An + ask that arrives once the work is already on disk buys the cost and none of the benefit. + +4. **The mode builds one piece.** What counts as one piece depends on the kind of work + ([D5](artifacts/decision-log.md#d5-a-piece-ends-where-the-kind-of-feedback-changes-not-at-a-size-threshold)): + + | Kind of work | One piece is | + | ------------ | -------------------------------------------------------------------------------- | + | Skill-backed | Whatever that skill already treats as one unit | + | Decision | One decision, with its context, the options weighed, and what it commits you to | + | Prose | One rung of a fidelity ladder: the shape, then a rough draft, then the language | + | Open-ended | Whatever the plan from step 2 named | + +5. **The mode hands the piece back for checking.** You get which piece this is against the plan and what remains, the + specific things you can verify, and what changed. The reasoning behind the choices does not lead, and the stop says in + one line that it is available for the asking + ([D6](artifacts/decision-log.md#d6-a-stop-hands-you-checkable-claims-rather-than-a-case-for-the-work), + [D16](artifacts/decision-log.md#d16-every-stop-names-your-position-in-the-plan-and-the-plan-stays-available)). + + When you gave a read in step 3, the reveal presents what was done in the same form as any other stop. It does not + restate your read, score it, or defend a divergence from it. + +6. **The mode stops.** The turn ends and nothing further is built. This is a directive the mode follows, not a guarantee + anything enforces ([D17](artifacts/decision-log.md#d17-the-stop-is-a-directive-the-mode-follows-not-a-guarantee)). + +7. **You respond, and the mode writes your response down.** Every piece of feedback goes into a running record before it + is acted on. You can read that record whenever you ask, and when the mode applies a recorded entry to a later piece it + names which entry it applied + ([D8](artifacts/decision-log.md#d8-your-feedback-goes-into-a-readable-written-record-rather-than-being-carried-in-memory)). + +8. **The mode acts on your feedback.** The two kinds take different routes + ([D9](artifacts/decision-log.md#d9-feedback-condemning-the-piece-in-hand-is-fixed-in-place-and-re-shown)): + - **About the piece in hand.** The mode fixes it within that same piece and shows it again, naming the correction it + applied and what it touched before restating the piece. That re-show is a stop like any other, so the loop returns + to step 6 and waits. It does not return to step 3, because step 3 asks for your read before a build, and this piece + is already built. + - **About what comes next.** It shapes the next piece, and the loop returns to step 3 for that piece. + + Accepting a re-shown piece with nothing further to say also moves to the next piece, at step 3. + +9. **The loop ends when the plan is finished or you end it.** Ending is your call by design; nothing computes a stopping + point for you ([D18](artifacts/decision-log.md#d18-ending-the-loop-is-the-persons-call-and-nothing-computes-it)). The + mode reports what was built, what your feedback changed, anything the plan named but did not reach, and the state of + any work a backing skill left unfinished. + +## Alternate Flows and States + +### The backing skill owns the piece boundary + +- **Entry condition:** The work sorted as skill-backed, meaning a Han skill covers it and carries the collaborative flag. +- **Sequence:** The mode hands the work to that skill. The skill does its own job unchanged, and stops at the point it + already treats as the end of a unit rather than looping onward on its own + ([D10](artifacts/decision-log.md#d10-five-skills-gain-an-opt-in-collaborative-flag)). Control returns to + the pairing loop at step 5 of the primary flow. +- **Exit:** The backing skill's own work is complete, or you end the loop. + +Five skills gain this flag, and none of them gains a new boundary. `tdd` already ends each cycle by crossing one +behavior off its list. `refactor` already ends each step by crossing off one named refactoring. `design-an-api` already +runs in distinct rounds and already surfaces its open items one at a time. `iterative-plan-review` already runs review +rounds with a stop rule computed from finding counts, and `plan-implementation` already runs resolution rounds. In every +case the flag changes only what happens when that existing boundary is reached: control returns to you instead of the +skill continuing on its own +([D10](artifacts/decision-log.md#d10-five-skills-gain-an-opt-in-collaborative-flag)). + +The last two are the ones most worth naming, because neither stops for you today. `iterative-plan-review` surfaces a +disagreement between two reviewers and then keeps going without waiting for your answer. `plan-implementation` holds its +only question until every round is already finished. + +### You want to move faster without giving up review + +- **Entry condition:** You ask for more than one piece at a time, in whatever words: "show me the next three", "do the + rest of the setup and stop before the interesting part." +- **Sequence:** The mode honors the request as asked, builds the pieces you named, and presents them together + ([D19](artifacts/decision-log.md#d19-you-can-ask-for-several-pieces-at-once-and-the-loop-returns-to-its-normal-pace-after)). +- **Exit:** The loop returns to its normal pace at the following stop, without you having to ask for that. + +This is the middle gear. Without it your only options are full ceremony on every piece or turning review off for the +remainder, and the second is what the mode exists to prevent. + +### You asked to pair on implementing, without naming a discipline + +- **Entry condition:** Your request says to build something but does not say whether to drive it from tests, restructure + what is there, or sketch a shape first. +- **Sequence:** The mode does not guess. Step 2's proposed plan names which approach it intends and why, and that + proposal is the thing you accept or redirect + ([D4](artifacts/decision-log.md#d4-the-mode-proposes-the-plan-of-stopping-points-rather-than-asking-you-to-supply-one), + [D11](artifacts/decision-log.md#d11-the-front-door-never-picks-the-discipline-for-you)). A single request may span more + than one approach, such as sketching a shape and then building it test-first. When the plan sequences more than one + backing skill, it orders them so each skill's own preconditions hold when its turn arrives. +- **Exit:** You accept or replace the proposed approach, and the loop proceeds from step 3. + +### Your feedback reaches outside the piece in hand + +- **Entry condition:** You ask for a change that would alter work outside the most recently built piece. +- **Sequence:** The mode names its reading before acting on it: it says that your feedback looks like it reaches past this + piece, and what it would change about the plan. You then have three ways out + ([D9](artifacts/decision-log.md#d9-feedback-condemning-the-piece-in-hand-is-fixed-in-place-and-re-shown)). +- **Exit:** You accept a revised plan, change it, or decline the reopening entirely. If you decline, your feedback is + recorded as scoped to later work, and the plan you already agreed to continues. + +The third exit exists because thinking out loud is the working style this mode is built for, and an offhand remark should +not silently replace a plan you agreed to. + +### You end the loop early + +- **Entry condition:** You say to stop, or to finish the rest without stopping. +- **Sequence:** The mode acknowledges the change in the same turn you ask for it, naming what remains that will now go + unreviewed. When you asked it to finish without stopping, it continues from the current plan and reports at the end + rather than at each piece. +- **Exit:** The loop is over. The mode reports the state of any work a backing skill left mid-cycle, and it names where + the feedback record was written, in terms you can act on + ([D18](artifacts/decision-log.md#d18-ending-the-loop-is-the-persons-call-and-nothing-computes-it)). + A record that survives a session but that you cannot find is not a record. + +## Edge Cases and Failure Modes + +| Condition | Required Behavior | +| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Your request is too vague to sort | The mode asks once, naming what was ambiguous and offering candidate readings of your request rather than posing a blank question. If the answer is still not enough, it proposes a plan against the most likely reading and says so. | +| The work turns out to have no natural pieces | The proposed plan says so and names a boundary it chose for a stated reason, so you have something concrete to redirect rather than a blank question ([D4](artifacts/decision-log.md#d4-the-mode-proposes-the-plan-of-stopping-points-rather-than-asking-you-to-supply-one)). | +| You respond to a stop with a question rather than a direction | The mode answers the question and stops again at the same place. A question holds your place; it never advances the work. | +| You approve several pieces in a row without comment | The loop continues unchanged, and the mode adds no pressure to comment. Approval is a valid response, and a run of approvals is not read as a lapse in care. The mode does not volunteer anything in response to it ([D19](artifacts/decision-log.md#d19-you-can-ask-for-several-pieces-at-once-and-the-loop-returns-to-its-normal-pace-after)). | +| A backing skill hits one of its own stop conditions | That skill's stop wins and is reported to you as-is. The pairing loop does not override or soften it. | +| The proposed plan turns out to be wrong once work starts | The mode says so at the next stop, names what it learned, and proposes a revised plan rather than silently working to a plan it no longer believes ([D4](artifacts/decision-log.md#d4-the-mode-proposes-the-plan-of-stopping-points-rather-than-asking-you-to-supply-one)). | +| The mode builds past a stop | The next thing it says names the overrun, states which pieces were built without review, and offers to walk back through them before continuing. It does not present the extra work as though you had approved it ([D17](artifacts/decision-log.md#d17-the-stop-is-a-directive-the-mode-follows-not-a-guarantee)). | +| The session is compacted or interrupted mid-loop | The running record of your feedback survives, because it is written down rather than remembered. On resuming, the mode restates the piece in hand and its position in the plan before continuing, so your continuity is restored alongside its own ([D8](artifacts/decision-log.md#d8-your-feedback-goes-into-a-readable-written-record-rather-than-being-carried-in-memory), [D16](artifacts/decision-log.md#d16-every-stop-names-your-position-in-the-plan-and-the-plan-stays-available)). | +| You ask to understand something rather than produce something | The mode says this is not its work and names where it goes: paced explanation of code that already exists, a written overview, or an open research question. It does not sort the request as open-ended and propose a plan to build things. | +| The work maps to a backing skill that is not installed | The mode names the missing skill and offers you the choice between the open-ended path and installing it. It never substitutes silently, because hand-rolling a refactoring skips the passing-test gate that skill exists to enforce ([D12](artifacts/decision-log.md#d12-the-skill-lives-in-han-core-and-its-backing-skills-are-optional)). | + +## User Interactions + +- **Affordances.** One invocation, in whatever words you prefer, naming what to pair on. At each stop, an ordinary + conversational turn: you say what you think, ask a question, redirect, approve, or ask for several pieces at once + ([D19](artifacts/decision-log.md#d19-you-can-ask-for-several-pieces-at-once-and-the-loop-returns-to-its-normal-pace-after)). + You can ask to read the feedback record + ([D8](artifacts/decision-log.md#d8-your-feedback-goes-into-a-readable-written-record-rather-than-being-carried-in-memory)) + or the current plan + ([D16](artifacts/decision-log.md#d16-every-stop-names-your-position-in-the-plan-and-the-plan-stays-available)) + at any point. +- **Feedback.** Each stop names which piece this is against the plan and what remains, what was built, what you can + check, and what changed + ([D6](artifacts/decision-log.md#d6-a-stop-hands-you-checkable-claims-rather-than-a-case-for-the-work)). At a stop over + a hard-to-reverse choice, the ask comes first, and declining it advances the stop unchanged + ([D7](artifacts/decision-log.md#d7-the-mode-asks-for-your-read-first-only-where-a-mistake-is-expensive-to-undo)). +- **Error states.** A request too vague to act on produces one question with candidate readings rather than a guess. A + backing skill's own blocking condition is reported in that skill's own words. An overrun past a stop is named rather + than absorbed. + +The pacing is the deliverable. The mode ends its turn at each stop rather than continuing, and every stop says where you +are in the plan. Asking for more than one piece at a time is part of the pacing, not an escape from it. + +## Coordinations + +| Coordinating System | Direction | Interaction | Ordering / Consistency Requirement | +| --------------------------- | --------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `tdd` | outbound | Runs the test-driven loop; returns control at the end of each behavior rather than continuing | The collaborative behavior applies only to an invocation made through `pairing`. An ordinary `tdd` invocation runs exactly as it does today. | +| `refactor` | outbound | Runs the refactoring sequence; returns control at the end of each named refactoring | Same condition. An ordinary `refactor` invocation runs exactly as it does today. | +| `design-an-api` | outbound | Runs its design rounds; returns control at the end of each round | Same condition. An ordinary `design-an-api` invocation runs exactly as it does today. | +| `iterative-plan-review` | outbound | Runs its review rounds; returns control at the end of each round | Same condition. An ordinary invocation runs its rounds to the computed stop rule exactly as it does today. | +| `plan-implementation` | outbound | Runs its resolution rounds; returns control at the end of each round | Same condition. An ordinary invocation holds its single question until after every round, exactly as it does today. | +| The running feedback record | both | Written after each stop, read before planning each piece, readable by you on request | A stop's feedback is written before the next piece is planned, so no piece is built against feedback not yet recorded. | +| `code-walkthrough` | neither | No handoff. The two share their whole pacing vocabulary, so each has to say which side of produced-versus-existing work it is on | Nothing runs. This is a routing relationship only, and it exists because the shared words would otherwise send a request to the wrong skill. | +| Han's configuration file | inbound | Supplies the output location the feedback record is written under | Read once at the start of the loop, so the record's location does not move mid-session. | + +The five skill rows are the opt-in flag and nothing more +([D10](artifacts/decision-log.md#d10-five-skills-gain-an-opt-in-collaborative-flag)): +the flag applies to an invocation made through this mode, and every ordinary invocation of those skills is untouched +([D2](artifacts/decision-log.md#d2-every-existing-skill-keeps-its-current-default-behavior)). The feedback-record row is +what makes a correction given early still apply late +([D8](artifacts/decision-log.md#d8-your-feedback-goes-into-a-readable-written-record-rather-than-being-carried-in-memory)). +The `code-walkthrough` row runs nothing, and exists because the shared vocabulary would otherwise send a request to the +wrong skill +([D20](artifacts/decision-log.md#d20-both-entry-paths-are-supported-and-the-phrase-path-has-to-win-its-collisions)). + +## What Else Has To Change When This Ships + +Shipping this mode is not only building the mode. Four groups of material change the moment it lands, and all four are +part of the work rather than follow-up +([D21](artifacts/decision-log.md#d21-the-surfaces-that-stop-being-accurate-are-part-of-this-work)). + +1. **`han-core` stops being what it says it is.** Its front door, the plugin index entry, and its manifests all describe + it as the specialist agents, project discovery, and the shared rule files. It now also carries a working mode a person + invokes directly, and every one of those descriptions needs to say so. The plugin index goes further and offers an + install described as "only the shared agents and project discovery, with no other skills," which becomes untrue + ([D12](artifacts/decision-log.md#d12-the-skill-lives-in-han-core-and-its-backing-skills-are-optional)). +2. **Five skills gain user-visible behavior.** `tdd`, `refactor`, `design-an-api`, `iterative-plan-review`, and + `plan-implementation` each get a collaborative mode, so each one's own operator manual and its own routing text change + alongside this mode's ([D10](artifacts/decision-log.md#d10-five-skills-gain-an-opt-in-collaborative-flag)). Three of + the five live in `han-coding` and two in `han-planning`, so both plugins change, not only the one this mode ships in. +3. **A new shared rule file.** The stopping convention this mode follows is owned by `han-core` as a canonical rule file, + beside the YAGNI, evidence, and configuration rules it already owns, because five skills consume the handoff contract + rather than one ([D22](artifacts/decision-log.md#d22-the-stopping-convention-is-a-canonical-rule-file-owned-by-han-core)). +4. **The usual surfaces a new skill needs.** The skill itself, its long-form documentation, a line on its plugin's front + door, an entry in the skills index, the project map, the workflow chains, and the version history. + +Two things this mode does not need, stated so nobody adds them: it takes no size argument and dispatches no team, so the +sizing documentation does not apply to it. + +## Out of Scope + +- **Choosing the discipline for you.** The mode proposes and you decide. It never silently picks test-driven development + over restructuring, or either over sketching a shape first + ([D11](artifacts/decision-log.md#d11-the-front-door-never-picks-the-discipline-for-you)). +- **Changing how any skill behaves by default.** Every flag is opt-in + ([D2](artifacts/decision-log.md#d2-every-existing-skill-keeps-its-current-default-behavior)). This is the operator's + stated exclusion, quoted in the scope boundary record. +- **Group review.** The mode assumes one reviewer. Nothing here coordinates several people reviewing the same piece. +- **Automatic invocation.** The mode runs when you ask for it. Nothing triggers it on your behalf. +- **A stop rule computed from counts.** The Han skills that run review rounds, `iterative-plan-review` and + `plan-implementation`, decide when to stop by counting and grading findings. Work being built produces no such + countable signal, so this mode has nothing to compute over, and ending the loop stays your call ([D18](artifacts/decision-log.md#d18-ending-the-loop-is-the-persons-call-and-nothing-computes-it)). + +## Cut for Scope + +This is work the work item excludes, not work deferred for lack of evidence. Nothing here carries a reopening trigger, +because the recorded boundary already settled it. + +### Making the collaborative mode the default for a whole session, rather than something you invoke per task + +- **Why cut:** The scope boundary records the operator's acceptance of one skill and no output style. That excludes + building an output style, a session-start hook, or a post-edit hook as part of this work. The record also notes that + widening the mode beyond code reopens the input behind that choice, and that the decision stands until the operator + revisits it. + +## Deferred (YAGNI) + +This is work no evidence supports yet, not work the work item excludes. Every entry carries the trigger that would +justify revisiting it. + +### Carrying the feedback record across separate sessions + +- **Why deferred:** No stated need. The evidence supporting a written record is about surviving within a working session. + There, the measured comparison was six percent of critical steps missed with a written checklist against twenty-three + percent from memory. Nothing establishes that feedback from a previous week should shape today's pieces, and doing so + risks applying a correction whose reason has expired. +- **Reopen when:** You describe re-giving the same feedback across sessions, or a session's record is lost and costs you + a repeat of work already reviewed. +- **Source:** Conversation context during specification. + +### Detecting when your new feedback contradicts feedback you gave earlier + +- **Why deferred:** Evidence test failed. No user-described need, incident, or measurement supports it. It is also the + most expensive behavior anyone proposed for this mode: a comparison of every new remark against the whole record, at + every stop. Its failure modes cut both ways. A false positive costs you a turn defending feedback you never + contradicted, and a false negative protects nothing. A strictly simpler behavior satisfies the same concern and is in + the spec instead. When the mode applies a recorded entry, it names which one, so you catch the conflict yourself with + the entry in front of you. +- **Reopen when:** You give contradictory feedback in a run and the mode applies the wrong one. +- **Source:** Review findings F5 and F6 in [artifacts/team-findings.md](artifacts/team-findings.md). + +### Offering the faster gear when you approve several pieces without comment + +- **Why deferred:** Evidence test failed, and the premise was already removed. Synthesis struck the claim that a run of + approvals signals a wish for a different pace, because no evidence in either research report speaks to what approvals + mean. The offer resting on that claim survived the claim's removal. Nothing else supports it: no stated need, no + incident, no measurement. It also costs a conditional and a once-per-session counter the mode would otherwise not need. + You can ask for several pieces at any time, which is the behavior the evidence does support. +- **Reopen when:** You ask for several pieces at once more than once in a single run, or say you wished the faster pace + had been offered. +- **Source:** Implementation review finding I3 in + [artifacts/implementation-iteration-history.md](artifacts/implementation-iteration-history.md). + +### Giving the collaborative flag to any skill beyond the five that have it + +- **Why deferred:** No candidate has evidence behind it. The widened test asks whether a skill produces its result across + a sequence of units, where each unit stands on its own and later units build on earlier ones. Running it across every + skill in every plugin the operator did not rule out found exactly the five that carry the flag. The rest fail in four + groups: the inline guidance skills produce no result of their own, the publishing and export skills already stop before + writing to a shared system, the one-document skills hand you a single synthesized artifact rather than a sequence, and + `plan-a-feature` and `code-walkthrough` already stop for you so the flag would be a no-op. +- **Reopen when:** A new skill ships that produces its result across a sequence of units where each unit stands on its + own, or you find yourself wanting to pair on a skill that runs to completion today. +- **Source:** Operator survey during specification, widened by review finding F10 and re-run across the suite at + escalations E7 and E8, both in [artifacts/team-findings.md](artifacts/team-findings.md). + +## Open Items + +None. All three items this specification opened were settled before it closed, and each is recorded as a decision with +its rejected alternatives: + +- Which convention owns the stops, settled as a canonical rule file owned by `han-core` + ([D22](artifacts/decision-log.md#d22-the-stopping-convention-is-a-canonical-rule-file-owned-by-han-core)). +- Which further skills qualify for the flag, settled by running the widened test across every skill in the plugins the + operator did not rule out ([D10](artifacts/decision-log.md#d10-five-skills-gain-an-opt-in-collaborative-flag)). +- Whether the skill keeps its original name, settled by renaming it + ([D23](artifacts/decision-log.md#d23-the-skill-is-named-pairing-and-the-phrase-people-type-lives-in-its-description)). + +## Summary + +- **Outcome delivered:** Work gets built in pieces you reviewed, with your feedback shaping every piece after it. +- **Primary actors:** One person doing their own work, pairing with Claude on any kind of task. +- **Decisions settled by evidence:** 14 — see [artifacts/decision-log.md](artifacts/decision-log.md) +- **Decisions settled by user input:** 9 — see [artifacts/decision-log.md](artifacts/decision-log.md) +- **Sub-agents consulted:** `junior-developer`, `user-experience-designer`, `information-architect` — see + [artifacts/team-findings.md](artifacts/team-findings.md) +- **Key adjustments from review:** The guard against nodding through now asks before the build rather than after, which is + what its evidence requires. The mode now tells you where you are in the plan, lets you read the feedback record, and + lets you ask for several pieces at once. The skill stays in `han-core` with its backing skills treated as optional, the + flag reaches five skills rather than two, and the skill is named `pairing` rather than for the phrase people type. +- **Remaining open items:** 0 diff --git a/docs/research/collaborative-output-style.md b/docs/research/collaborative-output-style.md new file mode 100644 index 00000000..55f5e0df --- /dev/null +++ b/docs/research/collaborative-output-style.md @@ -0,0 +1,650 @@ +# Research: A Collaborative "Human in the Lead" Output Style + +Can a custom output style carry a collaborative working mode? In it, Claude builds one chunk of an implementation, +walks you through it, stops for your review, and folds your feedback into the next chunk. Evidence mode: strict. + +## Summary + +Build one skill and no output style. The skill carries the whole loop: work in chunks, explain each one as you finish +it, stop and hand control back, and treat what comes back as direction for the next chunk. You start it when you want +this working mode, and work you do not start through it behaves normally. + +This answer changed partway through. The research first recommended a small output style plus a companion skill, +because a style is the only thing that reaches ordinary requests where you never name a skill. Then you decided an +opt-in workflow was fine, and that you did not want your existing skills forced into this mode. That removed the only +job the output style was doing. + +Dropping the style is a real simplification, not a consolation. Only one output style runs at a time, so a collaboration +style would have displaced the readability standard and forced a second decision about where that standard lives. It +also would have inherited an unresolved question: Anthropic's documentation says output styles set role, tone, and +format, while Anthropic's own code repository shows the two styles closest to what you want were pulled out of that +mechanism and rebuilt as startup hooks, meaning scripts that run when a session starts. Those two sources contradict +each other and I could not settle which is current. With no style in the design, that question no longer matters. + +The strongest reason to trust this shape is that you already run it. Your walkthrough skill carries the same +stop-after-every-step loop from prose in one file, with no output style involved. + +Three things still need care inside the skill. Feedback has to be written to a file rather than left in the +conversation, because a correction given early gets buried in the middle of a long session where the model attends to it +least. Chunks need to stay small enough to genuinely review. And no study anywhere measures how often stopping is worth +the interruption, so the pacing rests on converging practitioner guidance rather than measurement. + +- **Confidence:** High for the mechanism, Medium for the pacing details + +## Research Results + +### What an output style is and what it is documented to do + +An output style is a markdown file. Claude Code appends its text to the end of the system prompt at session start +(A1, A8). Anthropic's blog says output styles "carry the highest instruction-following weight of any method" for +changing behavior globally, and warns they "should be used judiciously" (A8). That is a point in favor of using one +here. + +Three limits matter immediately. First, a custom style drops Claude Code's built-in software-engineering instructions +(how to scope changes, comment conventions, security handling, verification habits) unless the file sets a flag to keep +them (A1, A8). Han's existing readability style already sets that flag (A31). Second, output styles reach the main +conversation only, because a subagent runs its own system prompt (A1). + +Third, only one output style runs at a time. The documentation does not state this as a standalone rule. It follows +from two things the documentation does state. The setting that selects a style holds a single text value. And when +several plugins each try to force their own style, "Claude Code uses the first one loaded" (A1) [inferred from the +documented settings schema, not stated outright]. Treat it as very likely true and worth confirming before you commit +to a design that depends on it. + +The documentation scopes output styles to "role, tone, and output format," and its own comparison table separates them +from skills, which it describes as the mechanism for a reusable workflow (A1). Turn-taking and work sequencing sit on +the skill side of that line. + +### Anthropic pulled the two closest styles off this mechanism + +The strongest evidence against building the whole loop into an output style is what Anthropic did with its own similar +styles. The Explanatory style's plugin README states it "recreates the deprecated Explanatory output style as a +SessionStart hook" (A9). The Learning style's README states it "combines the unshipped 'Learning' output style with the +deprecated 'Explanatory' output style," also as a startup hook (A10). A startup hook is a script that fires when a +session begins and appends text to the default system prompt. + +Learning is close kin to what you described: it pauses at decision points and asks the person to contribute code (A10). +That behavior did not ship as an output style. + +This directly conflicts with the current documentation page, which still lists Explanatory and Learning as built-in +output styles (A1). Two Anthropic-controlled sources disagree, and the research did not find a changelog entry or +maintainer statement that resolves it. I record the conflict rather than picking a side. + +### What Han already learned about output-style limits + +Prior research in this repository established four hard limits, and they constrain the design directly (A38): + +- An output style is fixed text added to the system prompt at session start. Nothing documents a way to include other + files or run commands from it. +- The plugin path variable does not resolve inside an output-style file. +- Output styles do not reach subagents. +- Copying a whole standard into one block contradicts how that standard is meant to be applied, in stages. + +That last point rests on a measured effect: instruction compliance falls from roughly 85 to 90 percent at one +instruction to between 15 and 44 percent when many are stacked (A39). The readability style is already 98 lines (A31). +A style that also carried a full collaborative procedure would roughly double that. + +One caution about that measurement. It covers compliance with content constraints such as tone, length, and format. It +does not measure whether an agent correctly executes a workflow gate, like stopping mid-edit to hand control back. +Applying it to a stopping instruction is an extrapolation, and I flag it as one rather than presenting it as a direct +finding. + +### Han's code-walkthrough skill already implements the pacing you want + +The `code-walkthrough` skill runs exactly the turn-taking loop you described, through prose instruction alone (A33). It +directs one step per turn, then a stop, with the reasoning stated inline: "the pacing _is_ the deliverable." It also +handles the case where you ask a question instead of moving on, holding position rather than advancing. + +This is local evidence that prose instruction can carry turn-taking in practice, which cuts against the pure +documentation-scope argument. + +What `code-walkthrough` does not do is run while code is being written. It is read-only, retrospective, and walks +through code that already exists (A33). + +### Nothing in Han stops mid-implementation for collaborative review + +The `tdd` skill runs autonomously after the initial request and states plainly that it "does not stop for confirmation" +(A34). It has two stopping points, neither of them collaborative. One is a gate before implementation starts, and only +when you explicitly ask to review the plan first. The other is a hard dependency stop when it cannot find a command to +run tests with (A34). Once the build loop starts, it "runs to completion without further human input" (A34). + +The `code-overview` skill is read-only and writes a file without an interactive loop (A35). + +The repository does have a rule for stopping, but it does not reach code. The operator-escalation rule allows exactly +one stop per run, and only when a missing input is something only you can supply (A36). It names its consumers +explicitly, and all four are planning skills. No coding skill is on that list. The rule was never written to govern +implementation work, so a collaborative loop would need its own stopping convention rather than an exception to this +one. + +### Nothing can force a stop at a chunk boundary + +Hooks are the one mechanism documented to apply "regardless of what Claude decides" (A5, A8). A pre-tool hook can block +a tool call outright. A post-tool hook fires after an edit but cannot undo or block it, because the tool already ran +(A2). + +None of the hook events corresponds to "one logical chunk of implementation is finished." That is a judgment about +meaning, not a mechanical event. Plan mode is the only enforced stop in the product, and it gates the boundary between +planning and executing, once, not repeated review during a build (A7). Checkpointing is undo, not a review gate (A6). + +So every option here ultimately relies on Claude following an instruction to stop. The options differ in how much +weight that instruction carries and how well it survives a long session, not in whether it can be enforced. + +### How big a chunk should be + +Practitioner and vendor guidance converge on task-shaped chunks rather than line counts (A12, A13, A14, A15). Anthropic's +own best-practices page says to skip the checkpoint for a change describable in one sentence and use it for anything +spanning multiple files or unfamiliar code (A12). + +There is one empirical anchor on the review side. The Cisco code-review study found reviewers catch 70 to 90 percent of +defects when examining 200 to 400 lines over 60 to 90 minutes, with effectiveness dropping sharply past roughly 400 +lines (A18). That study came to me through a blog's paraphrase rather than the original document [single-source]. + +Thoughtworks proposes a two-tier design worth borrowing: a frequent mechanical gate after each small test cycle, and a +coarser human gate at milestone boundaries where you review design and configuration choices (A13) [single-source]. + +### Feedback does not carry forward reliably on conversation history alone + +This is the best-evidenced finding in the whole report, and it argues for writing feedback down. A peer-reviewed study +found model accuracy drops by more than 30 percent when the relevant information sits in the middle of a long context +rather than at either end. The finding was replicated across six model families (A23). + +Anthropic's own documentation says the same thing in practical terms. After two failed corrections on the same point, +the context is "polluted with failed approaches." A fresh session with a better opening prompt beats continuing to +correct in place (A12). The same docs distinguish conversation memory from a written file that reloads fresh each +session (A5). + +One preprint claims a single explicit mid-session correction achieved complete repair in 30 of 30 sessions (A26). That +source is a single-author, unreviewed paper with promotional framing and no independent replication, so I carry it as a +directional hint only [single-source]. + +### The loop itself has a documented failure mode: you stop reading + +Two recent studies measure how humans review AI-written code, and they disagree on direction. One found that among 400 +repeat reviewers over 207 days, approval rates rose from 30.1 to 36.8 percent while inline comment volume fell 22 +percent. The authors read that as habituation rather than earned trust (A16). A separate study using different data +found the opposite trend: the share of merged agent pull requests receiving no human review fell from over half in +mid-2025 to about 13 percent by February 2026 (A17). + +Both authors flag that the underlying data is unstable under different but defensible analysis choices. There is no +settled answer on whether scrutiny is rising or falling. + +What both agree on is the mechanism. Review load pushes toward either shallower reading or reviewer burnout, and +AI-written code's surface polish lowers your guard because it looks clean and idiomatic (A16, A17). + +Separately, frequent approval prompts train people to stop reading and approve reflexively (A25). Vendor telemetry +claims users approve about 93 percent of permission prompts, with players in a threat-detection game missing one +injected threat in three (A30) [single-source, vendor telemetry]. + +That risk lands squarely on this design. A loop that narrates every chunk and asks for approval could produce the same +reflexive approval it was built to prevent. + +### Narration might help you catch problems, or might not + +The one data point on whether explaining a change improves the reviewer's catch rate comes from the Cisco study. +Author-annotated code showed lower defect density there, never exceeding 30 defects per thousand lines (A18). The +original researchers were themselves unsure whether annotation caught defects early or made reviewers less critical by +walking them through a narrative (A18) [single-source]. + +Two collaboration models support narration on principle. Pair programming's driver and navigator split works because +articulating reasoning out loud "pushes us to reflect if we really have the right understanding" (A19). An empirical +study found paired code cost about 15 percent more time while passing a significantly higher share of acceptance tests +(A22). Cognitive apprenticeship names articulation and reflection as two of six methods for making expert thinking +visible to a learner (A21). + +What does not transfer: strong-style pairing exists to coach a junior human who retains the skill (A20), and cognitive +apprenticeship's other methods assume the expert can fade support as the learner improves (A21). Neither has an +equivalent when the party doing the explaining is an AI with no memory of what you already learned. + +### Nobody has measured whether stopping is worth the interruption + +I searched for a study comparing checkpoint frequencies in human-AI coding and found none. That is a negative result +worth stating plainly. + +The nearest evidence is general interruption research: a field study of knowledge workers measured an average +23-minute-15-second lag to return to a task at the same focus level after an interruption (A24). That is not a study of +AI pairing, so applying it here is inference, not measurement. + +## Options to Consider + +### O1: One combined output style carrying readability and the collaborative loop + +- **What it is:** A single new style file holding the readability standard plus the full chunk-explain-stop-incorporate + procedure, replacing the current readability style. +- **Trade-offs:** Simplest to install and always on with nothing to invoke. But it stacks two full standards in one + block, which is the pattern measured to drop compliance from 85 to 90 percent down to 15 to 44 percent (A39). It also + contradicts the staged-application design the readability rule states for itself (A38), and it cannot read your + configuration, pull in the writing-voice profile, or dispatch the readability editor (A38). +- **Rests on:** (A1, A8, A31, A38, A39) +- **Evidence status:** corroborated + +### O2: A thin collaboration output style plus a companion skill invoked automatically + +- **What it is:** A short style file carries only the always-on stance: chunk the work, explain each chunk as you + finish it, stop, and absorb feedback. It is paired with a skill that owns the detailed procedure and does the runtime + work a style cannot. The implementation skills invoke that companion skill as an automatic sub-step, the way 27 + skills already invoke `readability-guidance` (A42). +- **Trade-offs:** Mirrors the split this repository already uses for readability, and keeps the instruction count low + enough to survive (A31, A38, A39). The automatic invocation is load-bearing rather than optional: `readability-guidance` + works because callers invoke it, not because a person remembers to (A42). Without that wiring this option degrades + into a thin stance plus an opt-in command, which is what the request rules out. The cost is two artifacts to build, + plus an edit to every implementation skill that should carry the loop. +- **Rests on:** (A1, A3, A8, A31, A33, A38, A39, A42) +- **Evidence status:** corroborated + +### O3: A skill only, with no new output style + +- **What it is:** Encode the whole loop as a skill you invoke when you want this working mode. +- **Trade-offs:** Skills are the mechanism the documentation names for a reusable workflow (A1, A3), and this is what + `code-walkthrough` already does successfully for pacing (A33). One artifact, one file to read, no output style to + swap and therefore no readability trade to make. Against it: the loop reaches only work you launch through the skill, + so an ordinary request gets none of it. The documentation also warns a loaded skill's influence can quietly fade over + a long session (A3), which the loop's own re-read step partly offsets by pulling the running feedback file back into + context each cycle. +- **Rests on:** (A1, A3, A33) +- **Evidence status:** corroborated + +### O4: An output style plus a session-start hook + +- **What it is:** Follow the pattern Anthropic used for Explanatory and Learning: implement the behavior as a script + that fires at session start and appends instructions to the default system prompt (A9, A10). +- **Trade-offs:** This is the pattern Anthropic itself moved to for exactly this class of behavior, which is the + strongest prior-art signal available. It also adds to the default prompt rather than replacing it, so built-in + engineering instructions survive without a flag (A9). Against it: Han ships no hooks today, it adds a script to + maintain, and the hook still only appends text, so it enforces nothing more than a style file does. +- **Rests on:** (A2, A5, A8, A9, A10) +- **Evidence status:** corroborated + +### O5: A collaboration output style with readability moved into an imported memory file + +- **What it is:** Let the new style own the collaborative loop alone, and carry the readability standard through an + import in your own memory file so both apply at once. +- **Trade-offs:** Solves the one-style-at-a-time constraint directly, and Han's prior research already named this import + route as a viable option (A38). The cost is real: memory content is documented as "context, not enforced + configuration," with no guarantee of strict compliance (A5). So readability would carry less weight than it does in + the system prompt today. +- **Rests on:** (A1, A5, A38) +- **Evidence status:** corroborated + +### O6: Extend `code-walkthrough` to run concurrently during implementation + +- **What it is:** Change the existing walkthrough skill from retrospective to concurrent, so it walks you through code + as it is written rather than after. +- **Trade-offs:** Reuses a loop that already works and is already documented. But `code-walkthrough` is explicitly + read-only and "never edits the target" (A33), so this inverts its stated contract and collides with its declared + boundary against sibling skills. It also remains opt-in rather than always-on. +- **Rests on:** (A33, A35) +- **Evidence status:** corroborated + +### O7: An output style plus a post-edit hook that injects a checkpoint reminder + +- **What it is:** Add a hook after file edits that injects a reminder to pause and explain. +- **Trade-offs:** Hooks are the only mechanism that applies regardless of what Claude decides (A5, A8). But no hook + event corresponds to a logical chunk boundary, and a post-tool hook cannot block or undo the edit that already ran + (A2). Firing after every edit would interrupt far more often than the chunk boundary you want. +- **Rests on:** (A2, A5, A8) +- **Evidence status:** corroborated + +### O8: Build the loop into the implementation skills directly, with no new output style + +- **What it is:** Add the chunk-explain-stop-review loop to `tdd` and its siblings as an operating principle inside each + skill file, exactly the way `code-walkthrough` carries its own pacing loop today. +- **Trade-offs:** This has the closest working precedent in the repository. `code-walkthrough` runs the whole turn-taking + loop from prose inside one skill file, with no output style and no companion skill involved (A33). It is also the + cheapest option to verify, because you can read the result in one file. Against it: the loop reaches only work you + start by invoking a skill. Ordinary requests, where you ask for something without naming a skill, get none of it, and + that is where the request said the behavior matters. It also duplicates the loop into every skill that needs it rather + than stating it once. +- **Rests on:** (A33, A34, A42) +- **Evidence status:** corroborated + +## Recommendation + +- **Recommendation:** O3. Build one skill that carries the whole loop, and build no output style at all. + +- **Why this changed:** The original recommendation was O2, a thin output style plus a companion skill wired to run + automatically. It rested on one premise: that the working mode had to reach ordinary requests, where you never name a + skill. The operator has since decided that an opt-in workflow is acceptable, and that forcing `tdd` or any other skill + into this mode is not wanted. That decision removes the only job the output style was doing. With the always-on + requirement withdrawn, the style half buys nothing that the skill does not already provide, and it costs the + readability standard, because only one output style runs at a time (A1). + +- **What the operator gives up, stated plainly:** Work you do not launch through the skill gets none of this behavior. + That is the whole cost, it is understood, and it is the operator's call. + +- **Evidence basis:** O3 rests on corroborated evidence. The documentation names skills as the mechanism for a reusable + workflow and separates them from output styles, which it scopes to role, tone, and format (A1). Han's `code-walkthrough` + skill is the working proof inside this repository: it runs the full turn-taking loop from prose in a single skill + file, with no output style and no companion, and it states its own reasoning for stopping after every step (A33). The + four limits on what a style can carry no longer bear on the design, because no style is being built (A38). + + Three design parameters carry into the skill, at the strength the evidence supports. Writing feedback into a durable + file rather than trusting conversation history is the best-evidenced decision here, resting on peer-reviewed research + on long-context attention (A23) plus vendor documentation stating the same limit against its own product's convenience + (A5, A12). The chunk-size target of roughly 200 to 400 lines comes from a single study read through a blog's paraphrase + (A18) [single-source]. The task-shaped chunk heuristic is convergent practitioner guidance with no outcome data behind + it (A12, A13, A14, A15). + + Dropping the style also retires the report's largest open question. The contradiction between Anthropic's documentation + and Anthropic's own code repository over whether Explanatory and Learning were deprecated (A1 against A9, A10) decided + only whether the style half should have been a session-start hook instead. With no style and no hook in the design, + that conflict no longer touches the recommendation. It remains recorded above in case a later design revisits the + always-on question. + + What this does not settle: nothing here can force a stop at a chunk boundary, and that was true of every option + considered (A2, A5, A7, A8). The skill relies on instruction-following for its stops, with `code-walkthrough` as local + evidence that prose instruction carries turn-taking acceptably in practice (A33). + +## Validation + +### V1: The single-style constraint was asserted without a source + +- **Strategy:** Challenge the Evidence +- **Investigation:** Searched the whole draft for the claim that only one output style runs at a time. It appeared twice + and carried no artifact ID, in a report that cites nearly every other sentence. +- **Result:** Confirmed. +- **Impact:** The claim now cites A1 and is labeled as inferred from the documented settings schema rather than stated + outright. The report tells you to confirm it before committing to a design that depends on it. + +### V2: The `tdd` skill has a second stopping point outside the cited line range + +- **Strategy:** Challenge the Evidence +- **Investigation:** Read `han-coding/skills/tdd/SKILL.md` past the cited range. Lines 89 to 91 describe a hard stop when + no test command can be resolved, which the draft's "one gate" framing omitted. +- **Result:** Partially Refuted. The quote inside the cited range was accurate; the summary around it was incomplete. +- **Impact:** The `tdd` description now names both stopping points. Neither is collaborative, so the underlying finding + stands. + +### V3: The readability precedent did not match what O2 proposed + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Read `han-communication/skills/readability-guidance/SKILL.md`. It runs inline in the caller's + context and hands control straight back, and 27 skill files invoke it (verified by search). Nobody invokes it by hand. + The draft's companion skill had no such host and would have been a top-level command. +- **Result:** Refuted. The analogy did not hold as written. +- **Impact:** The largest change in this report. O2 now requires wiring the companion skill as an automatic sub-step of + the implementation skills, and the Recommendation states that the precedent holds only in that corrected form. + +### V4: An option was missing, and it is the one with the closest local precedent + +- **Strategy:** Challenge the Options Framing +- **Investigation:** Checked whether any option proposed adding the loop directly to an existing implementation skill, + the way `code-walkthrough` carries its own pacing loop with no style and no companion. None did. +- **Result:** Confirmed. +- **Impact:** Added as O8. It does not displace O2, because it reaches only skill-invoked work and misses the ordinary + requests the request centers on. Its approach is now folded into O2 as the wiring mechanism. + +### V5: The always-on claim overstated what the recommendation delivers + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Compared the request for an always-on working mode against O2's own trade-off line, which conceded + that the deep behavior arrives only when the skill is invoked. +- **Result:** Confirmed. +- **Impact:** The Recommendation now carries a section stating exactly what each half delivers, including the gap for + ordinary requests that touch no skill. + +### V6: The instruction-stacking number measures a different kind of compliance + +- **Strategy:** Challenge the Evidence +- **Investigation:** Read the cited lines in the prior research file. The measurement covers content constraints such as + tone, length, and format, not whether an agent executes a workflow gate while mid-task. +- **Result:** Partially Refuted. The transfer is plausible but was presented as a direct finding. +- **Impact:** The report now flags this as an extrapolation where it uses the number. + +### V7: The recommendation header hid its own conditionality + +- **Strategy:** Challenge the Evidence-Gathering Integrity +- **Investigation:** The draft stated a flat recommendation of O2, then disclosed three paragraphs later that A9 and A10 + could flip half of it. +- **Result:** Partially Refuted. The disclosure was honest but badly placed. +- **Impact:** The conditional now sits in the recommendation line itself. + +### V8: Single-sourced material stayed out of the core argument + +- **Strategy:** Challenge the Evidence-Gathering Integrity +- **Investigation:** Counted single-sourced artifacts (21 of 41 at the time of the check) and traced whether any carried + weight in the recommendation's evidence basis. The load-bearing claims pin to A1, A8, A23, A38, and A39, none of them + single-sourced. The low-confidence preprint (A26) appears only as a labeled directional hint. +- **Result:** Confirmed, in the report's favor. +- **Impact:** No change. The single-sourced material stays confined to secondary design parameters such as chunk size. + +### V9: The operator-escalation rule does not reach coding skills at all + +- **Strategy:** Challenge the Evidence +- **Investigation:** Read the rule's consumers line. It names four planning skills and no coding skill. +- **Result:** Refuted on the reasoning. The draft's conclusion was right, its stated reason was not. +- **Impact:** The report now says the rule is scoped to planning skills, rather than implying it is a general Han rule + the loop would need an exception from. + +### V10: The habituation conflict does not undermine the reflexive-approval warning + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Checked whether the warning rested on either study's disputed trend direction. It rests on the + mechanism both studies agree on: review load drives shallower reading, and surface polish lowers your guard. +- **Result:** Refuted as a threat to the report. +- **Impact:** No change needed. + +### Adjustments Made + +Validation changed the report substantially. The single-style constraint gained a citation and an inference label (V1). +The `tdd` description gained its second stopping point (V2). O2 was rewritten to require automatic wiring, and the +Recommendation now says its readability precedent holds only in that corrected form (V3). O8 was added (V4). The +Recommendation gained an explicit statement of what each half delivers and where the gap is (V5). The +instruction-stacking number gained an extrapolation caveat (V6). The conditional moved into the recommendation line +(V7). The operator-escalation reasoning was corrected (V9). + +The recommendation survived, but only after the correction in V3. Without automatic wiring, O2 does not answer the +question that was asked. + +### Operator decision after validation + +The recommendation later moved from O2 to O3, and the validation findings above are the reason it moved cleanly. V3 and +V5 together established that O2 delivered a thin always-on stance plus an opt-in mechanism, and that closing the gap +meant editing every implementation skill. Presented with that cost, the operator chose the opt-in workflow and declined +to force `tdd` or any other skill into this mode. Withdrawing the always-on requirement leaves the output style with no +job, so the design collapses to a single skill. The findings above are preserved as written, because they document how +the earlier recommendation was tested rather than the conclusion it reached. + +### Confidence Assessment + +- **Confidence:** High for the mechanism, Medium for the pacing details +- **Remaining Risks:** The rating is split because the two halves rest on different evidence. + + Choosing a skill over an output style is High. The documentation assigns workflows to skills (A1), a working example + of the same loop already runs in this repository (A33), and the operator's decision to accept an opt-in workflow + removed the one requirement that argued for a style. Dropping the style also retired the report's largest open + question, the contradiction between Anthropic's documentation and its own code repository over the Explanatory and + Learning styles (A1 against A9, A10). That conflict only ever decided whether the style should have been a hook. + + The pacing details stay at Medium. No study anywhere measures whether stopping for review at a chunk boundary is worth + its interruption cost, so cadence rests on converging practitioner guidance with no outcome data (A12, A13, A14, A15). + The chunk-size target is single-sourced through a paraphrase (A18). The habituation risk, that frequent narrated + checkpoints train reflexive approval, rests on a mechanism two studies agree on while disputing its direction (A16, + A17). + + One process caveat carries forward. The validator could not fetch web pages, so all 30 external artifacts rest on the + research agents' reporting rather than on independent confirmation. The codebase artifacts (A31 through A42) were + checked directly against the files and held up, and those are the artifacts the current recommendation leans on most. + + For the record: the validator rated the original O2 recommendation Low, on the uncited single-style constraint (V1) + and the broken readability analogy (V3). Both were corrected, and the recommendation has since moved to O3 on the + operator's decision. + +## Sources + +| ID | Source | Link / location | Retrieved | Trust class | Summary (one line) | Evidence status | +| --- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------- | ----------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | +| A1 | Claude Code docs: Output styles | https://code.claude.com/docs/en/output-styles | 2026-08-13 | web | Styles append to the system prompt, set role/tone/format, drop built-in coding instructions by default, main conversation only. | corroborated by A8; contradicted by A9, A10 | +| A2 | Claude Code docs: Hooks | https://code.claude.com/docs/en/hooks | 2026-08-13 | web | ~30 hook events; pre-tool can block, post-tool cannot because the tool already ran. | corroborated by A3, A5, A8 | +| A3 | Claude Code docs: Skills | https://code.claude.com/docs/en/skills | 2026-08-13 | web | Skills are loaded instructions for reusable workflows; influence can fade over a session without error. | corroborated by A2, A5 | +| A4 | Claude Code docs: Subagents | https://code.claude.com/docs/en/sub-agents | 2026-08-13 | web | Subagents run their own system prompt and return only a final message. | corroborated by A1, A8 | +| A5 | Claude Code docs: Memory | https://code.claude.com/docs/en/memory | 2026-08-13 | web | CLAUDE.md is context, not enforced configuration; use hooks for anything that must run at a fixed point. | corroborated by A2, A8, A12 | +| A6 | Claude Code docs: Checkpointing | https://code.claude.com/docs/en/checkpointing | 2026-08-13 | web | Snapshots for undo and rewind; not a pause-for-review gate. | single source (primary doc for the feature) | +| A7 | Claude Code docs: Permission modes | https://code.claude.com/docs/en/permission-modes | 2026-08-13 | web | Plan mode is a real enforced stop, but gates planning versus executing, once. | single source (primary doc for the feature) | +| A8 | Anthropic blog: Steering Claude Code | https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more | 2026-08-13 | web | Output styles carry the highest instruction-following weight; hooks are for deterministic behavior. | corroborated by A1, A2, A5 | +| A9 | anthropics/claude-code: explanatory plugin | https://github.com/anthropics/claude-code/tree/main/plugins/explanatory-output-style | 2026-08-13 | web | States it recreates the "deprecated Explanatory output style" as a SessionStart hook. | contradicts A1; corroborated by A10 | +| A10 | anthropics/claude-code: learning plugin | https://github.com/anthropics/claude-code/tree/main/plugins/learning-output-style | 2026-08-13 | web | States it combines the "unshipped Learning" and "deprecated Explanatory" styles as a SessionStart hook. | contradicts A1; corroborated by A9 | +| A11 | GitHub issue: output styles ignored (#6450) | https://github.com/anthropics/claude-code/issues/6450 | 2026-08-13 | web | One user reports a custom style's tone instructions being overridden; closed "not planned". | single source (caveated, community anecdote) | +| A12 | Claude Code docs: Best practices | https://code.claude.com/docs/en/best-practices | 2026-08-13 | web | Skip checkpoints for one-sentence changes; after two failed corrections, context is polluted, start fresh. | corroborated by A5, A23 | +| A13 | Thoughtworks: review gates for AI dev | https://www.thoughtworks.com/insights/blog/generative-ai/how-to-implement-effective-review-gates-for-ai-assisted-development | 2026-08-13 | web | Two-tier gate: mechanical inner gate per cycle, human outer gate at milestones. | single source (caveated) for the two-tier design | +| A14 | Addy Osmani: LLM coding workflow 2026 | https://addyo.substack.com/p/my-llm-coding-workflow-going-into | 2026-08-13 | web | Two or three human checkpoints per feature; trim older context to keep pause-and-resume clean. | corroborated by A13, A15 | +| A15 | systemdesign.one: AI coding workflow | https://newsletter.systemdesign.one/p/ai-coding-workflow | 2026-08-13 | web | Implement one step at a time; asking for too much at once produces output that is hard to untangle. | corroborated by A13, A14 | +| A16 | Habituation at the Gate (arXiv 2606.22721) | https://arxiv.org/pdf/2606.22721 | 2026-08-13 | web | 400 repeat reviewers over 207 days: approval up 30.1% to 36.8%, inline comments down 22%. | contradicted in direction by A17 | +| A17 | 3100 Opinions on Code Review (arXiv 2607.07980) | https://arxiv.org/pdf/2607.07980 | 2026-08-13 | web | Grounded theory from 3,100 documents; AI code's surface polish lowers scrutiny; unreviewed merges fell to ~13%. | contradicts A16 on trend; corroborates mechanism | +| A18 | Cisco / SmartBear code review study | https://mikeconley.ca/blog/2009/09/14/smart-bear-cisco-and-the-largest-study-on-code-review-ever/ | 2026-08-13 | web | 70-90% defect discovery at 200-400 LOC over 60-90 min; author annotation lowered defect density. | single source (caveated, read as paraphrase) | +| A19 | Martin Fowler: On Pair Programming | https://martinfowler.com/articles/on-pair-programming.html | 2026-08-13 | web | Driver and navigator roles; articulating reasoning forces you to check your own understanding. | corroborated by A20, A22 | +| A20 | Llewellyn Falco: strong-style pairing | http://llewellynfalco.blogspot.com/2014/06/llewellyns-strong-style-pairing.html | 2026-08-13 | web | An idea must pass through someone else's hands; originally a coaching technique for juniors. | single source (caveated, practitioner blog) | +| A21 | Cognitive Apprenticeship (Collins et al.) | https://www.isls.org/research-topics/cognitive-apprenticeship/ | 2026-08-13 | web | Six methods including articulation and reflection for making expert thinking visible. | single source (caveated, read via summaries) | +| A22 | Cockburn & Williams, XP2000 | https://www.cs.utexas.edu/~ans/classes/cs439/projects/XPSardinia.PDF | 2026-08-13 | web | Pairing costs ~15% more time; paired code passed a significantly higher share of acceptance tests. | corroborated by A19 | +| A23 | Lost in the Middle (Liu et al., TACL) | https://arxiv.org/abs/2307.03172 | 2026-08-13 | web | Accuracy drops >30% when relevant information sits mid-context; replicated across six model families. | corroborated by A5, A12 | +| A24 | Gloria Mark: Cost of Interrupted Work | https://ics.uci.edu/~gmark/chi08-mark.pdf | 2026-08-13 | web | Average 23-minute-15-second resumption lag after an interruption in general knowledge work. | single source (caveated for this application) | +| A25 | WorkOS: approval fatigue in agent governance | https://workos.com/blog/approval-fatigue-agent-governance | 2026-08-13 | web | Frequent approval prompts lead users to stop reading and approve reflexively. | single source (caveated, vendor writing) | +| A26 | The Compliance Gap (arXiv 2605.01771) | https://arxiv.org/abs/2605.01771 | 2026-08-13 | web | Claims one explicit mid-session correction repaired compliance in 30 of 30 sessions. | single source (caveated, low confidence) | +| A27 | Parasuraman & Riley, Human Factors 1997 | https://journals.sagepub.com/doi/10.1518/001872097778543886 | 2026-08-13 | web | Names automation misuse (over-reliance, complacency) as a distinct human-automation failure mode. | corroborated (cited by A16 and A26) | +| A28 | Collaborator or Assistant? (arXiv 2605.08017)| https://arxiv.org/html/2605.08017 | 2026-08-13 | web | Agents initiate ≥96% of PRs but approve merges in <0.1%; humans retain terminal authority. | single source (caveated for exact figures) | +| A29 | Reddit threads on shipping in small chunks | https://www.reddit.com/r/ClaudeAI/comments/1ro12vz/how_to_tell_your_coding_agent_to_ship_features_in/ | 2026-08-13 | web | Confirms this exact workflow is a live named practitioner concern. | single source (caveated, community anecdote) | +| A30 | Scale X: AI agent permission telemetry | https://scalex.dev/blog/ai-agent-permissions-stats/ | 2026-08-13 | web | Reports users approve ~93% of permission prompts; game players missed 1 injected threat in 3 (66.3% accuracy). | single source (caveated, vendor telemetry) | +| A31 | Han readability output style | `han-communication/output-styles/han-readability.md:1-98` | n/a | codebase | 98 lines directing prose properties only; sets the keep-coding-instructions flag; no behavioral direction. | corroborated by A32, A38 | +| A32 | han-communication plugin manifests | `han-communication/.claude-plugin/plugin.json` | n/a | codebase | Output styles are auto-discovered from `output-styles/`; no manifest field declares them. | corroborated by A31 | +| A33 | code-walkthrough skill | `han-coding/skills/code-walkthrough/SKILL.md:1-234` | n/a | codebase | One step per turn then stop; a question holds position; read-only and never edits the target. | corroborated by A34, A35 | +| A34 | tdd skill | `han-coding/skills/tdd/SKILL.md:75-91` | n/a | codebase | Runs autonomously; a plan-review gate only on request, plus a hard stop for a missing test command; then runs to completion. | corroborated by A35 | +| A35 | code-overview skill | `han-coding/skills/code-overview/SKILL.md:1-100` | n/a | codebase | Read-only, writes a scratch file, no interactive loop; defers pacing to code-walkthrough. | corroborated by A33 | +| A36 | operator-escalation rule | `han-planning/references/operator-escalation-rule.md:16-100` | n/a | codebase | One question per turn; exactly one stop per run, only for input only the operator can supply. | corroborated by A37 | +| A37 | explanation rule | `han-communication/references/explanation-rule.md:1-89` | n/a | codebase | Concrete outcome over mechanism; no shorthand terms; consequence before detail; no self-check. | corroborated by A36 | +| A38 | Prior research: readability in output styles | `docs/research/readability-guidance-in-output-styles.md:27-113` | n/a | codebase | Styles are fixed text: no file includes, no path variable, no subagent reach, no runtime config reads. | corroborated by A1, A39 | +| A39 | Prior research: human-readable standard | `docs/research/human-readable-output-standard.md:37-41` | n/a | codebase | Compliance falls from 85-90% at one instruction to 15-44% when many are stacked; audience framing is strongest. | corroborated by A38 | +| A40 | Prior research: LLM code understanding | `docs/research/llm-accelerated-code-understanding.md:1-71` | n/a | codebase | AI speeds tasks without improving comprehension; high-comprehension users verified output 4.7x more often. | corroborated by A17 | +| A41 | Han documentation obligations | `CLAUDE.md:80-81,301-302` | n/a | codebase | A new output style needs the style file, a long-form doc, and a plugin README scent line; no repo-root index yet. | single source (project convention) | +| A42 | readability-guidance skill | `han-communication/skills/readability-guidance/SKILL.md` | n/a | codebase | Runs inline in the caller's context and hands control back; 27 skill files invoke it automatically, not the user. | corroborated by A31, A38 | + +### A1: Claude Code documentation on output styles — recommendation-bearing + +- **Link / location:** https://code.claude.com/docs/en/output-styles +- **Retrieved:** 2026-08-13 +- **Trust class:** web (outside the trust boundary) +- **Summary:** States output styles "change how Claude responds, not what Claude knows" and "modify the system prompt to + set role, tone, and output format." A custom style is a markdown file in a personal, project, or plugin + `output-styles/` directory, and Claude Code "adds each output style's custom instructions to the end of the system + prompt." Unless the file sets `keep-coding-instructions: true`, the style leaves out the built-in software-engineering + instructions covering how to scope changes, when to add comments, security concerns, and verification habits. Styles + apply to the main conversation only, because subagents run their own system prompt. The page's comparison table places + output styles apart from skills, which it describes as the mechanism for a reusable workflow. It lists Proactive, + Explanatory, and Learning as built-in styles beyond Default. +- **Evidence status:** corroborated by A8 on the injection mechanics and the role/tone/format scope; contradicted by A9 + and A10 on whether Explanatory and Learning are currently shipped as output styles + +### A8: Anthropic blog on steering Claude Code — recommendation-bearing + +- **Link / location:** https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more +- **Retrieved:** 2026-08-13 +- **Trust class:** web (vendor writing, outside the trust boundary) +- **Summary:** Describes output styles as files that "inject instructions into the system prompt" and never get + compacted. They "carry the highest instruction-following weight of any method," with the caution that they "should be + used judiciously." A custom style "drops all of this" (the built-in engineering instructions) unless configured to + keep them. Directs hooks at "anything that should happen deterministically" and notes a pre-tool hook can inspect a + call and block it. Describes CLAUDE.md as loading into context at session start and staying for the session, and + subagents as returning only a final message to the main session. +- **Evidence status:** corroborated by A1 on output-style mechanics, and by A2 and A5 on hook determinism + +### A9: Anthropic's explanatory-output-style plugin — recommendation-bearing + +- **Link / location:** https://github.com/anthropics/claude-code/tree/main/plugins/explanatory-output-style +- **Retrieved:** 2026-08-13 +- **Trust class:** web (Anthropic's own repository, but a plugin artifact rather than canonical documentation) +- **Summary:** The README states verbatim that the plugin "recreates the deprecated Explanatory output style as a + SessionStart hook," authored by an Anthropic employee per the plugin manifest. It implements the behavior through a + session-start hook rather than the `output-styles/` directory, and frames that pattern as "roughly equivalent to + CLAUDE.md, but more flexible and allows for distribution through plugins." It adds that behavior involving tasks + besides software development is "better expressed as subagents, not as SessionStart hooks." That is because + "Subagents change the system prompt while SessionStart hooks add to the default system prompt." +- **Evidence status:** contradicts A1's listing of Explanatory as a current built-in output style; corroborated by A10 + +### A10: Anthropic's learning-output-style plugin — recommendation-bearing + +- **Link / location:** https://github.com/anthropics/claude-code/tree/main/plugins/learning-output-style +- **Retrieved:** 2026-08-13 +- **Trust class:** web (Anthropic's own repository, plugin artifact) +- **Summary:** The README states verbatim that the plugin "combines the unshipped 'Learning' output style with the + deprecated 'Explanatory' output style," again implemented as a session-start hook. Its behavior is close kin to the + requested loop: it identifies "meaningful 5-10 line code contributions at decision points" for the person to write, + implements boilerplate directly, and adds periodic explanations. By this source, the collaborative pause-at-decision- + points behavior that Anthropic's documentation describes as a built-in output style was never shipped that way. +- **Evidence status:** contradicts A1's listing of Learning as a current built-in output style; corroborated by A9 + +### A23: Lost in the Middle (Liu et al., TACL) — recommendation-bearing + +- **Link / location:** https://arxiv.org/abs/2307.03172 +- **Retrieved:** 2026-08-13 +- **Trust class:** web (peer-reviewed journal paper, the strongest-tier source in this report) +- **Summary:** Model performance on long-context tasks follows a U-shaped curve by position. Accuracy is highest when + the relevant information sits at the beginning or the end of the context and degrades by more than 30 percent when it + sits in the middle. The finding was replicated across six model families. This is the load-bearing evidence for + writing feedback into a durable file rather than relying on it surviving in the middle of a long conversation. I read + secondary write-ups rather than the primary journal article, though the finding is consistently reported across + independent summaries. +- **Evidence status:** corroborated by A5 and A12, which state the same practical limit in vendor documentation + +### A31: Han's existing readability output style — recommendation-bearing + +- **Link / location:** `han-communication/output-styles/han-readability.md:1-98` +- **Retrieved:** n/a +- **Trust class:** codebase (trusted current-state anchor) +- **Summary:** A 98-line file with frontmatter carrying a name, a description, and the keep-coding-instructions flag, + followed by prose directives. It directs prose properties only, never behavior or working mode. Those properties are + main point first, one idea per paragraph, descriptive headings, short active sentences, common words, numbered lists + for steps, progressive disclosure, and technical detail after the prose. Its closing section scopes everything to + prose, excluding code fences, diagram bodies, rendered markup, and citation identifiers. This is the working example + of the thin-style + pattern the recommendation extends. +- **Evidence status:** corroborated by A32 on how it is wired, and by A38 on the design reasoning behind its scope + +### A33: Han's code-walkthrough skill — recommendation-bearing + +- **Link / location:** `han-coding/skills/code-walkthrough/SKILL.md:1-234` +- **Retrieved:** n/a +- **Trust class:** codebase (trusted current-state anchor) +- **Summary:** Implements the turn-taking loop the request describes, through prose instruction alone. It directs + "One step per turn, then stop and wait," forbids chaining two steps, and states the reasoning inline: "the pacing _is_ + the deliverable." A question about the current step holds position rather than advancing, and the step counter does + not move. It is read-only and "never edits the target and never writes a file," which is why it covers retrospective + walkthroughs rather than walking through code as it is written. It sources the explanation standard and dispatches + codebase-explorer agents, both of which a style file could not do. +- **Evidence status:** corroborated by A34 and A35, which show the neighboring skills carry no comparable loop + +### A38: Prior Han research on readability guidance in output styles — recommendation-bearing + +- **Link / location:** `docs/research/readability-guidance-in-output-styles.md:27-113` +- **Retrieved:** n/a +- **Trust class:** codebase (trusted current-state anchor) +- **Summary:** Establishes four limits on what an output style can carry in this project. A style is fixed text added + to the system prompt at session start, with nothing documented for including other files or running commands. The + plugin path variable does not resolve inside a style file. Styles do not reach subagents. And copying a whole standard + into one block contradicts the standard's own staged design, because compliance drops when instructions stack. It + records that the readability rule and writing-voice profile together run 33,439 bytes, and recommends a short style + carrying the always-on layer only, leaving runtime work to the skill. It also names an import in the personal memory + file as a route to reach subagents. +- **Evidence status:** corroborated by A1 on style mechanics, and by A39 on the instruction-stacking measurement + +### A42: Han's readability-guidance skill — recommendation-bearing + +- **Link / location:** `han-communication/skills/readability-guidance/SKILL.md` +- **Retrieved:** n/a +- **Trust class:** codebase (trusted current-state anchor) +- **Summary:** The skill that partners with the readability output style, and the precedent the recommendation leans on. + It states that it "runs in your context, not an isolated one." It is "a means to writing your deliverable, not the + deliverable itself." And the caller should "RETURN to the workflow that called you and finish it." A search of the + repository found 27 skill files that invoke it. That matters for the design here: the skill works because its callers + invoke it automatically, not because a person remembers to. Adversarial validation used this file to refute the draft's + original claim that a user-invoked companion skill would mirror the readability split. +- **Evidence status:** corroborated by A31 on the style half of the pattern, and by A38 on why the split exists + +### A39: Prior Han research on the human-readable output standard — recommendation-bearing + +- **Link / location:** `docs/research/human-readable-output-standard.md:37-41` +- **Retrieved:** n/a +- **Trust class:** codebase (trusted current-state anchor) +- **Summary:** Reports that instruction compliance drops from 85 to 90 percent at one instruction to between 15 and 44 + percent when many are stacked, and that the fix is to split work across passes rather than issuing one block. It also + records that audience targeting is the single most-evidenced instruction for plain output, backed by three independent + clinical studies, and that few-shot examples beat abstract instructions. These findings are why the recommendation + keeps the new style short rather than folding a full procedure into it. +- **Evidence status:** corroborated by A38, which applies the same finding to output-style design diff --git a/docs/research/non-code-chunk-boundaries.md b/docs/research/non-code-chunk-boundaries.md new file mode 100644 index 00000000..91eda74a --- /dev/null +++ b/docs/research/non-code-chunk-boundaries.md @@ -0,0 +1,639 @@ +# Research: Stopping Points for Collaborative Work That Is Not Code + +What makes a good stopping point for human review when an assistant is doing collaborative work that is not code, and +who should decide where that point falls? Evidence mode: strict. + +## Summary + +Stop where the kind of feedback changes, not where a word count is hit. That is the one finding solid enough to build +on. It holds across professional editing bodies, two peer-reviewed studies of how writers revise, and design +practice in a separate field. Review the shape of the work before its surface, every time. Polish applied before the +shape is settled gets thrown away when the shape changes. + +That gives a different unit for each kind of work. For a decision, the unit is one decision, presented with its context, +the options weighed, and what it commits you to. For written work, the unit is one rung of a fidelity ladder: the shape +first, then a rough draft, then the language. You get structural feedback while the work is still cheap to restructure, +and you never review the same thing twice for two different concerns. For code you already have the answer. For +genuinely open-ended work there is no established answer, and I found none, so the assistant should propose a plan and +let you change it. + +One finding should change how the walkthrough itself is written. Explaining your reasoning to a reviewer does not +reliably make them more careful, and can make them less so. Explanations read as a signal of competence whether or not +their content holds up, and a polished explanation invites agreement. What does work is making claims cheap to check, +and getting the reviewer to form a view before they see the reasoning. So the walkthrough should hand you something to +check, not something to be convinced by. + +Two smaller results are worth carrying. Who picks the stopping point barely matters for commitment, as long as the +reason for the choice is stated, so the assistant proposing a plan you can redirect is fine. + +Feedback also belongs in a written record rather than in the assistant's memory of the conversation, which your suite +already has a convention for. + +The gap: nobody has studied this exact situation. Every source describes humans reviewing a mostly-finished thing, or a +person using an assistant once. An assistant building something with you across many stops is not in the literature. + +- **Confidence:** High for staging by concern, Medium for the per-kind units, Low for open-ended work + +## Research Results + +### Stop where the concern changes, not where the document divides + +This is the best-evidenced finding in the whole report, and it comes from four independent directions. + +Professional editing stages work by concern in a fixed order: structure first, then language and style, then grammar and +consistency, then typographical errors on a near-final proof. Two national professional bodies define the same stages in +the same order, one in the United States and one in the United Kingdom (A16, A17). Multiple practitioner editors give +the same reason for the order (A20). + +Two peer-reviewed studies of how people revise back it up from a different angle. Inexperienced writers revise at the +word level, while experienced writers revise for meaning and structure first (A18, A19). That is genuine corroboration +rather than one claim repeated, because professional practice and academic research arrived at it separately. + +The reason the order matters is concrete. Polishing a paragraph that a structural edit will delete is, in one editor's +words, "effort spent decorating rooms that are about to be knocked through" (A20). + +The same principle shows up in design work, from sources with no connection to editing. Low-fidelity work draws +structural feedback while high-fidelity work draws only cosmetic feedback, and people are reluctant to criticize +something that looks finished (A13). An engineering leader writing about design proposals observed the same thing +independently: "the more polished a document looks, the softer reviews tend to be" (A12). Two unrelated fields reaching +the same conclusion is strong corroboration. + +### The unit for a decision is one decision + +For work that produces a decision rather than an artifact, the established unit is unambiguous. The originating source +for the architectural decision record states that "one ADR describes one significant decision" (A10). An independently +maintained community reference says the same thing in nearly identical words (A11). Both put it at one or two pages +with a fixed shape: the context, the decision, and its consequences. + +How much review a decision deserves scales with how reversible it is. Amazon's framework separates decisions you can +walk back cheaply from ones you cannot, and prescribes fast review by a small group for the first and slow, wide review +for the second (A6). + +Every decision-record template separates the problem, the options, and the chosen option into distinct sections, and +that convergence is well corroborated across at least four independent template families (A10, A11). + +But **no source treats those three sections as three separate review checkpoints**. That is a real gap: they are +documented as parts of one document, written and reviewed together. Turning them into a review sequence is a +reasonable extension, not an established practice, and I am flagging it as such rather than dressing it up. + +Published proposal processes offer less than you would hope. The Rust language's process gives no size guidance and no +rule for splitting a large proposal, and the same search of Python's process returned nothing either (A3). One +widely-cited account of design documents at Google gives concrete numbers: roughly ten to twenty pages for a large +one, one to three pages for a small one, with direction to split when a document outgrows itself. That figure comes +from one author's account (A8) [single-source]. + +### The unit for prose is one rung of a fidelity ladder + +Reviewing prose section by section is the wrong cut. The editorial staging above operates on the whole manuscript per +pass, not on one chapter at a time. + +That creates a problem this loop has to solve. Editorial staging assumes a finished draft already exists, because its +first pass reads the whole thing for structure. A loop that produces work in pieces cannot wait for a finished draft +before its first stop. Taken literally, the editorial unit would make the first chunk "write the entire draft," which is +no loop at all. + +The resolution is to stage by fidelity rather than by pass over a finished artifact. Review the shape while it is still +a shape, then the rough draft, then the language. Two independent lines of evidence support this. A university writing +center states the timing rule directly: feedback on an outline or rough draft can still change foundational choices. +Feedback on a polished draft is limited to surface concerns, because the foundations are no longer practically +revisable (A22). Design practice reaches the same place from another direction, finding that low-fidelity work draws +structural feedback and high-fidelity work draws only cosmetic feedback (A13). + +Staging by fidelity keeps what the editorial evidence establishes, which is the order of concerns, while +dropping the precondition that the whole draft exist first. Each rung is a chunk, and the concern reviewed at that rung +is set by the staging rule. + +The competing pattern is worth naming because it is real. Amazon's narrative process caps a document at six pages, has +the group read it in silence, and discusses it as a whole. It is deliberately not circulated in pieces (A25) +[single-source], on the argument that reading parts in isolation produces worse structural feedback than reading the +connected whole. Reverse outlining sits in the same family, distilling each paragraph of a finished draft to its main +idea to check structure before any language work (A21). Both require the artifact to exist before review starts. + +Writing workshops give one concrete size: two and a half to five thousand words per piece (A24) [single-source]. + +They also give a rule worth stealing. Two independent sources describe a named alternative to the standard workshop +that sequences feedback deliberately: what is working, then the author's own questions, then neutral questions, then +opinions only with permission (A23). That is the same structure-before-surface principle, applied inside a single +conversation rather than across separate passes. + +### Explaining your reasoning can make the reviewer less careful + +This is the finding that should change the design, and it is well corroborated by controlled studies. + +Passive explanations do not reliably reduce over-reliance on an assistant's output, and sometimes increase it (A33). +Explanations act partly as a signal of competence, working on the reviewer's trust regardless of whether the content +holds up (A35). One study of five experiments with 731 participants found explanations reduce over-reliance only when +they lower the cost of checking the claim independently. Hard-to-parse explanations make things worse, because they +raise that cost (A32). + +The one intervention that worked better than any explanation design was making the reviewer commit to their own +judgment before seeing the assistant's reasoning (A33). It cost reviewer satisfaction, which the study measured rather +than assumed. + +One result cuts the other way and is worth keeping. A randomized trial of 108 reviewers found no significant anchoring +effect: reviewers shown a flawed early version revised their assessment once corrected material arrived (A36) +[single-source]. So showing your work early does not permanently fix someone's view. + +Taken together: a walkthrough should hand the reviewer concrete, checkable claims rather than a fluent case, and should +not lead with the reasoning that makes the work sound right. + +### Who picks the stopping point matters less than whether the reason is stated + +Fifty years of goal-setting research says that when difficulty is held constant, goals someone helped set and goals +assigned to them produce statistically indistinguishable performance. An assigned goal reaches equivalent +commitment when it comes with a rationale (A30, A31). Participation's real effect is that people set themselves harder +targets. + +That literature answers a narrower question than the one asked. It measures the commitment of the person doing the work, +not the care of the person reviewing it. **No study compares how carefully someone reviews at a checkpoint they +helped choose against one imposed on them.** That is a genuine gap, and the goal-setting evidence should not be read as +settling it. + +### Review degrades without an objective gate, but nobody has measured how much + +Habituation is corroborated. A systematic review found that reviewers of highly-but-imperfectly reliable systems show +measurable desensitization over time. Erroneous advice raised the risk of an incorrect decision by 26 percent +across four clinical studies (A29). Practitioner accounts name the same pattern for AI-written code and recommend +anchoring review in objective gates such as tests (A38, A39). + +Survey data shows a gap between stated distrust and actual behavior. 96 percent of developers say they do not fully +trust AI-generated code, while only 48 percent consistently verify it before merging (A37) [single-source for the exact +figures, from a vendor selling code-quality tooling, though the direction is corroborated by an independently run +survey]. + +**No study compares degradation between artifacts with an objective pass-or-fail gate and artifacts without one.** The +automation-bias literature comes largely from aviation and clinical settings, which do have eventual objective outcomes, +so it does not isolate the missing-ground-truth variable. The reasoning that a failing test is exactly the kind of +salient failure signal that interrupts habituation is plausible and unevidenced, and I am not carrying it as a finding. + +### Feedback belongs in a written record + +No study tests written-versus-remembered feedback for this kind of work. The closest well-evidenced analogy is surgical: +teams using a written checklist missed about 6 percent of critical steps against about 23 percent when working from +memory, in simulated crisis scenarios (A41). + +Professional editing implements exactly this with the style sheet, a running record of decisions and their reasons kept +so a decision does not have to be re-argued or misremembered later (A42). That is mature convention rather than measured +outcome. + +### Stopping costs something, and the cost is measured + +Knowledge workers take an average of 23 minutes and 15 seconds to return to a task at full focus after an interruption +(A40). That study is about general knowledge work, not about reviewing an assistant's output, so applying it here is +inference. + +Two independent practitioner accounts describe review quality decaying into rubber-stamping past some volume threshold, +though neither identifies where that threshold sits (A43). + +### Your own suite already runs three patterns + +Han contains three proven approaches, and the differences between them are instructive. + +**One unit per turn.** The walkthrough presents one step and ends the turn. The escalation rule allows one question per +turn while stating how many are pending. The API design skill surfaces open items one at a time, never batched, because +"each answer routinely settles or reshapes the ones behind it" (A44, A46, A48). + +**Bounded rounds with a stop rule that is computed, not judged.** The plan-review skill runs review rounds capped by +size band and stops on a deterministic condition: two or fewer new findings and zero major ones (A53). Its sibling +aggregates each round into a claim ledger that groups findings by category and marks each one evidenced, anecdotal, +disputed, or unverified, then gates on that (A54). This is neither of the other two patterns. Review happens in batches, +but how many batches is decided by what the batches turn up rather than by a plan fixed in advance. + +**Whole artifact, then review.** The documentation skill drafts the complete document and only then dispatches +reviewers, with its two operator questions confined to the opening step before any drafting (A51). The coding-standard +skill is close but not the same: it stops mid-draft to get approval for the file globs its standard will govern, and +will "not write the file until the user confirms or proposes a substitute" (A52). So one skill in this suite genuinely +runs stop-free after its opening, and one has a single mid-draft gate on a choice that is expensive to get wrong. + +There is also an existing convention for carrying feedback forward: an escalation register recording each question as +asked, the answer, and where the answer landed (A47). + +## Options to Consider + +### O1: Stage by concern, with the unit set by the kind of work + +- **What it is:** The boundary falls where the kind of feedback changes. One decision for decision work, one rung of a + fidelity ladder for prose, one behavior or one named refactoring for code. +- **Trade-offs:** Rests on the strongest evidence in the report, with support from four independent directions. Two + costs. It needs a different unit defined per kind of work, and for open-ended work no source defines one. The + prose unit is a reconciliation rather than a direct reading. The editorial evidence establishes the order of concerns, + but it assumes a finished draft. This option keeps that order and drops the precondition, on the strength of two + further sources about when feedback can still change something (A13, A22). +- **Rests on:** (A10, A11, A13, A16, A17, A18, A19, A20, A22) +- **Evidence status:** corroborated for the concern order; the fidelity-ladder unit for prose is a reconciliation of + A16 through A20 with A13 and A22, not a practice any single source documents + +### O2: A negotiated chunk plan, proposed by the assistant and redirected by you + +- **What it is:** Before work starts, the assistant proposes where it will stop and why. You accept or change it, and + either side can renegotiate as the work reveals itself. +- **Trade-offs:** Goal-setting research says a stated rationale closes most of the gap between an imposed plan and a + negotiated one (A30, A31). So a proposal you can change costs little and buys a cheap early correction. Your API + design skill already runs this shape (A48). Against it: no evidence that negotiating a checkpoint makes anyone review + more carefully at it, which is a real gap rather than a demonstrated weakness. +- **The alternative this option does not beat on evidence:** asking the person where to stop before proposing anything. + The same research shows participation's real effect is that people set themselves harder targets (A30), which + licenses asking first as well as proposing first. The reason to prefer proposing is practical rather than + evidenced. A proposal gives the person something concrete to react to. A blank question at the start of a task + asks them to plan work they have not seen yet. That is a judgment call, not a finding. +- **Rests on:** (A30, A31, A48) +- **Evidence status:** corroborated for the commitment claim, uncorroborated for the review-quality claim, and the + choice over asking first is reasoned rather than evidenced + +### O3: A bounded whole artifact, reviewed in one piece + +- **What it is:** Cap the work at something short enough to review entire, then review all of it rather than parts. +- **Trade-offs:** Directly addresses the risk that reviewing parts gives good feedback on a piece while missing whether + it fits. Amazon's six-page narrative is the documented instance, and two of your own skills already work this way + (A25, A51, A52). Against it: one documented external instance only, and it needs a hard length cap that long-running + work cannot honor. +- **Rests on:** (A25, A51, A52) +- **Evidence status:** single-source externally, corroborated by two in-repo skills + +### O4: Fixed-cadence stops, decoupled from the work's shape + +- **What it is:** Stop on a rhythm rather than at a content boundary, reviewing whatever exists at that point. +- **Trade-offs:** Two independent practitioner sources recommend frequent regular critique over one large review (A1, + A2). It also sidesteps defining a unit at all, which is attractive for open-ended work. Against it: a cadence rule + says nothing about what should be ready at each stop, so it needs pairing with a content rule. The sources describing + it were describing visual design critique, not this. And the supporting consulting material is the weakest evidence + in the report (A27, A28). +- **Rests on:** (A1, A2, A27, A28) +- **Evidence status:** corroborated for the cadence claim in its original domain, uncorroborated for transfer to this one + +### O5: Scale the stop to how reversible the work is + +- **What it is:** Stop and hand control back for choices that are expensive to undo. Keep going through ones you can + walk back cheaply. +- **Trade-offs:** The best-corroborated guidance about decisions rather than artifacts (A6), and it directly answers the + interruption cost, since it spends your attention where reversal is expensive (A40, A43). Against it: it calibrates + how much scrutiny, not where the boundary falls, so it cannot stand alone. +- **Rests on:** (A6, A40, A43) +- **Evidence status:** corroborated + +### O6: Build the walkthrough for checking, not for convincing + +- **What it is:** Present concrete checkable claims and what changed, keep the reasoning available but not front-loaded, + and give the reviewer something to form a view on before they meet the case for the work. +- **Trade-offs:** Backed by two controlled studies rather than by practice or analogy (A32, A33), and it directly + counters the habituation risk that motivated the question (A29). Three costs. The study measuring the effective + version also measured reduced reviewer satisfaction, so this makes the loop less pleasant on purpose (A33). It is + orthogonal to boundary placement rather than an alternative to it. And its two supporting studies come from the same + research conversation about over-reliance and explanation, published in the same venue, with one explicitly reframing + the other's line of findings. So they are not independent in the way this report demands elsewhere. +- **Rests on:** (A29, A32, A33, A35) +- **Evidence status:** corroborated, with the caveat that A32 and A33 share a research lineage; A35's only stated + corroboration is those same two, and A29 supports the general habituation mechanism rather than this specific claim + +### O7: Bounded rounds with a stop rule that is computed rather than judged + +- **What it is:** Work proceeds in batches. After each one, findings are classified and counted, and a fixed rule + decides whether another round happens. Two skills in this repository already run this shape (A53, A54). +- **Trade-offs:** It is the only pattern here where "are we done" has an answer nobody has to argue about, which is a + direct guard against the loop running until someone gets tired. It is also proven in this codebase rather than + borrowed. Against it: it needs a countable signal to gate on, and the two skills using it have one because their + rounds produce findings that can be counted and graded. Work being built rather than reviewed produces no such + signal, so this pattern has nothing to compute over in the case this research serves. +- **Rests on:** (A53, A54) +- **Evidence status:** corroborated in the codebase; no external source supports transferring it to production work + +### O8: No chunk structure at all for open-ended work + +- **What it is:** For work with no backing discipline, drop the loop and simply converse, stopping wherever the + conversation naturally does. +- **Trade-offs:** This deserves naming precisely because the report found no evidence for any unit in open-ended work. + Imposing a structure the literature does not support is a real risk, and conversation is the honest default when + nothing is known. Against it: the interruption and fatigue evidence cuts both ways, and an unstructured conversation + has no defense against the failure the whole loop exists to prevent (A29, A43). That failure is a large amount of + work arriving at once, with the person nodding through it. It also gives the person nothing to redirect early. +- **Rests on:** (A29, A43), and the absence of evidence for any alternative in this case +- **Evidence status:** no evidence either way; named here so the choice of O2 for this case reads as deliberate + +## Recommendation + +- **Recommendation:** A composite of O1, O2, O5, and O6. No single option answers the question, and the evidence + supports each of these four on a different axis: O1 sets where the boundary falls, O2 sets who chooses it, O5 sets how + hard to stop, and O6 sets what happens at the stop. O3 and O4 are not recommended, for reasons below. + +- **Evidence basis:** O1 rests on the strongest corroboration in the report, four independent directions converging on + staging by concern with structure before surface (A16, A17, A18, A19, A20, A13). The per-kind units are more uneven. + One decision per record is well corroborated (A10, A11). The prose unit is weaker and should be treated that way. + The editorial evidence establishes the order of concerns but assumes a finished draft. Staging by fidelity keeps that + order while dropping the precondition, resting on two further sources about when feedback can still change something + (A13, A22). No single source documents that as a practice. For open-ended work no source defines a unit at all, which + is why O2 carries that case. + + O2 rests on goal-setting research showing a stated rationale closes most of the gap between an imposed and a + negotiated plan (A30, A31). It also rests on an existing skill in this repository that already surfaces open items + one at a time, for the stated reason that each answer reshapes the ones behind it (A48). The claim that negotiation + improves review quality is **not** evidenced and is not part of the basis. + + O5 rests on the reversibility framework, corroborated by an independent secondary source (A6), and answers the + measured interruption cost of stopping (A40). + + O6 rests on two controlled studies (A32, A33), reinforced by the mechanism behind them (A35) and by the habituation + review that motivated the question (A29). Adversarial validation established that those two studies are not + independent of each other. They belong to the same research conversation about over-reliance and explanation, in the + same venue, with one reframing the other's line of findings. This report demands independence elsewhere, so it has to + concede the shortfall here. O6 is well evidenced by controlled experiment and thinly corroborated, which is a + different thing from the four-directional support behind O1. Discounting both studies would leave O6 with only the + general habituation literature, which is about a different question, and the recommendation would lose it. + + Carrying feedback into a written record rather than the assistant's memory rests on an analogy from an adjacent domain + with strong numbers: 6 percent against 23 percent missed steps (A41). It also rests on mature professional convention + (A42) and an existing convention in this repository (A47). It is analogy rather than direct measurement, and it is + corroborated well enough to act on. + + **Why not the others.** O3 reviews a bounded whole, which needs the artifact to exist before review starts and so + conflicts with the loop's premise that work arrives in pieces. It stays worth knowing because one skill in this + repository runs that way. It also names a real risk the composite has to answer: parts reviewed in isolation + can each look right while the whole does not (A25, A51). + + O4 is the weakest-evidenced option, its supporting sources describe a different domain, and a cadence rule alone + never says what should be ready at the stop. + + O7 needs a countable signal to gate on, and work being built produces none. Its idea of a stop rule nobody argues + about is worth borrowing, though, if a countable signal ever appears. + + O8 is the honest default for open-ended work, given that no evidence supports any unit there. O2 is preferred over + it only because a proposed plan gives the person something to redirect before the work exists, which O8 cannot offer. + + **What is not settled.** Three gaps are real and none of them is papered over above. No source documents splitting a + decision's problem, options, and choice into separate review checkpoints, so that staging is an extension rather than + a practice. No study compares review care at a negotiated checkpoint against an imposed one. No study compares review + degradation with and without an objective gate, which matters here precisely because non-code work has no test suite. + And no source anywhere describes this exact situation, an assistant building work with a person across many stops. + Every source describes either a human reviewing a mostly-finished artifact or a person consulting an assistant once. + +## Validation + +### V1: The prose unit needed the very precondition used to reject a competing option + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Compared the loop's premise that work arrives in pieces against O1's original prose unit, one + concern pass over the whole draft, and against the stated reason for rejecting O3. Editorial staging assumes a + finished draft, so the first chunk would have been "write the entire draft," which is O3 in substance. +- **Result:** Confirmed. This was the report's sharpest internal contradiction. +- **Impact:** The largest change here. The prose unit is now one rung of a fidelity ladder, which keeps the order of + concerns the editorial evidence establishes while dropping the finished-draft precondition, resting on A13 and A22. + Its evidence status now says plainly that no single source documents this as a practice. + +### V2: A skill was described as running stop-free when it has a mid-draft gate + +- **Strategy:** Challenge the Evidence +- **Investigation:** Read the coding-standard skill in full. Its drafting step stops to propose the file globs the + standard will govern and states it will "not write the file until the user confirms or proposes a substitute." A + search of the documentation skill confirmed its two operator questions sit in the opening step, before drafting. +- **Result:** Refuted, as originally written. +- **Impact:** The in-repo precedent section and A52 are corrected. One skill runs stop-free after its opening; the other + has a single mid-draft gate on an expensive-to-reverse choice. The argument against O3 now cites the one skill that + supports it. + +### V3: A third in-repo pattern was gathered as evidence and never used + +- **Strategy:** Challenge the Options Framing +- **Investigation:** Two source entries documented bounded review rounds with a stop rule computed from finding counts + and severities, and neither appeared anywhere outside the sources table. That pattern is neither one-unit-per-turn + nor whole-artifact-then-review. +- **Result:** Confirmed. +- **Impact:** Added as O7, and the in-repo section now describes three patterns rather than two. O7 is not recommended, + because it needs a countable signal to gate on and work being built produces none. + +### V4: The two studies behind the walkthrough finding share a lineage + +- **Strategy:** Challenge the Evidence-Gathering Integrity +- **Investigation:** The report applies independence scrutiny rigorously to the staging finding and flags shared data + lineage elsewhere. It does not apply that scrutiny to A32 and A33, which sit in the same research conversation and + venue, with one reframing the other's line of findings. +- **Result:** Confirmed. +- **Impact:** O6's evidence status and the recommendation's evidence basis now carry the caveat, and the claim that it + was the only option with a controlled study behind it is gone. + +### V5: Losing those two studies would cost the walkthrough finding + +- **Strategy:** Challenge the Recommendation +- **Investigation:** Traced O6's supporting sources. One of the four has no corroboration beyond those same two studies, + and the fourth supports general habituation rather than this specific claim. +- **Result:** Confirmed. +- **Impact:** The recommendation now states this sensitivity outright rather than leaving a reader to discover it. + +### V6: Two smaller citation errors + +- **Strategy:** Challenge the Evidence +- **Investigation:** The cited line range for the test-driven cycle did not contain the "cross the item off" language, + which sits about 65 lines later. A separate count of skills using one unit per turn did not reconcile against the + escalation rule's own list of consumers. +- **Result:** Partially Refuted on the first, since the claim was true of the skill but the range was wrong. +- **Impact:** The line range is corrected. The count is removed rather than fixed, following this repository's + convention of describing sets completely instead of stating running totals. + +### V7: Two viable alternatives were never named + +- **Strategy:** Challenge the Options Framing +- **Investigation:** Checked whether "no chunk structure at all for open-ended work" and "ask the person where to stop + rather than proposing a plan" appeared anywhere. Neither did, despite the report conceding it found no evidence for + any unit in open-ended work. +- **Result:** Confirmed. +- **Impact:** The first is added as O8 and dismissed with a stated reason. The second is addressed inside O2, which now + says plainly that preferring a proposal over a question is a judgment call rather than a finding. + +### V8: Single-sourced material stayed out of the recommendation + +- **Strategy:** Challenge the Evidence-Gathering Integrity +- **Investigation:** Enumerated every artifact flagged single-source and cross-referenced against each recommended + option. O1, O2, and O6 contain none. O5 loses only the interruption-cost study. +- **Result:** Confirmed, in the report's favor. +- **Impact:** No change. The recommended composite does not depend on any single-sourced external claim, though this + does not offset the lineage problem in V4, which is a different failure mode. + +### V9: A weak retrieval did not affect the headline finding + +- **Strategy:** Challenge the Evidence-Gathering Integrity +- **Investigation:** One editorial body's page was retrieved through search snippets after an HTTP 403. Checked whether + removing it collapses the four-directional support behind the staging finding. It does not: a second professional + body, a practitioner account, and two composition studies remain, still spanning practice and research. +- **Result:** Confirmed, in the report's favor. +- **Impact:** No change. + +### Adjustments Made + +Validation changed the report substantially. The prose unit was rewritten from a pass over a finished draft to a rung of +a fidelity ladder, which was the only way to make it compatible with the loop it serves (V1). The in-repo precedent +section was corrected and expanded from two patterns to three (V2, V3). O7 and O8 were added, and O2 now addresses the +alternative it beats on judgment rather than evidence (V3, V7). O6's evidence claim was softened to admit its two +studies share a lineage, and the recommendation now states what discounting them would cost (V4, V5). One citation range +was corrected and one count removed (V6). + +The recommendation survived, but the prose half of O1 did not survive in its original form. + +### Confidence Assessment + +- **Confidence:** High for staging by concern, Medium for the per-kind units, Low for open-ended work +- **Remaining Risks:** The rating splits three ways because the evidence does. + + Staging by concern, structure before surface, is High. Four independent directions support it: two national editing + bodies, a practitioner account, two peer-reviewed composition studies, and design practice in an unrelated field + reaching the same conclusion (A13, A16, A17, A18, A19, A20). Validation attacked it and it held. + + The per-kind units are Medium, and unevenly so. One decision per record is well corroborated (A10, A11). The prose + unit is a reconciliation this report performed rather than a practice any source documents, and after V1 it says so. + If that reconciliation is wrong, prose work has no evidenced unit either. + + Open-ended work is Low, and honestly so. No source describes a unit for it, which is why the recommendation falls back + to a negotiated plan and why O8 is named rather than buried. + + Three gaps stay open and none is closed by this report. No source documents splitting a decision into separate review + checkpoints. No study compares review care at a negotiated checkpoint against an imposed one. No study compares review + degradation with and without an objective gate, which matters most here, because non-code work is exactly the case + with no test suite to fall back on. + + One process caveat. The validator could not fetch web pages, so all 43 external artifacts rest on the research agents' + reporting rather than independent confirmation. The codebase artifacts were checked directly against the files, and + two of them were wrong, which is why V2 and V6 exist. + +## Sources + +| ID | Source | Link / location | Retrieved | Trust class | Summary (one line) | Evidence status | +| --- | ------ | --------------- | --------- | ----------- | ------------------ | --------------- | +| A1 | NN/g: Design Critiques | https://www.nngroup.com/articles/design-critiques/ | 2026-08-13 | web | Critique is narrowly scoped, frequent, works at any fidelity, and is distinct from approval. | corroborated by A2 | +| A2 | Berkun: How To Run a Design Critique | https://scottberkun.com/essays/23-how-to-run-a-design-critique/ | 2026-08-13 | web | Three or four specific questions per session; weekly cadence; critique informs rather than authorizes. | corroborated by A1 | +| A3 | Rust RFC process | https://rust-lang.github.io/rfcs/0002-rfc-process.html | 2026-08-13 | web | No size threshold and no splitting guidance; a negative result also true of Python's process. | single source (negative result) | +| A4 | Boehm cost-of-change data | https://reworkcost.com/boehm-cost-of-change-curve | 2026-08-13 | web | Cost to fix rose from 1x at requirements to 50-200x in production; 2001 revision found 1:5 to 1:20 for iterative teams. | corroborated by A5 | +| A5 | Mountain Goat: cost-of-change curve | https://www.mountaingoatsoftware.com/blog/the-cost-of-change-curve-is-outdated | 2026-08-13 | web | Direction holds, magnitude flattened; feedback delay now dominates. | corroborated by A4, same data lineage | +| A6 | Amazon one-way/two-way doors | https://aws.amazon.com/executive-insights/content/how-amazon-defines-and-operationalizes-a-day-1-culture/ | 2026-08-13 | web | Irreversible decisions get slow wide review; reversible ones get fast review by a small group. | corroborated by an independent secondary source | +| A7 | LeanIX: architecture review boards | https://www.leanix.net/en/wiki/ea/architecture-review-board | 2026-08-13 | web | Boards review whole proposals gated by cost and impact; no sizing metric given. | single source (caveated, vendor) | +| A8 | Ubl: Design Docs at Google | https://www.industrialempathy.com/posts/design-docs-at-google/ | 2026-08-13 | web | 10-20 pages for a large design doc, 1-3 for a small one, split when it outgrows itself. | single source (caveated) on the figures | +| A9 | Google Research: Improving Design Reviews | https://research.google/pubs/improving-design-reviews-at-google/ | 2026-08-13 | web | 25% reduction in median approval time across 141,652 documents; review latency is a measured cost. | single source, abstract only | +| A10 | Nygard: Documenting Architecture Decisions | https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions | 2026-08-13 | web | "One ADR describes one significant decision"; five-part structure, one to two pages. | corroborated by A11 | +| A11 | adr.github.io | https://adr.github.io/ | 2026-08-13 | web | "Captures a single AD and its rationale"; same unit, independently maintained. | corroborated by A10 | +| A12 | Calçado: A Structured RFC Process | https://philcalcado.com/2018/11/19/a_structured_rfc_process.html | 2026-08-13 | web | Widening-circle review over fixed size gates; "the more polished a document looks, the softer reviews tend to be". | corroborated cross-domain by A13 | +| A13 | Buxton fidelity principle, via Whatley | https://www.simonwhatley.co.uk/writing/low-fidelity-design-gets-high-level-feedback-high-fidelity-designs-get-low-level-feedback/ | 2026-08-13 | web | Low-fidelity work draws structural feedback; high-fidelity draws cosmetic; people won't criticize what looks finished. | corroborated cross-domain by A12 | +| A14 | Double Diamond design model | https://en.wikipedia.org/wiki/Double_Diamond_(design_process_model) | 2026-08-13 | web | Four stages as two diverge-converge cycles, problem space then solution space; not tied to review triggers. | single source (caveated, tertiary) | +| A15 | Increment: Planning with RFCs | https://increment.com/planning/planning-with-requests-for-comments/ | 2026-08-13 | web | RFC templates add estimated size and definition of done; cadence needs deliberate infrastructure. | single source (caveated) | +| A16 | Editorial Freelancers Association | https://www.the-efa.org/editorial-services-definitions/ | 2026-08-13 | web | Four editing levels in fixed order: developmental, line, copy, proofread. | corroborated by A17, A18, A19, A20 | +| A17 | CIEP editorial stage definitions | https://www.ciep.uk/resource/what-is-the-difference-between-copyediting-and-proofreading.html | 2026-08-13 | web | Same three-stage order from an independent national body; retrieved via search snippets after HTTP 403. | corroborated by A16 | +| A18 | Sommers 1980, CCC 31(4) | https://eric.ed.gov/?id=EJ240356 | 2026-08-13 | web | Students revise by rewording; experienced writers revise recursively for meaning and structure. | corroborated by A19 | +| A19 | Faigley & Witte 1981, CCC 32(4) | https://scholarsarchive.byu.edu/cgi/viewcontent.cgi?article=1016&context=journalrw | 2026-08-13 | web | Meaning changes versus surface changes; experienced writers make meaning changes more often. Read via secondary summary. | corroborated by A18 | +| A20 | The Expert Editor: edit types | https://experteditor.com.au/article/copyedit-vs-proofread-vs-structural-edit-which-your-draft-actually-needs/ | 2026-08-13 | web | "Effort spent decorating rooms that are about to be knocked through." | corroborated by A16, A17 | +| A21 | GMU Writing Center: Reverse Outlining | https://writingcenter.gmu.edu/writing-resources/writing-as-process/reverse-outlining | 2026-08-13 | web | Distill each paragraph to its main idea to check structure before sentence-level revision. | corroborated by A22 | +| A22 | UNC Writing Center: Getting Feedback | https://writingcenter.unc.edu/tips-and-tools/getting-feedback/ | 2026-08-13 | web | Early feedback changes foundations; late feedback is limited to surface concerns. Share often. | corroborated by A21 | +| A23 | Workshop models: Iowa and Lerman | https://writers.com/how-to-workshop-creative-writing | 2026-08-13 | web | Iowa gag rule; Lerman sequences what's working, author questions, neutral questions, then opinions with permission. | corroborated by an independent practitioner account | +| A24 | Fiction Foundry workshop guidelines | https://fictionfoundry.alumni.columbia.edu/workshop_manuscript_guidelines | 2026-08-13 | web | 2,500-5,000 words per manuscript, six per session, advance written critiques. | single source (caveated) | +| A25 | Amazon PR/FAQ process | https://workingbackwards.com/concepts/working-backwards-pr-faq-process/ | 2026-08-13 | web | Six-page cap, read in silence as a whole, deliberately not circulated in pieces. | single source (caveated) | +| A26 | Minto Pyramid Principle | https://slideworks.io/resources/the-pyramid-principle-mckinsey-toolbox-with-examples | 2026-08-13 | web | Conclusion first, then arguments, then evidence; document structure rather than review cadence. | single source (caveated) | +| A27 | Umbrex: hypothesis-driven problem solving | https://umbrex.com/resources/frameworks/strategy-frameworks/hypothesis-driven-problem-solving/ | 2026-08-13 | web | Weekly or biweekly sprints with a 30-60 minute synthesis checkpoint and a living hypothesis board. | single source (caveated) | +| A28 | Cooper Stage-Gate process | https://www.toolshero.com/innovation/stage-gate-process/ | 2026-08-13 | web | Stages separated by go/kill/hold/recycle gates; physical product development, not knowledge work. | single source (caveated, adjacent domain) | +| A29 | Parasuraman & Manzey: Complacency and Bias | https://pmc.ncbi.nlm.nih.gov/articles/PMC3240751/ | 2026-08-13 | web | Erroneous advice raised incorrect-decision risk 26%; complacency rises with highly-but-imperfectly reliable systems. | corroborated by A38, A39 | +| A30 | Locke & Latham 2019 retrospective | https://www.decisionskills.com/uploads/5/1/6/0/5160560/locke_latham_2019_the_development_of_goal_setting_theory_50_years.pdf | 2026-08-13 | web | With difficulty held constant, participative and assigned goals perform alike; rationale closes the commitment gap. | corroborated by A31 | +| A31 | Latham & Yukl 1975 | https://web.mit.edu/curhan/www/docs/Articles/15341_Readings/Group_Performance/Latham%20and%20Yukl%20-%201975%20-%20Assigned%20versus%20participative%20goal%20setting%20with%20ed.pdf | 2026-08-13 | web | Participative goal-setting raised productivity because the goals set were harder, not because of participation. | corroborated by A30, read via secondary summary | +| A32 | Vasconcelos et al. 2023, CSCW | https://arxiv.org/abs/2212.06823 | 2026-08-13 | web | Five studies, 731 participants: explanations reduce overreliance only when they lower verification cost. | corroborated by A33, A35 | +| A33 | Buçinca et al. 2021, CSCW | https://arxiv.org/abs/2102.09692 | 2026-08-13 | web | Passive explanations do not reduce overreliance and can increase it; forcing the reviewer to judge first does, at a satisfaction cost. | corroborated by A32 | +| A34 | Zhang, Liao & Bellamy 2020, FAT* | https://dl.acm.org/doi/10.1145/3351095.3372852 | 2026-08-13 | web | Confidence scores and explanations are a weak, inconsistent lever on appropriate reliance. Abstract only; paywalled. | corroborated by A32, A33 | +| A35 | Ehsan & Riedl: explainability pitfalls | https://technologyandsociety.org/human-centricity-in-the-relationship-between-explainability-and-trust-in-ai/ | 2026-08-13 | web | Explanations signal perceived competence independent of whether their content is sound. | corroborated by A32, A33 | +| A36 | Reviewer anchoring RCT | https://arxiv.org/abs/2307.05443 | 2026-08-13 | web | 108 reviewers: no significant anchoring; reviewers revised scores once corrected material arrived. | single source (caveated), conflicts with a naive first-impression model | +| A37 | Sonar and Stack Overflow developer surveys | https://www.sonarsource.com/state-of-code-developer-survey-report.pdf | 2026-08-13 | web | 96% do not fully trust AI code; only 48% consistently verify before merging. | single source (caveated, vendor) for the figures; direction corroborated | +| A38 | Thoughtworks: complacency with AI code | https://www.thoughtworks.com/radar/techniques/complacency-with-ai-generated-code | 2026-08-13 | web | Vigilance drops after a few positive experiences; recommends anchoring review in objective gates. | corroborated by A29, A39 | +| A39 | Atomic Robot: AI review fatigue | https://atomicrobot.com/blog/ai-review-fatigue/ | 2026-08-13 | web | Vigilance decrement, automation complacency, and context-switching residue compound. | corroborated by A29 | +| A40 | Mark et al. 2008, CHI | https://ics.uci.edu/~gmark/chi08-mark.pdf | 2026-08-13 | web | Average 23 minutes 15 seconds to resume a task after interruption; faster but more stressed completion. | single source (caveated for this application) | +| A41 | Surgical checklist studies | https://www.ncbi.nlm.nih.gov/pmc/articles/PMC11536331/ | 2026-08-13 | web | Teams missed ~6% of critical steps with a checklist against ~23% from memory. | corroborated across two independent sources | +| A42 | Editorial style sheets | https://www.daniellencarter.com/post/editing-with-style-sheets | 2026-08-13 | web | A running record of editorial decisions and reasons, kept so decisions aren't re-argued or misremembered. | single source (caveated), practice broadly attested | +| A43 | Review fatigue practitioner accounts | https://hackernoon.com/the-oversight-fatigue-problem-why-hitl-breaks-down-at-scale-and-what-comes-after | 2026-08-13 | web | Review quality decays into rubber-stamping past a volume threshold; concentrate review at fewer points. | two practitioner sources converge; neither cites data | +| A44 | code-walkthrough operating principles | `han-coding/skills/code-walkthrough/SKILL.md:41-46` | n/a | codebase | "One step per turn, then stop and wait... the pacing is the deliverable." | corroborated by A46, A48 | +| A45 | walkthrough step format | `han-coding/skills/code-walkthrough/references/walkthrough-step-format.md:1-26` | n/a | codebase | A step earns its place where behavior turns: a branch, transformation, dispatch, boundary crossing, or write. | corroborated by A44 | +| A46 | operator-escalation rule | `han-planning/references/operator-escalation-rule.md:16-24` | n/a | codebase | One question per turn, stating how many are pending so the operator knows the queue depth. | corroborated by A44, A48 | +| A47 | escalation register | `han-planning/references/operator-escalation-rule.md:102-115` | n/a | codebase | Records each question as asked, the answer, and where the answer landed in the artifact. | corroborated by A49 | +| A48 | design-an-api open-item gate | `han-coding/skills/design-an-api/SKILL.md:289-307` | n/a | codebase | Open items surfaced one at a time, never batched, because each answer reshapes the ones behind it. | corroborated by A44, A46 | +| A49 | plan-a-feature decision log | `han-planning/skills/plan-a-feature/SKILL.md:110-115` | n/a | codebase | Stable decision IDs cross-referenced inline so every link keeps resolving through revisions. | corroborated by A47 | +| A50 | tdd red-green-refactor unit | `han-coding/skills/tdd/SKILL.md:126-134,199-207` | n/a | codebase | One behavior per cycle, three phases never collapsed, each closing by crossing the item off the list. | corroborated by A44 | +| A51 | project-documentation structure | `han-documentation/skills/project-documentation/SKILL.md:36-200` | n/a | codebase | Writes the complete document, then dispatches reviewers; its two operator questions sit in the opening step, before drafting. | corroborated by A52 with the difference noted | +| A52 | coding-standard structure | `han-coding/skills/coding-standard/SKILL.md:214-226,338-382` | n/a | codebase | Stops mid-draft for approval of the globs the standard governs and will not write until confirmed; the later audit is a self-check, not a gate. | contrasts with A51; corrected by validation finding V2 | +| A53 | iterative-plan-review rounds | `han-planning/skills/iterative-plan-review/SKILL.md:249-355` | n/a | codebase | Rounds capped by band, with a deterministic stop rule and findings recorded per round. | corroborated by A54 | +| A54 | plan-implementation round aggregation | `han-planning/skills/plan-implementation/references/round-aggregation.md:1-44` | n/a | codebase | Claim ledger grouping findings by category and marking each evidenced, anecdotal, disputed, or unverified. | corroborated by A53 | + +### A16: Editorial Freelancers Association service definitions — recommendation-bearing + +- **Link / location:** https://www.the-efa.org/editorial-services-definitions/ +- **Retrieved:** 2026-08-13 +- **Trust class:** web (professional association) +- **Summary:** Defines four editing levels and their order. Developmental editing restructures and reorganizes; + line editing works sentence and paragraph language and style; copyediting handles grammar, punctuation, and + consistency; proofreading catches typographical and formatting errors on near-final proofs. States that line + editing follows developmental work and proofreading comes last. This is one of the two national professional bodies + whose independent agreement anchors the staging finding. +- **Evidence status:** corroborated by A17 (a separate national body in another country), and independently by the + composition research in A18 and A19 + +### A18: Sommers, "Revision Strategies of Student Writers and Experienced Adult Writers" — recommendation-bearing + +- **Link / location:** https://eric.ed.gov/?id=EJ240356 +- **Retrieved:** 2026-08-13 +- **Trust class:** web (peer-reviewed, foundational composition-studies research) +- **Summary:** A study of 8 student writers and 7 experienced adult writers, published in College Composition and + Communication. Found that student writers treat revision as word-level rewording while experienced writers revise + recursively, focused on meaning and structure rather than working linearly by stage. This matters here because it + arrives at the structure-before-surface finding from academic research rather than professional convention, making + the agreement with A16 and A17 genuine corroboration rather than one claim repeated. +- **Evidence status:** corroborated by A19, which distinguishes meaning changes from surface changes and finds the same + split between experienced and inexperienced writers + +### A33: Buçinca, Malaya & Gajos, "To Trust or to Think" — recommendation-bearing + +- **Link / location:** https://arxiv.org/abs/2102.09692 +- **Retrieved:** 2026-08-13 +- **Trust class:** web (peer-reviewed, Proceedings of the ACM on Human-Computer Interaction) +- **Summary:** Establishes that passively presented explanations do not reliably reduce over-reliance on an assistant's + output and can increase it. The only intervention that meaningfully reduced over-reliance was a cognitive forcing + function, meaning a step that requires the person to engage actively before seeing the assistant's answer. The study + measured a real cost: lower user satisfaction. The benefit concentrated in people already inclined toward effortful + thinking. This is the study behind the recommendation that the walkthrough hand the reviewer something to check + rather than a case to agree with. +- **Evidence status:** corroborated by A32, which independently finds the effect of explanations on reliance is + conditional rather than uniformly protective + +### A32: Vasconcelos et al., "Explanations Can Reduce Overreliance on AI Systems" — recommendation-bearing + +- **Link / location:** https://arxiv.org/abs/2212.06823 +- **Retrieved:** 2026-08-13 +- **Trust class:** web (peer-reviewed, Proceedings of the ACM on Human-Computer Interaction) +- **Summary:** Five studies with 731 participants. Reframes earlier null findings: explanations reduce over-reliance + specifically when they lower the cost of checking a claim independently. On hard tasks people engage more carefully + with explanations, but explanations that are harder to parse increase over-reliance because they raise verification + cost. A financial incentive to verify reduced blind acceptance. This is the source for the design consequence that a + walkthrough should carry concrete checkable claims rather than a fluent narrative. +- **Evidence status:** corroborated by A33 and A35 + +### A6: Amazon's one-way and two-way door framework — recommendation-bearing + +- **Link / location:** https://aws.amazon.com/executive-insights/content/how-amazon-defines-and-operationalizes-a-day-1-culture/ +- **Retrieved:** 2026-08-13 +- **Trust class:** web (the organization's own account of its internal framework) +- **Summary:** Separates decisions by reversibility. Irreversible, high-consequence decisions warrant slow, deliberate, + widely consulted review. Reversible, low-cost-of-being-wrong decisions should be made quickly by a small group or a + single person with good judgment. This is the best-corroborated guidance found about calibrating review effort to a + decision rather than to an artifact. It is what lets the loop spend the operator's attention where reversal is + expensive, instead of stopping uniformly. +- **Evidence status:** corroborated by independent secondary sources describing the framework identically + +### A48: Han's design-an-api open-item gate — recommendation-bearing + +- **Link / location:** `han-coding/skills/design-an-api/SKILL.md:289-307` +- **Retrieved:** n/a +- **Trust class:** codebase (trusted current-state anchor) +- **Summary:** Surfaces open items "one at a time, each as its own `AskUserQuestion` call. Never batch them BECAUSE each + answer routinely settles or reshapes the ones behind it, and a batch asks the user to decide in an order the design + does not follow." After each answer it re-checks the remaining items, dropping settled ones and rewording changed + ones. This is the working in-repo precedent for a negotiated, adaptive sequence in decision work, and it is the + closest existing analogue to the pairing loop this research serves. +- **Evidence status:** corroborated by A44 and A46, which show the same one-unit-per-turn pattern in two other skills + +### A41: Surgical checklist studies — recommendation-bearing + +- **Link / location:** https://www.ncbi.nlm.nih.gov/pmc/articles/PMC11536331/ +- **Retrieved:** 2026-08-13 +- **Trust class:** web (peer-reviewed medical human-factors research) +- **Summary:** In simulated operating-room crisis scenarios, teams using a written checklist missed about 6 percent of + critical steps, against about 23 percent missed when working from memory. This is the strongest available empirical + anchor for the claim that an externalized written record outperforms recollection. It is domain-specific to surgical + emergency response, so its application to carrying a reviewer's feedback forward is an analogy rather than a direct + finding, and it is labeled as such wherever it is used. +- **Evidence status:** corroborated across two independent sources, applied here by analogy diff --git a/docs/skills/README.md b/docs/skills/README.md index ae0ea224..150baf25 100644 --- a/docs/skills/README.md +++ b/docs/skills/README.md @@ -61,6 +61,8 @@ skill-and-agent split is fuzzy, read [Concepts](../concepts.md) first. test plan from supplied context: named tests with by-hand steps and expected outcomes for a person to run. - [`/markdown-to-confluence`](../../han-atlassian/docs/skills/markdown-to-confluence.md) — Publish one local Markdown file to a user-specified Confluence location; defaults to an unpublished draft. +- [`/pairing`](../../han-core/docs/skills/pairing.md) — Build work collaboratively in reviewable pieces, handing each + one back before starting the next, so you steer while the work happens. - [`/plan-a-feature`](../../han-planning/docs/skills/plan-a-feature.md) — Build a feature specification from scratch through an evidence-based interview that walks the design tree and dispatches specialist reviewers. - [`/plan-a-feature-to-confluence`](../../han-atlassian/docs/skills/plan-a-feature-to-confluence.md) — Run diff --git a/docs/workflows.md b/docs/workflows.md index c4174d53..b372194e 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -34,6 +34,9 @@ flowchart TD gh --> build["/tdd"] jira --> build linear --> build + pairing["/pairing"] -.drives.-> impl + pairing -.drives.-> review + pairing -.drives.-> build ``` - **[`/issue-triage`](../han-research/docs/skills/issue-triage.md) → [`/investigate`](../han-coding/docs/skills/investigate.md).** @@ -50,6 +53,11 @@ flowchart TD where your team tracks them: [`/work-items-to-issues`](../han-github/docs/skills/work-items-to-issues.md) for GitHub, [`/work-items-to-jira`](../han-atlassian/docs/skills/work-items-to-jira.md) for Jira (opt-in `han-atlassian`), or [`/work-items-to-linear`](../han-linear/docs/skills/work-items-to-linear.md) for Linear (opt-in `han-linear`). +- **[`/pairing`](../han-core/docs/skills/pairing.md) drives + [`/plan-implementation`](../han-planning/docs/skills/plan-implementation.md) and + [`/iterative-plan-review`](../han-planning/docs/skills/iterative-plan-review.md).** Both run their rounds without + pausing today, so this is where the wrapper changes the most: you see each round as it closes rather than only the + finished plan. ## From a gap to a plan @@ -86,6 +94,9 @@ flowchart TD refactor --> tdd tdd --> prdesc["/update-pr-description"] investigate["/investigate"] --> iterate["/iterative-plan-review"] + pairing["/pairing"] -.drives.-> refactor + pairing -.drives.-> tdd + pairing -.drives.-> design ``` - **[`/code-review`](../han-coding/docs/skills/code-review.md) → @@ -108,6 +119,11 @@ flowchart TD [`/update-pr-description`](../han-github/docs/skills/update-pr-description.md).** Once the branch carries the change, turn its commits into the PR body. This is the description half of the PR; `/post-code-review-to-pr` is the review half, and the two are independent. +- **[`/pairing`](../han-core/docs/skills/pairing.md) drives + [`/refactor`](../han-coding/docs/skills/refactor.md), [`/tdd`](../han-coding/docs/skills/tdd.md), and + [`/design-an-api`](../han-coding/docs/skills/design-an-api.md).** This is not a chain but a wrapper: `/pairing` runs one + of them and takes control back at each unit boundary, so you review as the work lands rather than at the end. Invoking + any of the three directly runs it straight through, unchanged. ## Planning the tests diff --git a/han-coding/docs/skills/code-walkthrough.md b/han-coding/docs/skills/code-walkthrough.md index 83383c5b..c5b8be45 100644 --- a/han-coding/docs/skills/code-walkthrough.md +++ b/han-coding/docs/skills/code-walkthrough.md @@ -138,6 +138,9 @@ cheap and safe to run often. - [Plugin README](../../README.md). The plugin's front door: its skills, agents, and how they fit together. - [Repo root README](../../../README.md). The Han suite landing page. Start here if you arrived from outside the docs +- [`/pairing`](../../../han-core/docs/skills/pairing.md). The skill this one is most often confused with, because both + pace you through work a step at a time. This one explains code that already exists; `/pairing` builds work while + pacing you through it. tree. - [`code-overview`](./code-overview.md). The written-document counterpart. Same understanding goal, one artifact instead of a paced conversation. diff --git a/han-coding/docs/skills/design-an-api.md b/han-coding/docs/skills/design-an-api.md index 9787a98f..671708b6 100644 --- a/han-coding/docs/skills/design-an-api.md +++ b/han-coding/docs/skills/design-an-api.md @@ -154,6 +154,9 @@ oversized for shaping one contract. - [Plugin README](../../README.md). The plugin's front door: its skills, agents, and how they fit together. - [Repo root README](../../../README.md). The Han suite landing page. Start here if you arrived from outside the docs +- [`/pairing`](../../../han-core/docs/skills/pairing.md). Drive these rounds collaboratively, stopping after each one so + you review it as it lands. Invoking `/design-an-api` directly runs the rounds to completion without pausing between + them. tree. - [YAGNI](../../../docs/yagni.md). The evidence-based "You Aren't Gonna Need It" rule: the two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. diff --git a/han-coding/docs/skills/refactor.md b/han-coding/docs/skills/refactor.md index 8e6549f6..8a23f230 100644 --- a/han-coding/docs/skills/refactor.md +++ b/han-coding/docs/skills/refactor.md @@ -213,6 +213,9 @@ URL: https://arxiv.org/abs/2411.04444 - [Plugin README](../../README.md). The plugin's front door: its skills, agents, and how they fit together. - [Repo root README](../../../README.md). The Han suite landing page. Start here if you arrived from outside the docs tree. +- [`/pairing`](../../../han-core/docs/skills/pairing.md). Drive this sequence collaboratively, stopping after each named + refactoring so you review it as it lands. Invoking `/refactor` directly runs the sequence to completion without + pausing. - [Skills Index](../../../docs/skills/README.md). All skills, grouped by purpose. - [YAGNI](../../../docs/yagni.md). The evidence gate every planned refactoring passes, with the named anti-patterns and the deferral format. diff --git a/han-coding/docs/skills/tdd.md b/han-coding/docs/skills/tdd.md index 22ae45dc..76ccba58 100644 --- a/han-coding/docs/skills/tdd.md +++ b/han-coding/docs/skills/tdd.md @@ -243,6 +243,8 @@ URL: https://growing-object-oriented-software.com/ - [Plugin README](../../README.md). The plugin's front door: its skills, agents, and how they fit together. - [Repo root README](../../../README.md). The Han suite landing page. Start here if you arrived from outside the docs tree. +- [`/pairing`](../../../han-core/docs/skills/pairing.md). Drive this loop collaboratively, stopping after each behavior + so you review it as it lands. Invoking `/tdd` directly runs the loop to completion without pausing. - [Skills Index](../../../docs/skills/README.md). All skills, grouped by purpose. - [YAGNI](../../../docs/yagni.md). The evidence-based "You Aren't Gonna Need It" rule the refactor step and test list apply. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. diff --git a/han-coding/references/collaborative-stop-rule.md b/han-coding/references/collaborative-stop-rule.md new file mode 100644 index 00000000..d9cbc7a7 --- /dev/null +++ b/han-coding/references/collaborative-stop-rule.md @@ -0,0 +1,127 @@ +# Collaborative Stop Rule (Handing Control Back Mid-Run) + +This rule defines what happens when a skill running collaboratively reaches a unit boundary: how it knows to stop, what +it presents when it stops, and what it does with the answer. It exists so a stop means the same thing whichever skill +performed it. + +Six places need to agree on that answer. `pairing` drives the loop, and `tdd`, `refactor`, `design-an-api`, +`iterative-plan-review`, and `plan-implementation` each stop at a boundary they already have. Without one shared +definition, each would describe stopping in its own words and a person would meet six slightly different experiences. +Every vendored copy of this file is byte-identical to the canonical `han-core/references/collaborative-stop-rule.md`. + +## Who reads this + +Two kinds of reader, needing different parts. + +**A skill that gains the collaborative flag** reads "Detecting the flag" and "What a stop presents." Those two sections +are the whole contract for a backing skill. Nothing else here is required reading to add the flag correctly. + +**The skill driving the loop** reads all of it, because it also owns the plan, the record, and the sorting of work that +has no backing skill at all. + +## Detecting the flag + +The collaborative flag arrives as a named argument on the invocation, never as a caller's identity. A skill supporting +it declares the argument in frontmatter and branches on its value at the boundary the skill already has. + +Never make a skill test which skill invoked it. A skill that names its caller breaks when the caller is renamed, and it +cannot be driven collaboratively by anything else later. The argument form carries the same information without the +coupling. + +Never let the flag change anything except what happens at an existing boundary. It adds no new boundary, skips no step, +and relaxes no gate the skill already enforces. An invocation without the flag behaves exactly as it does today, which +is what makes the flag safe to add to a skill people already rely on. + +## What a stop presents + +A stop hands the person something to check, not a case for the work. That ordering is the point of the whole +convention: a fluent explanation raises agreement without raising scrutiny, so leading with the reasoning defeats the +review the stop exists to get. + +Every stop carries four things, in this order: + +1. **Position.** Which piece this is against the plan, and what remains. A person deciding whether they have the + attention for two more pieces cannot answer that without it. +2. **What was built or found.** The unit that just closed, named in the terms that skill already uses. +3. **What can be checked.** The specific claims the person can verify. For work that produces an artifact, these are + properties of the artifact. For a review round, the findings themselves are the checkable claims, and the plan edits + the round made are what changed. +4. **What changed.** Since the previous stop, not since the beginning. + +The reasoning behind the choices comes last or not at all. State in one line that it is available for the asking, and +stop there BECAUSE an unannounced affordance in a conversation is the same as no affordance, while a volunteered +rationale is the thing that suppresses scrutiny. + +Then end the turn. Nothing further is built until the person responds. + +That last instruction is a directive, not a guarantee. Nothing in the platform enforces it. When a run does build past a +stop, the next thing it says names the overrun, states which pieces went unreviewed, and offers to walk back through +them. Never present unreviewed work as though it had been approved. + +## Asking before building, and when + +For a piece carrying a choice that is expensive to walk back, the ask comes **before** the build, not at the stop +afterward. Committing to your own expectation before the answer exists is the mechanism; an ask arriving once the work +is on disk collects the cost and none of the benefit. + +**The test.** A choice is expensive to walk back when later pieces in the plan would have to be redone to undo it. Apply +it against the plan you already proposed, which lists the pieces, so the question is answerable rather than a matter of +taste. + +Three consequences follow from that test and are part of it: + +- Most plans mark one piece, sometimes two. A piece nothing else depends on is cheap to redo by definition. +- A plan that marks every piece has misapplied the test. Stop and re-derive it rather than asking at every stop, which + is the outcome this calibration exists to avoid. +- A plan that marks nothing is the normal case for short work with independent pieces. Do not manufacture a marking to + fill the slot. + +This criterion is authored here rather than drawn from a source. The framework behind it separates reversible from +irreversible decisions and prescribes different review depth for each, but supplies no way to tell them apart. Treat the +test as provisional and revisit it once real runs show whether it marks the pieces people find expensive. + +**The ask itself** names the dimension the choice turns on and stops there. Do not pose a blank question, and do not +offer candidate answers, BECAUSE named candidates anchor the guess and the point is an independent read. + +**Declining is a first-class answer.** "I don't know" and "just show me" advance the piece exactly as a considered +answer does. Never re-prompt, and never require an answer before building. + +**After the build, the reveal is an ordinary stop.** It does not restate the person's read, score it, or defend a +divergence from it. A stop that grades you teaches you to answer noncommittally, and a stop that argues with you leads +with the reasoning this convention keeps out of the lead. + +## Recording what the person says + +Write every piece of feedback into the running record before acting on it. A correction given at the second stop has to +still apply at the seventh, and mid-context material is the least reliably recalled. + +The person can read the record whenever they ask. When a recorded entry shapes a later piece, name which entry it was, +so a misrecorded correction surfaces while it is still cheap to fix rather than quietly governing the rest of the +session. + +## Acting on the answer + +Three routes, by what the feedback touches. + +**The piece in hand.** Fix it within that piece and show it again. The re-show names the correction applied and what it +touched before restating the piece. It is a stop like any other, so end the turn and wait rather than moving on. + +**What comes next.** Carry it into the next piece. + +**Work outside the piece in hand.** Say so before acting: name that the feedback looks like it reaches past this piece, +and what it would change about the plan. Then offer three ways out, never two. The person accepts a revised plan, +changes it, or declines the reopening entirely, in which case the feedback is recorded as scoped to later work and the +agreed plan continues. The third exit is what keeps an offhand remark from silently replacing a plan the person agreed +to. + +## Pace + +Honor a request for more than one piece as asked, then return to the normal pace at the following stop without being +asked to. Without that middle gear the only choices are full ceremony on every piece or no review at all, and the second +is what the loop exists to prevent. + +Add no pressure to comment. A run of silent approvals is a valid response and means nothing in particular; do not +volunteer anything in reply to it. + +Ending the loop is the person's call. Nothing here computes a stopping point, because work being built produces no +countable signal to compute over. diff --git a/han-coding/skills/code-walkthrough/SKILL.md b/han-coding/skills/code-walkthrough/SKILL.md index fa8fa662..fe98d472 100644 --- a/han-coding/skills/code-walkthrough/SKILL.md +++ b/han-coding/skills/code-walkthrough/SKILL.md @@ -1,15 +1,14 @@ --- name: code-walkthrough description: > - Walks a person through a set of code changes one step at a time in conversation, starting at the entry point and - following the flow that changes, showing a small chunk of code per step and explaining it in plain language so they - learn what it does and why. Defaults to the current branch's changes, and walks the code from the perspective of any - context provided instead — a file, directory, symbol, pull request, plan, or ticket. Use when someone wants to be - walked through, taught, paced through, or shown around code or a branch step by step, or to learn how a change works - before reviewing or extending it. Stops after every step and waits, so the learner sets the pace and can ask questions - as they go. Writes no files and changes no code. Does not produce a written overview document to read alone — use - code-overview. Does not review code quality or raise findings — use code-review. Does not diagnose bugs or root-cause - failures — use investigate. + Walks a person through code changes one step at a time in conversation, starting at the entry point and following the + flow that changes, showing a small chunk per step and explaining it in plain language. Defaults to the current + branch's changes, and walks the code from the perspective of any context provided instead — a file, directory, + symbol, pull request, plan, or ticket. Use when someone wants to be walked through, taught, paced through, or shown + around code or a branch step by step, or to learn how a change works before reviewing or extending it. Stops after + every step and waits, so the learner sets the pace. Paces through code that already exists and builds nothing — to + build new work while being paced through it, use pairing. Does not produce a written overview to read alone — use + code-overview. Does not review code quality — use code-review. Does not diagnose bugs — use investigate. arguments: size argument-hint: "[size: small | medium | large | dynamic] [target: a file, directory, symbol, PR reference, or plan — defaults to the diff --git a/han-coding/skills/design-an-api/SKILL.md b/han-coding/skills/design-an-api/SKILL.md index 8b25c234..dd5173e0 100644 --- a/han-coding/skills/design-an-api/SKILL.md +++ b/han-coding/skills/design-an-api/SKILL.md @@ -8,7 +8,8 @@ description: > API change for a capability you can already describe, sized for roughly one pull request. Produces a design document and changes no code. Does not specify what a feature should do — use plan-a-feature. Does not plan delivery or sequencing — use plan-implementation. Does not assess the architecture of existing code — use - architectural-analysis. Does not write the code — use tdd. Does not restructure existing code — use refactor. + architectural-analysis. Does not write the code — use tdd. Does not restructure existing code — use refactor. Runs its rounds without + pausing for review; to review each round as it lands, use pairing. arguments: size argument-hint: "[size: small | medium | large | dynamic] [the goal or ticket this serves, and the interface to design]" @@ -200,6 +201,14 @@ State git availability in the same message if git is absent. Proceed without a b read-only and re-runnable, so a gate here would gate a reversible operation. If the user objects to the roster, honor the adjustment. +**Running collaboratively.** When the request asks to review each round as it closes as it lands, which is what +`pairing` does when it hands work here, stop at this point and hand control back instead of continuing. Present the stop +in the shape [collaborative-stop-rule.md](../../references/collaborative-stop-rule.md) specifies. Absent such a request, +continue as below; an ordinary invocation is unchanged. + +For this skill a round is one dispatch step: the discovery wave, the options round, the question round, and the +validation round. The two human gates below are unchanged and still fire regardless. + ## Step 4: Dispatch the Discovery Wave and Write the Context Brief Launch `han-core:codebase-explorer` and every signalled specialist in a single message with one `Agent` call per agent diff --git a/han-coding/skills/refactor/SKILL.md b/han-coding/skills/refactor/SKILL.md index 1eb22ff1..533f6c45 100644 --- a/han-coding/skills/refactor/SKILL.md +++ b/han-coding/skills/refactor/SKILL.md @@ -7,7 +7,8 @@ description: > of existing code, or to apply refactoring recommendations from a code-review or architectural-analysis report. This skill changes code; it does not review code (use code-review), assess architecture (use architectural-analysis), or build new behavior test-first (use tdd). Do not use it on code inside an active tdd loop; the refactor step of tdd - owns that cleanup. + owns that cleanup. Runs its planned sequence to completion without pausing for review; to review each named + refactoring as it lands, use pairing. argument-hint: "[file, module, named smell, or a path to review findings]" allowed-tools: Read, Write, Edit, Glob, Grep, Bash(git *), Bash(find *), Bash(npm *), Bash(npx *), Bash(pnpm *), Bash(yarn *), @@ -130,6 +131,12 @@ Take the plan items in order. For each: 2. **Run the full suite** (and the type-check command where one was resolved). **Paste the runner's summary line.** Paste full output only when something fails or looks unexpected. 3. **Green: cross the item off** and move to the next. + + **Running collaboratively.** When the request asks to review each named refactoring as it lands, which is what + `pairing` does when it hands work here, stop at this point and hand control back instead of continuing. Present the + stop in the shape [collaborative-stop-rule.md](../../references/collaborative-stop-rule.md) specifies. Absent such a + request, continue as below; an ordinary invocation is unchanged. + 4. **Red: revert this step.** When git is available and the tree was clean at start, `git checkout`/`git restore` the touched files. When git is absent, or the tree was already dirty at start, undo the edits directly instead, so reverting this step does not discard the user's other work. Do not patch forward over a red suite; a failed step diff --git a/han-coding/skills/tdd/SKILL.md b/han-coding/skills/tdd/SKILL.md index 634d02a0..dd7c8baa 100644 --- a/han-coding/skills/tdd/SKILL.md +++ b/han-coding/skills/tdd/SKILL.md @@ -8,7 +8,8 @@ description: > leading. This skill writes and changes code; it does not produce a test plan document (use automated-test-planning, or manual-test-planning for a plan a person runs by hand), review or audit existing code (use code-review), restructure existing code outside a TDD loop (use refactor), specify what a - feature should do (use plan-a-feature), or find the root cause of a bug (use investigate). + feature should do (use plan-a-feature), or find the root cause of a bug (use investigate). Runs its loop to + completion without pausing for review; to review each behavior as it lands, use pairing. argument-hint: "[what to build, a behavior to drive, or a path to a spec/plan]" allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(git *), Bash(find *), Bash(npm *), Bash(npx *), Bash(pnpm *), Bash(yarn *), @@ -204,6 +205,11 @@ stop for input: flag it prominently as a scope warning, keep going, and record i exceeded the recommended size and should be split next time. A runaway list is a scope signal, not a reason to pause for a human. +**Running collaboratively.** When the request asks to review each behavior as it lands, which is what `pairing` does +when it hands work here, stop at this point and hand control back instead of continuing. Present the stop in the shape +[collaborative-stop-rule.md](../../references/collaborative-stop-rule.md) specifies. Absent such a request, continue as +below; an ordinary invocation is unchanged. + Return to the top of Step 3 with the next item. Continue until the list is empty. ## Step 4: Close the Outer Loop diff --git a/han-core/README.md b/han-core/README.md index 9689c329..c0273a47 100644 --- a/han-core/README.md +++ b/han-core/README.md @@ -1,16 +1,28 @@ # han-core -The shared foundation of the Han suite. It carries the specialist agent roster the other plugins dispatch (every shared -agent except the readability-editor, which lives in `han-communication`, and the research-analyst, which lives in -`han-research`), the project-discovery skill with its project-scanner agent, and the canonical evidence and YAGNI rule -files. The documentation skills live in `han-documentation`, the pre-planning research skills in `han-research`, the -planning skills in `han-planning`, and the coding skills in `han-coding`; each depends on han-core. Install only this -and you have the specialists and project discovery, but no other skills. +The shared foundation of the Han suite, carrying two different kinds of thing. + +Most of it is material the other plugins consume: the specialist agent roster they dispatch (every shared agent except +the readability-editor, which lives in `han-communication`, and the research-analyst, which lives in `han-research`), +the project-discovery skill with its project-scanner agent, and the canonical evidence, YAGNI, and collaborative-stop +rule files. + +It also carries one working mode you invoke directly. `/pairing` builds work in reviewable pieces and hands each one +back before starting the next, across code, design decisions, and writing alike. It sits here because it spans every +kind of work rather than belonging to any one plugin's subject matter. + +The documentation skills live in `han-documentation`, the pre-planning research skills in `han-research`, the planning +skills in `han-planning`, and the coding skills in `han-coding`; each depends on han-core. Install only this and you +have the specialists, project discovery, and the pairing mode. `/pairing` gains its test-driven, refactoring, interface, +and plan-review paths when the plugins carrying those skills are installed alongside it, and names the missing skill +rather than substituting when they are not. **Bundled.** Installed with the `han` meta-plugin. Depends on no other Han plugin. ## Skills +- [`/pairing`](docs/skills/pairing.md) — Build work collaboratively in reviewable pieces, handing each one back before + starting the next, so you steer while the work happens instead of reviewing a finished result. - [`/project-discovery`](docs/skills/project-discovery.md) — Scan the repository for languages, frameworks, tooling, and structure, and write a concise reference section into AGENTS.md or CLAUDE.md for other skills. diff --git a/han-core/docs/skills/pairing.md b/han-core/docs/skills/pairing.md new file mode 100644 index 00000000..0a4b55e5 --- /dev/null +++ b/han-core/docs/skills/pairing.md @@ -0,0 +1,174 @@ +# /pairing + +Operator documentation for the `/pairing` skill in the han plugin. This document helps you decide _when_ and _how_ to +use the skill. For what the skill does internally, read the skill definition at +[`han-core/skills/pairing/SKILL.md`](../../skills/pairing/SKILL.md). + +> See also: [Plugin README](../../README.md) · [Repo root](../../../README.md) · +> [All skills](../../../docs/skills/README.md) · [All agents](../../../docs/agents/README.md) · +> [YAGNI](../../../docs/yagni.md) + +## TL;DR + +- **What it does.** Builds your work in reviewable pieces and hands each one back before starting the next, so you steer + while the work happens. +- **When to use it.** You want to collaborate on something rather than hand it off and review the result. +- **What you get back.** The work itself, plus a running record of the feedback you gave along the way. + +## Key concepts + +- **A concern.** One thing you asked for, with its own deliverable. A request that asks for two things holds two + concerns, they run one after the other, and no piece spans both. +- **A piece.** One unit of work you review on its own. What counts as one depends on the kind of work, and the skill + tells you which kind it picked for each concern before it starts. +- **The plan.** A short list of the concerns and the pieces inside each, proposed before any work begins, that you + accept or change. It also names which pieces carry a choice that is expensive to walk back. +- **A stop.** The end of a turn. You get your position in the plan, what was built, what you can check, and what + changed. The reasoning does not lead. +- **The pre-build ask.** For a piece the plan marked expensive to walk back, the skill asks what you expect before it + builds. Declining is a complete answer. +- **The feedback record.** A file holding everything you said, so a correction you gave at the second stop still applies + at the seventh. You can read it whenever you ask. +- **A backing skill.** An existing skill that does the work while this one handles the pacing. Five carry the flag. + +## When to use it + +**Invoke when:** + +- You want to review a build as it happens rather than at the end. +- You are working on something where a wrong turn early is expensive to unwind. +- You want to think out loud and have your remarks shape what gets built next. +- The work is not code. Design decisions and writing are first-class here. + +**Do not invoke for:** + +- **Being walked through code that already exists.** Use + [`/code-walkthrough`](../../../han-coding/docs/skills/code-walkthrough.md) instead. That skill explains; this one + builds while explaining. +- **Understanding something rather than producing it.** Use + [`/code-overview`](../../../han-coding/docs/skills/code-overview.md) for a written overview, or + [`/research`](../../../han-research/docs/skills/research.md) for an open question. +- **Running a skill straight through.** Invoke `tdd`, `refactor`, `design-an-api`, `iterative-plan-review`, or + `plan-implementation` directly. Each runs to completion without pausing unless this skill is driving. + +## How to invoke it + +Run `/pairing` in Claude Code, or just say it in your own words. + +Give it: + +1. **What you want to pair on.** The clearer the subject, the better the proposed plan. "Pair with me on the export + flow" gets a vaguer plan than "pair with me on adding retry handling to the export job." +2. **The discipline, if you have a preference.** Say "pair with me on tdd for this" and it runs the test-driven loop. + Leave it out and the plan proposes an approach for you to accept or redirect. It never picks silently. +3. **Any context to respect.** A specification, a ticket, a prior decision. The skill reads what you point it at. + +Example prompts: + +- `/pairing`. _"Pair with me on refactoring the notification dispatcher."_ +- `/pairing`. _"Pair with me on designing the API for bulk export."_ +- `/pairing`. _"Pair with me on writing a response to this customer escalation."_ +- `/pairing`. _"Pair with me on implementing the retry logic — I'd like to sketch the shape before we drive it from + tests."_ + +## What you get back + +The work itself, wherever it normally lands. A test-driven build produces code and tests; a design pairing produces a +design document; prose work produces the prose. + +Alongside it, one file: the running feedback record. It lives under the output base directory your +[configuration](../../../docs/configuration.md) sets, or beside the work under `.han/pairing/` when you have no +configuration. Each run gets its own file, so a second run does not overwrite the first. The skill names the path in the +plan it proposes, and again when the loop ends. + +The record holds each piece of feedback you gave and which piece prompted it. When the skill applies a recorded entry to +a later piece, it names which entry, so a misrecorded correction surfaces while it is still cheap to fix. + +## How to get the most out of it + +- **Redirect the plan before the work starts.** The plan is the cheapest thing to change, and the sort it names + determines every boundary after it. If the kind of work looks wrong, say so at the first turn. +- **Merge the concerns back when a split is not worth a stop.** The plan names how your request was split. If two of + them are small enough that you would rather see them together, say so and they run as one. +- **Contest the reversibility markings.** The plan names which pieces it thinks are expensive to walk back. You know + your codebase better than it does. Adding or removing a marking at plan time costs nothing. +- **Ask for several pieces at once when you are moving fast.** "Show me the next three" is honored as asked, and the + loop returns to its normal pace afterward without being asked. This is the middle gear between full ceremony and + turning review off. +- **Answer the pre-build ask honestly, including with "I don't know."** Declining advances the stop exactly as a + considered answer does. The ask exists to get an independent read, and a manufactured guess is worth less than none. +- **Read the feedback record if a later piece feels subtly wrong.** That is usually a correction recorded in a way you + did not intend, and it is much easier to spot in the file than to reconstruct from memory. +- **Pair with `/code-review` afterward.** Reviewing as it goes catches direction; a review pass at the end catches + what a piece-by-piece view cannot see. + +## YAGNI + +This skill does not gate items the way a planning skill does. It builds what you agreed to in the plan and nothing +beyond it, and the plan is yours to cut. + +Two places it applies the rule to itself. It proposes the smallest set of pieces that covers the work rather than +padding the plan for symmetry, and it adds no behavior in response to a run of silent approvals, because nothing +establishes what a run of approvals means. See [YAGNI](../../../docs/yagni.md). + +## Cost and latency + +Runs on the session model with no dispatch fan-out of its own. The skill itself is thin: the cost is whatever the +backing skill would have cost, plus one turn per stop. + +The expensive part is your attention, not tokens. A long session with many stops is the shape this is built for, and the +several-pieces-at-once gear exists so you can spend that attention unevenly. Built for tight-loop iteration, not for a +single high-signal run. + +## In more detail + +**How it splits a request that asks for more than one thing.** Splitting comes before anything else. Two asks joined by +"and then" are two concerns whenever they produce two things you would check separately, and each concern gets its own +pieces and its own stops. Changing code and answering a question about it are always separate, even in one sentence and +even about the same lines, because checking an edit means reading a diff and checking an answer means reading the +answer. When the split is genuinely unclear the skill splits anyway and names it in the plan, where merging the two back +costs you nothing. + +**How it decides what kind of work you brought.** An ordered test per concern, first match wins. Does a flagged skill +cover this? Then it is skill-backed. Does it produce a choice that commits you to something? Decision work. Does it +produce prose someone will read? Prose work. Otherwise the plan supplies the boundaries with no rule behind them. The +order is the tie-break, so drafting a decision record sorts as decision work rather than prose work. Concerns sort +independently, so one request often yields a skill-backed concern and a prose concern side by side. + +**Why the reasoning does not lead at a stop.** Controlled studies found that reading an assistant's explanation does not +reliably make a reviewer more careful, and can make them less so. An explanation reads as competence whether or not its +content holds up. What helps is lowering the cost of checking a claim yourself, so a stop hands you things to verify and +keeps the case for the work below them. + +**Why the ask comes before the build.** The same research found one intervention that measurably worked: committing to +your own judgment before seeing the assistant's answer. It only works beforehand. An ask arriving once the work is on +disk collects the annoyance and none of the benefit. It fires only where a mistake is expensive to undo, because the +study that measured the benefit also measured a satisfaction cost. + +**What the prose ladder does on long work.** Short writing climbs the ladder once, whole: shape, then rough draft, then +language. For longer writing, the shape is agreed for the whole artifact first, then the remaining rungs climb section +by section. Sectioning only the later rungs keeps structural feedback ahead of surface feedback, which is the ordering +the ladder exists for. + +**What is not settled.** Stopping where the kind of feedback changes is well evidenced. The specific unit for each kind +is less so, and for open-ended work no source defines one at all, which is why the plan negotiates rather than applying +a rule. The test for a choice being expensive to walk back was authored for this skill rather than drawn from a source. +Treat both as provisional. + +## Related documentation + +- [Plugin README](../../README.md). The plugin's front door: its skills, agents, and how they fit together. +- [Repo root README](../../../README.md). The Han suite landing page. Start here if you arrived from outside the docs + tree. +- [YAGNI](../../../docs/yagni.md). The evidence-based "You Aren't Gonna Need It" rule. +- [`collaborative-stop-rule.md`](../../references/collaborative-stop-rule.md). The shared contract this skill and its + five backing skills follow, defining what a stop presents and what returning control means. +- [`/tdd`](../../../han-coding/docs/skills/tdd.md), [`/refactor`](../../../han-coding/docs/skills/refactor.md), and + [`/design-an-api`](../../../han-coding/docs/skills/design-an-api.md). The coding skills this one can drive. +- [`/iterative-plan-review`](../../../han-planning/docs/skills/iterative-plan-review.md) and + [`/plan-implementation`](../../../han-planning/docs/skills/plan-implementation.md). The planning skills this one can + drive. +- [`/code-walkthrough`](../../../han-coding/docs/skills/code-walkthrough.md). The skill this one is most often confused + with, and the boundary between them. +- [Configuration](../../../docs/configuration.md). Where the feedback record lands, and how the output base directory is + resolved. diff --git a/han-core/references/collaborative-stop-rule.md b/han-core/references/collaborative-stop-rule.md new file mode 100644 index 00000000..d9cbc7a7 --- /dev/null +++ b/han-core/references/collaborative-stop-rule.md @@ -0,0 +1,127 @@ +# Collaborative Stop Rule (Handing Control Back Mid-Run) + +This rule defines what happens when a skill running collaboratively reaches a unit boundary: how it knows to stop, what +it presents when it stops, and what it does with the answer. It exists so a stop means the same thing whichever skill +performed it. + +Six places need to agree on that answer. `pairing` drives the loop, and `tdd`, `refactor`, `design-an-api`, +`iterative-plan-review`, and `plan-implementation` each stop at a boundary they already have. Without one shared +definition, each would describe stopping in its own words and a person would meet six slightly different experiences. +Every vendored copy of this file is byte-identical to the canonical `han-core/references/collaborative-stop-rule.md`. + +## Who reads this + +Two kinds of reader, needing different parts. + +**A skill that gains the collaborative flag** reads "Detecting the flag" and "What a stop presents." Those two sections +are the whole contract for a backing skill. Nothing else here is required reading to add the flag correctly. + +**The skill driving the loop** reads all of it, because it also owns the plan, the record, and the sorting of work that +has no backing skill at all. + +## Detecting the flag + +The collaborative flag arrives as a named argument on the invocation, never as a caller's identity. A skill supporting +it declares the argument in frontmatter and branches on its value at the boundary the skill already has. + +Never make a skill test which skill invoked it. A skill that names its caller breaks when the caller is renamed, and it +cannot be driven collaboratively by anything else later. The argument form carries the same information without the +coupling. + +Never let the flag change anything except what happens at an existing boundary. It adds no new boundary, skips no step, +and relaxes no gate the skill already enforces. An invocation without the flag behaves exactly as it does today, which +is what makes the flag safe to add to a skill people already rely on. + +## What a stop presents + +A stop hands the person something to check, not a case for the work. That ordering is the point of the whole +convention: a fluent explanation raises agreement without raising scrutiny, so leading with the reasoning defeats the +review the stop exists to get. + +Every stop carries four things, in this order: + +1. **Position.** Which piece this is against the plan, and what remains. A person deciding whether they have the + attention for two more pieces cannot answer that without it. +2. **What was built or found.** The unit that just closed, named in the terms that skill already uses. +3. **What can be checked.** The specific claims the person can verify. For work that produces an artifact, these are + properties of the artifact. For a review round, the findings themselves are the checkable claims, and the plan edits + the round made are what changed. +4. **What changed.** Since the previous stop, not since the beginning. + +The reasoning behind the choices comes last or not at all. State in one line that it is available for the asking, and +stop there BECAUSE an unannounced affordance in a conversation is the same as no affordance, while a volunteered +rationale is the thing that suppresses scrutiny. + +Then end the turn. Nothing further is built until the person responds. + +That last instruction is a directive, not a guarantee. Nothing in the platform enforces it. When a run does build past a +stop, the next thing it says names the overrun, states which pieces went unreviewed, and offers to walk back through +them. Never present unreviewed work as though it had been approved. + +## Asking before building, and when + +For a piece carrying a choice that is expensive to walk back, the ask comes **before** the build, not at the stop +afterward. Committing to your own expectation before the answer exists is the mechanism; an ask arriving once the work +is on disk collects the cost and none of the benefit. + +**The test.** A choice is expensive to walk back when later pieces in the plan would have to be redone to undo it. Apply +it against the plan you already proposed, which lists the pieces, so the question is answerable rather than a matter of +taste. + +Three consequences follow from that test and are part of it: + +- Most plans mark one piece, sometimes two. A piece nothing else depends on is cheap to redo by definition. +- A plan that marks every piece has misapplied the test. Stop and re-derive it rather than asking at every stop, which + is the outcome this calibration exists to avoid. +- A plan that marks nothing is the normal case for short work with independent pieces. Do not manufacture a marking to + fill the slot. + +This criterion is authored here rather than drawn from a source. The framework behind it separates reversible from +irreversible decisions and prescribes different review depth for each, but supplies no way to tell them apart. Treat the +test as provisional and revisit it once real runs show whether it marks the pieces people find expensive. + +**The ask itself** names the dimension the choice turns on and stops there. Do not pose a blank question, and do not +offer candidate answers, BECAUSE named candidates anchor the guess and the point is an independent read. + +**Declining is a first-class answer.** "I don't know" and "just show me" advance the piece exactly as a considered +answer does. Never re-prompt, and never require an answer before building. + +**After the build, the reveal is an ordinary stop.** It does not restate the person's read, score it, or defend a +divergence from it. A stop that grades you teaches you to answer noncommittally, and a stop that argues with you leads +with the reasoning this convention keeps out of the lead. + +## Recording what the person says + +Write every piece of feedback into the running record before acting on it. A correction given at the second stop has to +still apply at the seventh, and mid-context material is the least reliably recalled. + +The person can read the record whenever they ask. When a recorded entry shapes a later piece, name which entry it was, +so a misrecorded correction surfaces while it is still cheap to fix rather than quietly governing the rest of the +session. + +## Acting on the answer + +Three routes, by what the feedback touches. + +**The piece in hand.** Fix it within that piece and show it again. The re-show names the correction applied and what it +touched before restating the piece. It is a stop like any other, so end the turn and wait rather than moving on. + +**What comes next.** Carry it into the next piece. + +**Work outside the piece in hand.** Say so before acting: name that the feedback looks like it reaches past this piece, +and what it would change about the plan. Then offer three ways out, never two. The person accepts a revised plan, +changes it, or declines the reopening entirely, in which case the feedback is recorded as scoped to later work and the +agreed plan continues. The third exit is what keeps an offhand remark from silently replacing a plan the person agreed +to. + +## Pace + +Honor a request for more than one piece as asked, then return to the normal pace at the following stop without being +asked to. Without that middle gear the only choices are full ceremony on every piece or no review at all, and the second +is what the loop exists to prevent. + +Add no pressure to comment. A run of silent approvals is a valid response and means nothing in particular; do not +volunteer anything in reply to it. + +Ending the loop is the person's call. Nothing here computes a stopping point, because work being built produces no +countable signal to compute over. diff --git a/han-core/skills/pairing/SKILL.md b/han-core/skills/pairing/SKILL.md new file mode 100644 index 00000000..ba4d8419 --- /dev/null +++ b/han-core/skills/pairing/SKILL.md @@ -0,0 +1,205 @@ +--- +name: pairing +description: > + Build work collaboratively in reviewable pieces, handing each piece back for review before starting the next, so the + person stays in the lead and steers while the work happens instead of reviewing a finished result. Use when someone + says to pair with them on something, asks to collaborate rather than direct, wants to review as it goes, or wants to + guide the work piece by piece — on code, on a design decision, or on writing. For a test-first build it runs tdd, for + restructuring it runs refactor, for an interface contract it runs design-an-api, and for plan work it runs + iterative-plan-review or plan-implementation, each collaboratively; invoke any of those directly instead to run it + straight through without pausing. Does not pace someone through code that already exists and builds nothing — use + code-walkthrough. Does not explain, summarize, or research something instead of producing it — use code-overview or + research. +allowed-tools: Read, Write, Edit, Glob, Grep, Skill, Bash(find *) +argument-hint: "[what to pair on]" +--- + +## Project Context + +- personal config directory: !`echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"` +- project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""` +- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f` + +As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read +that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md` +probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence +between the two files, relative-path resolution, and what to do with a file that reads but cannot be used. + +## The contract this skill runs on + +Read [collaborative-stop-rule.md](../../references/collaborative-stop-rule.md) before Step 4. It defines what a stop +presents, when the pre-build ask fires, what makes a choice expensive to walk back, and what to do with the answer. The +skills this one hands work to follow the same file, which is what makes a stop feel the same whoever performed it. + +Two constraints from that file govern every step below and are repeated here because they are the ones most easily lost: + +- **The pacing is the deliverable.** Ending the turn at each stop is the product, not an interruption in it. Never + continue past a stop to be helpful. +- **A stop hands over something to check, never a case for the work.** Lead with what the person can verify. The + reasoning goes last or goes unsaid until asked, BECAUSE a fluent explanation raises agreement without raising + scrutiny, which is the failure this whole loop exists to prevent. + +# Pairing + +## Step 1: Resolve the Record Location + +Resolve where the running feedback record will be written, using the output base directory from the configuration +probed above. Absent any configuration, write it beside the work under `.han/pairing/`. + +Name the file for this run so a second run in the same repository does not overwrite the first. State the path to the +person in Step 4's plan, in one clause, BECAUSE a record they cannot find is not a record. + +Read the file first if it already exists. A run resuming after an interrupted session inherits the record rather than +starting a new one. + +## Step 2: Split the Request Into Concerns + +Split the request into concerns before sorting any of it. A request holding two concerns and sorted as one produces one +kind, one set of boundaries, and one uninterrupted run through both, which is how a build and the work that depends on +that build end up in the same turn with neither of them reviewed. + +**A concern is one thing the person asked for, with its own deliverable.** Two asks joined by "and", "and then", "then +help me", or a numbered list are two concerns whenever they produce two things the person would check separately. An +edit to a file and a reply to a question are two deliverables even when they are about the same lines of code. + +**Changing code and understanding or answering a question are always separate concerns.** This one takes no judgment. +Never bundle them, whatever their subject, however small either one is, and however plainly the second follows from the +first, BECAUSE checking an edit means reading a diff and checking an answer means reading the answer. Bundled, the +answer arrives before the edit it rests on has been verified, so a wrong edit yields a confident wrong answer and the +two pass unreviewed together. + +**Do not split one deliverable into concerns.** The steps inside a single deliverable are pieces, and Step 4's plan +divides them. Two concerns exist when the person would check two different artifacts, not when one artifact takes +several steps. + +Concerns run in sequence and never interleave. The last piece of one concern is a stop like any other, and the next +concern does not begin until the person responds. + +**When you cannot tell whether the request holds one concern or two, treat it as two** and say so in the plan, where the +person can merge them back. An extra stop costs one turn. A missing one costs the review this whole loop exists to get. + +## Step 3: Sort Each Concern + +Apply this test to each concern separately, in order, and stop at the first match: + +1. Does a skill carrying the collaborative flag cover this work? Then it is **skill-backed**. The flagged skills are + `tdd` for a test-first build, `refactor` for restructuring, `design-an-api` for an interface contract, + `iterative-plan-review` for sharpening a plan, and `plan-implementation` for planning a build. +2. Does the work produce a choice among options that commits the person to something? Then it is **decision work**. +3. Does the work produce prose someone will read? Then it is **prose work**. +4. Otherwise it is **open-ended**, and Step 4's plan supplies the boundaries with no rule behind them. + +The order is the tie-break. A concern matching more than one kind sorts as the earliest match, so drafting a decision +record sorts as decision work rather than prose work. Concerns sort independently, so one request routinely yields a +skill-backed concern and a prose concern side by side. + +**Never guess the discipline for skill-backed work.** A concern to build something that does not say whether to drive +it from tests, restructure what is there, or sketch a shape first is answered by proposing an approach in Step 4, never +by picking one silently. A single concern may span more than one approach. + +**When a concern is too vague to sort**, ask once. Name what was ambiguous and offer candidate readings. If the answer +still does not settle it, propose a plan against the most likely reading and say that is what you did. Never sort a +concern you could not read. + +**When a concern asks to understand something rather than produce something**, this skill is the wrong one for it. Say +so and name where it goes: `code-walkthrough` for paced explanation of existing code, `code-overview` for a written +overview, `research` for an open question. Do not sort it as open-ended and propose a plan to build things. When it is +one concern among several, hand off that one and keep the rest in the plan rather than ending the run. + +## Step 4: Propose the Plan + +Before any work starts, present a short plan. It names: + +- The concerns the request split into, in the order they will run, and which kind each one sorted into. **Always state + both** BECAUSE the split sets where control comes back and the sort determines every boundary inside a concern, and + they are the parts of the plan the person cannot correct if they cannot see them. +- The pieces to be built inside each concern, and the reason for each boundary. No piece spans two concerns. +- Which pieces carry a choice that is expensive to walk back, applying the test in the stop rule. Naming them here is + what makes that call contestable while contesting it is still cheap. +- Where the feedback record lives. + +What counts as one piece depends on the kind that concern sorted into: + +| Kind of work | One piece is | +| ------------ | -------------------------------------------------------------------------------------- | +| Skill-backed | Whatever that skill already treats as one unit | +| Decision | One decision, with its context, the options weighed, and what it commits the person to | +| Prose | One rung of a fidelity ladder: the shape, then a rough draft, then the language | +| Open-ended | Whatever this plan names | + +**For prose, scale the ladder to the size of the work.** Short work climbs the ladder once, whole. For longer work, +agree the shape for the whole artifact first, then climb the remaining rungs section by section, naming the sections in +this plan so they can be redirected. Sectioning only the later rungs keeps structural feedback ahead of surface +feedback, which is the ordering the ladder exists for. + +**For skill-backed work the plan names the backing skill, the unit it stops at, and the reason — not the list of units.** +That skill builds its own list partway through its own run, so the list does not exist yet. Surface it at the first stop, +where it can still be redirected. + +**When the plan sequences more than one backing skill**, order them so each skill's own preconditions hold when its turn +arrives. `refactor` will not run alongside an unfinished test-driven loop, so a plan that sequences both closes the first +before starting the second. + +Then wait. The person accepts the plan, changes it, or replaces it. + +## Step 5: Run the Loop + +Repeat until the plan is finished or the person ends it. The loop walks the concerns in the order the plan named, and +the pieces inside each one in the order the plan named. + +1. **If the plan marked this piece expensive to walk back, ask first.** Follow the ask protocol in the stop rule: name + the dimension the choice turns on, offer no candidate answers, and accept a declined answer as a complete one. The ask + comes before the build, never after. + +2. **Build one piece.** + + For skill-backed work, invoke the backing skill with the collaborative argument set, and forward the person's request + and any constraints through unchanged. That skill runs its own job and stops at the boundary it already has. + **After the invocation returns, continue this loop explicitly** BECAUSE the moment after a sub-skill call is where an + orchestration most often stops and treats the sub-skill's output as its final answer. + + When a backing skill is not available, name it and offer the choice between the open-ended path and installing the + plugin that carries it. **Never substitute silently** — hand-rolling a refactoring skips the passing-test gate that + skill exists to enforce. + + For every other kind, build the piece yourself. + +3. **Present the stop**, in the shape the stop rule specifies: position in the plan, what was built, what can be + checked, what changed, and one line saying the reasoning is available for the asking. + + When the piece closes a concern, say so in the position line and name the concern that comes next. That tells the + person the next response starts different work, which is the moment their review matters most. + +4. **End the turn.** Nothing further is built until the person responds. **Starting the next concern is not an + exception**, however directly it follows from the one that just closed. + +## Step 6: Act on the Response + +Write the response into the record before acting on it. When a recorded entry shapes this piece, name which entry it +was. + +Then route by what the feedback touches, per the stop rule: + +- **The piece in hand.** Fix it within that piece and show it again, naming the correction and what it touched. That + re-show is a stop, so return to Step 5's fourth instruction and wait. Do not return to the pre-build ask; this piece is + already built. +- **What comes next.** Carry it into the next piece and return to the top of Step 5. +- **Work outside the piece in hand.** Name that reading before acting on it, then offer three ways out: accept a revised + plan, change it, or decline the reopening so the feedback is recorded as scoped to later work and the agreed plan + continues. + +**A question holds the person's place; it never advances the work.** Answer it and stop again at the same place. + +**When the person asks for more than one piece at a time**, honor it as asked, present the pieces together, and return +to the normal pace at the following stop without being asked to. + +**When the person says to finish without stopping**, acknowledge it in the same turn and name what will now go +unreviewed, then continue from the current plan and report at the end. + +## Step 7: Close + +Report what was built, what the person's feedback changed, anything the plan named but did not reach, the state of any +work a backing skill left mid-cycle, and where the feedback record was written. + +Ending is the person's call throughout. Nothing here computes a stopping point, BECAUSE work being built produces no +countable signal to compute over. diff --git a/han-planning/docs/skills/iterative-plan-review.md b/han-planning/docs/skills/iterative-plan-review.md index 093aceeb..ff0bfa01 100644 --- a/han-planning/docs/skills/iterative-plan-review.md +++ b/han-planning/docs/skills/iterative-plan-review.md @@ -421,6 +421,8 @@ https://projectmanagementcompass.substack.com/p/building-decision-logs-that-prot - [Plugin README](../../README.md). The plugin's front door: its skills, agents, and how they fit together. - [Repo root README](../../../README.md). The Han suite landing page. Start here if you arrived from outside the docs tree. +- [`/pairing`](../../../han-core/docs/skills/pairing.md). Drive these review rounds collaboratively, stopping after each + one so you see its findings as they land rather than only the finished plan. - [YAGNI](../../../docs/yagni.md). The evidence-based "You Aren't Gonna Need It" rule this skill applies before committing items. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. - [Evidence](../../../docs/evidence.md). The companion review pillar. Trust classes, the corroboration gate for web-source diff --git a/han-planning/docs/skills/plan-implementation.md b/han-planning/docs/skills/plan-implementation.md index 3cf2575f..4e9e959a 100644 --- a/han-planning/docs/skills/plan-implementation.md +++ b/han-planning/docs/skills/plan-implementation.md @@ -446,6 +446,8 @@ URL: https://ieeexplore.ieee.org/document/1204375 - [Plugin README](../../README.md). The plugin's front door: its skills, agents, and how they fit together. - [Repo root README](../../../README.md). The Han suite landing page. Start here if you arrived from outside the docs tree. +- [`/pairing`](../../../han-core/docs/skills/pairing.md). Drive these resolution rounds collaboratively, stopping after + each one so you see its findings as they land rather than only the finished plan. - [YAGNI](../../../docs/yagni.md). The evidence-based "You Aren't Gonna Need It" rule this skill applies before committing items. The two gates, the acceptable-evidence list, the named anti-patterns, and the deferral format. - [Skills Index](../../../docs/skills/README.md). All skills, grouped by purpose. diff --git a/han-planning/references/collaborative-stop-rule.md b/han-planning/references/collaborative-stop-rule.md new file mode 100644 index 00000000..d9cbc7a7 --- /dev/null +++ b/han-planning/references/collaborative-stop-rule.md @@ -0,0 +1,127 @@ +# Collaborative Stop Rule (Handing Control Back Mid-Run) + +This rule defines what happens when a skill running collaboratively reaches a unit boundary: how it knows to stop, what +it presents when it stops, and what it does with the answer. It exists so a stop means the same thing whichever skill +performed it. + +Six places need to agree on that answer. `pairing` drives the loop, and `tdd`, `refactor`, `design-an-api`, +`iterative-plan-review`, and `plan-implementation` each stop at a boundary they already have. Without one shared +definition, each would describe stopping in its own words and a person would meet six slightly different experiences. +Every vendored copy of this file is byte-identical to the canonical `han-core/references/collaborative-stop-rule.md`. + +## Who reads this + +Two kinds of reader, needing different parts. + +**A skill that gains the collaborative flag** reads "Detecting the flag" and "What a stop presents." Those two sections +are the whole contract for a backing skill. Nothing else here is required reading to add the flag correctly. + +**The skill driving the loop** reads all of it, because it also owns the plan, the record, and the sorting of work that +has no backing skill at all. + +## Detecting the flag + +The collaborative flag arrives as a named argument on the invocation, never as a caller's identity. A skill supporting +it declares the argument in frontmatter and branches on its value at the boundary the skill already has. + +Never make a skill test which skill invoked it. A skill that names its caller breaks when the caller is renamed, and it +cannot be driven collaboratively by anything else later. The argument form carries the same information without the +coupling. + +Never let the flag change anything except what happens at an existing boundary. It adds no new boundary, skips no step, +and relaxes no gate the skill already enforces. An invocation without the flag behaves exactly as it does today, which +is what makes the flag safe to add to a skill people already rely on. + +## What a stop presents + +A stop hands the person something to check, not a case for the work. That ordering is the point of the whole +convention: a fluent explanation raises agreement without raising scrutiny, so leading with the reasoning defeats the +review the stop exists to get. + +Every stop carries four things, in this order: + +1. **Position.** Which piece this is against the plan, and what remains. A person deciding whether they have the + attention for two more pieces cannot answer that without it. +2. **What was built or found.** The unit that just closed, named in the terms that skill already uses. +3. **What can be checked.** The specific claims the person can verify. For work that produces an artifact, these are + properties of the artifact. For a review round, the findings themselves are the checkable claims, and the plan edits + the round made are what changed. +4. **What changed.** Since the previous stop, not since the beginning. + +The reasoning behind the choices comes last or not at all. State in one line that it is available for the asking, and +stop there BECAUSE an unannounced affordance in a conversation is the same as no affordance, while a volunteered +rationale is the thing that suppresses scrutiny. + +Then end the turn. Nothing further is built until the person responds. + +That last instruction is a directive, not a guarantee. Nothing in the platform enforces it. When a run does build past a +stop, the next thing it says names the overrun, states which pieces went unreviewed, and offers to walk back through +them. Never present unreviewed work as though it had been approved. + +## Asking before building, and when + +For a piece carrying a choice that is expensive to walk back, the ask comes **before** the build, not at the stop +afterward. Committing to your own expectation before the answer exists is the mechanism; an ask arriving once the work +is on disk collects the cost and none of the benefit. + +**The test.** A choice is expensive to walk back when later pieces in the plan would have to be redone to undo it. Apply +it against the plan you already proposed, which lists the pieces, so the question is answerable rather than a matter of +taste. + +Three consequences follow from that test and are part of it: + +- Most plans mark one piece, sometimes two. A piece nothing else depends on is cheap to redo by definition. +- A plan that marks every piece has misapplied the test. Stop and re-derive it rather than asking at every stop, which + is the outcome this calibration exists to avoid. +- A plan that marks nothing is the normal case for short work with independent pieces. Do not manufacture a marking to + fill the slot. + +This criterion is authored here rather than drawn from a source. The framework behind it separates reversible from +irreversible decisions and prescribes different review depth for each, but supplies no way to tell them apart. Treat the +test as provisional and revisit it once real runs show whether it marks the pieces people find expensive. + +**The ask itself** names the dimension the choice turns on and stops there. Do not pose a blank question, and do not +offer candidate answers, BECAUSE named candidates anchor the guess and the point is an independent read. + +**Declining is a first-class answer.** "I don't know" and "just show me" advance the piece exactly as a considered +answer does. Never re-prompt, and never require an answer before building. + +**After the build, the reveal is an ordinary stop.** It does not restate the person's read, score it, or defend a +divergence from it. A stop that grades you teaches you to answer noncommittally, and a stop that argues with you leads +with the reasoning this convention keeps out of the lead. + +## Recording what the person says + +Write every piece of feedback into the running record before acting on it. A correction given at the second stop has to +still apply at the seventh, and mid-context material is the least reliably recalled. + +The person can read the record whenever they ask. When a recorded entry shapes a later piece, name which entry it was, +so a misrecorded correction surfaces while it is still cheap to fix rather than quietly governing the rest of the +session. + +## Acting on the answer + +Three routes, by what the feedback touches. + +**The piece in hand.** Fix it within that piece and show it again. The re-show names the correction applied and what it +touched before restating the piece. It is a stop like any other, so end the turn and wait rather than moving on. + +**What comes next.** Carry it into the next piece. + +**Work outside the piece in hand.** Say so before acting: name that the feedback looks like it reaches past this piece, +and what it would change about the plan. Then offer three ways out, never two. The person accepts a revised plan, +changes it, or declines the reopening entirely, in which case the feedback is recorded as scoped to later work and the +agreed plan continues. The third exit is what keeps an offhand remark from silently replacing a plan the person agreed +to. + +## Pace + +Honor a request for more than one piece as asked, then return to the normal pace at the following stop without being +asked to. Without that middle gear the only choices are full ceremony on every piece or no review at all, and the second +is what the loop exists to prevent. + +Add no pressure to comment. A run of silent approvals is a valid response and means nothing in particular; do not +volunteer anything in reply to it. + +Ending the loop is the person's call. Nothing here computes a stopping point, because work being built produces no +countable signal to compute over. diff --git a/han-planning/skills/iterative-plan-review/SKILL.md b/han-planning/skills/iterative-plan-review/SKILL.md index e5b79602..6bb71276 100644 --- a/han-planning/skills/iterative-plan-review/SKILL.md +++ b/han-planning/skills/iterative-plan-review/SKILL.md @@ -5,7 +5,8 @@ description: > and recording every finding and iteration in cross-referenced companion files. Use this skill whenever the user wants to iterate on, refine, tighten, or improve a plan. Also use it when the user asks to verify, validate, or confirm feasibility of an approach. Does not implement plan steps, write test plans, review code, or investigate bugs, and - does not generate new plans from scratch — use plan-a-feature for a new plan. + does not generate new plans from scratch — use plan-a-feature for a new plan. Runs its review rounds to completion + without pausing between them; to review each round as it lands, use pairing. arguments: size argument-hint: "[size: small | medium | large | dynamic] [context or path to plan file]" allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *) @@ -349,6 +350,13 @@ loop earlier whenever a round goes quiet, so the cap is a ceiling rather than a primary flow path). The size cap from Step 2 sets the upper bound: medium = 2 rounds, large = 3 rounds. Never exceed the size cap. +**Running collaboratively.** When the request asks to review each round as it lands, which is what `pairing` does when +it hands work here, stop at the end of each round and hand control back instead of starting the next. Present the stop +in the shape [collaborative-stop-rule.md](../../references/collaborative-stop-rule.md) specifies: the round's findings +are what the person can check, and the plan edits the round made are what changed. A redirect at such a stop does not +consume a round against the cap, BECAUSE a round is a unit of review work and a redirect is not. Absent such a request, +continue as below; an ordinary invocation is unchanged. + Between rounds, surface to the user any finding where two agents disagree on substance, or where resolving the finding requires a judgment only the plan's author can make. Present each as a contextual question with impact, tradeoffs, and a recommended answer. Record the question on the corresponding `F#` entry and, if the user answers before the next round, diff --git a/han-planning/skills/plan-implementation/SKILL.md b/han-planning/skills/plan-implementation/SKILL.md index 446370c2..50f40bc4 100644 --- a/han-planning/skills/plan-implementation/SKILL.md +++ b/han-planning/skills/plan-implementation/SKILL.md @@ -5,7 +5,8 @@ description: > facilitated team conversation. Use when the user wants to plan how to implement, build, deliver, or ship a feature that has already been specified. Does not specify what the feature should do — use plan-a-feature first. Does not design the contract for an interface — use design-an-api. Does not refine or stress-test an already-written plan — - use iterative-plan-review. + use iterative-plan-review. Runs its resolution rounds to completion and holds its questions until after they finish; + to review each round as it lands, use pairing. arguments: size argument-hint: "[size: small | medium | large | dynamic] [feature specification path, optional: additional context]" allowed-tools: Read, Write, Edit, Glob, Grep, Agent, Bash(find *), Bash(git *), Bash(mkdir *), Bash(cp *) @@ -318,6 +319,13 @@ For each iteration: deterministic next-step recommendation. Leave `Decisions produced:` and `Changed in plan:` as `—` for now; both fields are backfilled by the han-core:plan-synthesizer in Step 8 once decisions are committed and the plan is written. + **Running collaboratively.** When the request asks to review each round as it lands, which is what `pairing` does + when it hands work here, stop at the end of each round and hand control back instead of starting the next. Present + the stop in the shape [collaborative-stop-rule.md](../../references/collaborative-stop-rule.md) specifies: the + round's findings are what the person can check, and the plan edits the round made are what changed. A redirect at + such a stop does not consume a round against the cap, BECAUSE a round is a unit of review work and a redirect is not. + Absent such a request, continue as below; an ordinary invocation is unchanged. + 5. **Decide whether to continue looping (deterministic stop rule).** Exit the loop when ANY of the following holds: - The deterministic next-step recommendation is **"go to synthesis."** - The deterministic next-step recommendation is **"blocked pending user input"** and all blocking Open Questions have