research

Investigates an issue or task through falsifiable hypotheses and posts the resulting plan to GitHub. Do NOT write any production code in this skill.

Issue / task: $ARGUMENTS

Step 0 — Determine issue context

Check whether $ARGUMENTS is a number (existing issue) or free text (new task).

• Number → proceed with that issue.
• Free text → use the text as the task description; an issue will be created in Step 7.

Step 1 — Read issue/task and form hypotheses

1. For an existing issue, read it with "${CLAUDE_SKILL_DIR}/../read-issue/scripts/read-issue.sh" <n>, <n> being the issue number $ARGUMENTS names; when the read exits nonzero, stop and report its message. For a new task, use the free text.
2. Skim the project layout (directory tree, CLAUDE.md, key entry points). Do NOT deep-read files yet.

3. Establish baselines.

   • Test baseline: build and run existing tests. Record pre-existing failures so later regressions can be distinguished.
   • Memory recall baseline: read MEMORY.md (index only); for each entry whose one-line description plausibly intersects the work, open and read it. A hypothesis that contradicts an active memory rule is rejected at formation.
   • Rule-set baseline: invoke the authoritative-text-rules skill and read its Scope section and Items index in main context; a rule set that does not resolve halts research, naming what was looked for. Then read every item body that index lists, deriving the set from the index as that skill directs — skipping that read, and only that read, when the issue and the layout skim above positively establish that every surface the change could touch is excluded by that Scope section. A surface the skim left unenumerated establishes nothing, and the absence of a stated reason to touch a qualifying surface is not an exclusion. A hypothesis that contradicts a loaded item is rejected at formation.

   Whenever a surface the change could touch is found to qualify under that Scope section and the item-body read was skipped, re-run that baseline and return to hypothesis formation, because the hypothesis set was formed without the items. Every other movement on this axis calls for nothing: where a qualifying surface drops out instead, the loaded items constrained hypotheses the drop removes, so none formed under them survives to be wrong.

4. Form hypotheses across three aspects:

   • What needs to change: required code modifications
   • What invariants must hold: contracts / preconditions / correctness properties
   • What could break: existing code paths affected by the change, especially where new inputs flow through existing APIs
5. Each hypothesis names its falsifier: a concrete observation or counterexample that would defeat it.

6. Tag each hypothesis with a kind:

   • empirical — resolved by reading code, running tests, observing runtime, inspecting git history, querying spec / external API / caller behavior. Probes in Step 2 handle these.
   • derivational — resolved by deductive reasoning from defining equations / type laws / protocol axioms / mathematical or physical first principles. The truth value of a derivational hypothesis does not depend on the state of the codebase; reading more code will not resolve it. Step 2 handles these in the main context, not via subagents.

   Disambiguation test: "if the codebase did not exist, would the claim still have a definite truth value?" Yes → derivational. No → empirical. Two follow-on rules:

   • Numerical verification stays derivational. "Construct a candidate → check against an oracle (spec, reference value, closed-form ground truth)" is derivational; resolve in Step 2.B with a scratch script outside the project tree.
   • Misclassification signal. If a probe's action is "write code in the project, then check whether it works", it is a derivational gap dressed as an empirical probe — re-classify before the plan exits research.
7. Specific-example claim sweep (REQUIRED when applicable). If the plan attaches deductive properties to a concrete example ("this example is symmetric / non-degenerate / exercises the multi-X path"), each property MUST be a separate derivational hypothesis — "obvious" is not an exemption. Form: "Example E has property P, derivable from E's defining equations / specification."
8. Present hypotheses to the user for approval before Step 2. Show the kind tag and the falsifier for each. The user can narrow or widen scope, split into sub-issues, or correct mis-classifications.

Step 2 — Verify hypotheses

Hypotheses split by kind. Empirical hypotheses go through probes (Step 2.A). Derivational hypotheses are resolved in the main context (Step 2.B). Both must complete before Step 3 consolidates.

Decisions and disconfirming probes

A disconfirming probe is a check that looks for a hypothesis's falsifier. Whoever verifies an empirical hypothesis, a subagent or the main context, runs one unless it cannot run; listing it is not enough. Where the hypothesis claims more than that probe covered, run one over the rest too. A part no probe that ran could tell about is split off as its own inconclusive hypothesis. A probe leaves the working tree as it found it.

Every verifier of an empirical hypothesis also follows these:

• For non-trivial existing code, read the code itself. Shallow grep-only verification is permitted only for trivially mechanical hypotheses (existence checks, file locations).
• Runtime probe for behavioral claims. Behavioral claims (output ordering, return shape, error-path return, ABI / FFI layout, signal handling, performance) need a minimal reproducer — docs reading is corroboration, not verification. Boundary cases (minimal/maximal sizes, type variations, single-element containers) belong here.
• Caller-contract verification for change-impact hypotheses. Classify the change as compile-breaking (new required trait method, type change) or silently semantic (same signature, different behavior). Semantic changes need caller-by-caller verification. Flag any public API with unchecked internal assumptions (pointer arithmetic trusting an offset, a serializer trusting field order, an index trusting contiguity).

An empirical hypothesis completes when it holds one of four Decisions:

• confirmed — a disconfirming probe ran, could have found the falsifier, and no probe found it.
• rejected — a probe found the falsifier. The plan does not rest on a rejected hypothesis.
• inconclusive — no probe that ran could tell.
• deferred — the main context puts it outside the current scope, whatever the probes found.

A probe cannot run when it would change anything outside the local machine, when its effect could not be undone afterwards, or when the verifier has no way to run it. Do not run it. In place of a disconfirming probe that cannot run, run another probe these rules allow that can look for the falsifier over all or part of what the hypothesis claims. With no such probe, the hypothesis is inconclusive. When a probe that cannot run leaves a hypothesis or a part of it inconclusive, the probe: says why it cannot run and what it needs.

Step 2.A — Empirical hypotheses (subagents)

Spawn one subagent per empirical hypothesis (or per small related group). Put in its prompt the hypothesis and its falsifier, the task, the repository path, the text of Decisions and disconfirming probes, and this contract.

Subagent contract:

1. Return a Decision for each assigned hypothesis, and for each part of a split one, once each has one. For inconclusive, attach the probe: that would decide it.
2. Report back with concise file paths, line numbers, function signatures, and, for each hypothesis, what each probe looked for, what ran, and its result.

Subagent granularity: hypotheses requiring only existence checks or single-file grep can be resolved directly from the main context. Reserve subagents for hypotheses that touch multiple files or need deep reading. Spawn all empirical-hypothesis subagents in a single message.

Step 2.B — Derivational hypotheses (deductive verification in main context)

Each derivational hypothesis is resolved by working out the deduction explicitly, not by reading code. The deduction may take either form:

• Symbolic — pen-and-paper algebra / type-law rewriting / protocol-axiom application.
• Numerical — when the closed form is too messy, reduce to a numerical identity against an oracle (published reference matrix, closed-form spec, ground-truth value); run a scratch script outside the project tree. This is the derivation, not a deferred implementation probe.

Subagents cannot resolve derivational hypotheses.

For each derivational hypothesis:

1. State the defining equations / axioms / specification clauses the example or claim rests on. Quote the source if it is an external spec (RFC, protocol doc, mathematical definition); reproduce it if it is a project-internal definition.
2. Derive forward from the defining equations to the claimed property. Show the deductive steps. A derivation that ends in "therefore P holds" without reproducible steps is unacceptable.
3. Attempt a counterexample (the disconfirming step). Try to construct an instance of the example where the claimed property fails, working from the defining equations. A property that resists counterexample construction is corroborated; one that admits a counterexample falsifies the hypothesis.
4. Report a Decision in the four-state shape from Step 2, with these derivational-specific resolutions:
   • confirmed — derivation completed AND counterexample construction failed
   • rejected — counterexample constructed (the claim is false; plan needs revision before continuing)
   • inconclusive — derivation incomplete due to missing axiom / ambiguous spec / convention conflict; attach the missing piece as an empirical probe: routing back through Step 2.A. ("Code it up and check at implementation time" is not valid — use the numerical-derivation lane.)
   • deferred — outside current scope; attach reason and resolution-point

A rejected derivational hypothesis is a plan bug. Correct the plan and re-derive before Step 3. A plan that attaches deductive properties to examples without reproducing the derivation fails this step.

Step 3 — Consolidate into implementation plan

Merge Step 2's results into a single plan with the following sections.

Failure scenarios

Write this section first, then run the review this section ends with, and design the Plan body against the section as that review leaves it.

The section is a table with one row for each failure scenario the plan's author identifies, a failure scenario being an input the change handles, or an operation someone performs on the change, together with one way it goes wrong. Its columns are Scenario, Occurs, Severe, Detected, Covered, and Handling. Each of the three axes, Occurs, Severe, and Detected, takes a value with the fact it rests on, judged on the change without any Handling this table proposes:

• Occurs — ruled out when a constraint makes the scenario impossible, the constraint cited in the row, for example a type, a caller contract, or a check that runs before the change sees the input. Otherwise yes when the run holds one of three kinds of evidence that the scenario happens in actual use: (1) a record of it happening that a reader of the plan can open, for example an issue, a review finding, or a linked run; (2) a record of it happening that the reader cannot open, such as a local run transcript; (3) the fact that someone can produce it without departing from the procedure they follow. A user passing a wrong argument departs from no procedure; an agent altering a command a skill directs does, so that scenario needs a record. Otherwise no. A row whose Occurs rests on a record cites a record of the first kind, or states the fact a record of the second kind shows.
• Severe — yes when the failure's effect cannot be undone by the means available after the failure, for example a post to an external service, or a deleted file that no commit holds. Otherwise no.
• Detected — yes when the failure surfaces at the step where it happens, as an error or a visible wrong output; a failure a pipe or a discarded stream hides is not detected. Otherwise no.

Covered is no when Occurs is ruled out, or when Occurs is no, Severe is no, and Detected is yes. It is also no when the scenario is produced only on purpose, by someone who can produce it directly without passing through a guard against it, as a malicious user of a local tool can. Otherwise it is yes.

Handling applies to a covered scenario, and is none otherwise. It either supports the scenario's input or operation as it arrives, or detects the scenario and fails with a message that names it. For a scenario that arises from departing from instructions an agent executes, that support or detection is a mechanism that does not depend on the agent reading prose: for example, a script that detects its own failure and prints it as a status line, or a hook that detects the command shape and blocks it. When the change, without any Handling this table proposes, already detects the scenario and fails with a message that names it, in the form this paragraph requires of a Handling, that existing behavior is the row's Handling, and the plan adds no guard for it.

A change that handles no input or operation says so in place of the table.

The section is accurate for the change when every Occurs, Severe, and Detected cell, and the fact each such cell rests on, is true; every Covered cell holds the value the Covered rule gives; its statement that the change handles no input or operation, where it makes one, is true; and every scenario that a scenario record of the first or second kind of Occurs evidence shows happening, and that the Covered rule makes covered, has a row.

The scenario definitions are this section's definitions of a failure scenario, of the three axes, of Covered, of Handling, and of accurate, and its statement for a change that handles no input or operation. The scenario records are the records the run holds, other than review findings raised in the run, that the table cites, whose facts the table states, or that report a scenario happening; a record that a review finding cites is one the run holds from then on.

Then dispatch a fresh-context subagent once, with the section as written, the scenario definitions, the scenario records, the hypotheses Step 2 confirmed, the task, and the repository path. Ask it whether the section is accurate for the change, and whether any Handling contradicts how the system is actually used. Revise the section by each point it raises that is correct.

Hypotheses

One row for each hypothesis Step 2 decided, with columns Hypothesis, Kind, Decision, Falsifier, and Disconfirming probe. The Hypothesis cell states the claim the Decision applies to, and the Decision cell holds one of the four labels. The last cell holds what ran and its result, a derivational hypothesis's counterexample attempt among them, or why none ran.

Plan body

• Checklist of changes with exact file paths, function signatures, type definitions
• Impact list: every caller affected and its implicit contract (for use in implementation verification)
• Test plan:
  • Invariants the new/changed code must satisfy
  • Tests to add/modify with expected behavior
  • For new constructors / input paths: tests passing those inputs through every existing public API that could receive them. A new input path without cross-API tests is incomplete.
  • Surrogate-probe re-instantiation: every hypothesis confirmed in Step 2 by a surrogate probe (proof-of-concept build, reference implementation, toy fixture standing in for the committed artifact) must emit either an artifact-level Test plan entry that re-runs the check against the committed artifact, or an explicit surrogate evidence suffices because <reason> line.
  • Perf acceptance criterion (perf-motivated tasks only): an end-to-end benchmark that provably exercises the changed path, with a before/after (or feature-off/on) comparison, carried forward as a first-class acceptance criterion with the same status as a correctness test. A component-level microbenchmark proves the component win, not the operation win, and does not discharge this. When the win is conditional (neutral on the default build, paying off only under a feature flag / accelerated backend / specific input class), state where it lands rather than implying an unconditional speedup.
• Implementation guards (from confirmed hypotheses; a guard of any kind below that acts against an input or an operation is listed only for a covered row of the Failure scenarios table, its entry naming that row, and the guard implements the row's Handling):
  • New invariants enforced with assertions, not comments
  • Paired APIs that must stay consistent (sibling methods)
  • Constructor validations required
  • State that needs an explicit field rather than heuristic inference
• Derivations (from confirmed derivational hypotheses): for each specific example whose properties were claimed in the plan, reproduce the derivation in compressed form (defining equations → steps → conclusion). The plan reader should be able to retrace the deduction without re-running Step 2.B.
• Conflicts or dependencies between hypotheses (if any)

Inconclusive / Deferred items (REQUIRED section)

This section is mandatory. Every hypothesis Step 2 decides inconclusive or deferred has an entry in it.

## Inconclusive / Deferred items

- inconclusive — <hypothesis>
  probe: <next investigation: git blame, runtime observation, etc.>
  expected branches:
    - if probe yields X → continue per plan
    - if probe yields Y → re-plan trigger (return to research)

- deferred — <hypothesis>
  reason: <why postponed>
  resolution-point: <when this becomes actionable>

If none, write Inconclusive / Deferred items: none identified explicitly.

Filter unresolved questions before listing them

Before escalating a sub-decision to the user as "unresolved":

1. Workspace patterns — search the workspace (rg, fd) for analogous constructs. If the workspace consistently does X, that is the answer.
2. Memory and prior conversation — check available memory entries and recent turns for decisions on the same axis.
3. Step 2 results — re-read Step 2 output. A recommendation a confirmed hypothesis backs is resolved unless contradicted elsewhere.

A sub-decision is genuinely unresolved only when the above are silent or contradictory. "More than one technically-viable option exists" is not unresolved — it is analysis you owe the user. When you do escalate, state what you checked.

Report the plan back to the main context.

Step 4 — Reachability check (mandatory)

A plan can be locally closed yet reach further than the author reasoned about — a new public surface whose semantics depend on consumer code outside scope (Checks 1–3), an enablement that binds compilation units the plan never named (Check 4), a verification probe that covers fewer build configurations than the obligation spans (Check 5), or a performance probe that exercises fewer code paths than the changed path it is trusted to measure (Check 6). codex-plan-review and author confidence both miss these — they require looking outward. Any check firing means the plan's reach is not closed; rescope or defer.

Check 1 — Dead-on-arrival state

For each new public symbol (parameter with non-trivial value range, struct field, accessor, method, variant), ask: does any current or in-plan code path branch on this symbol's value (match, if, conditional dispatch, layout reorder, validation)? Pure references — Clone copying, accessor exposure, constructor storing — are not branches.

• Real branch exists → proceed.
• No real branch → dead-on-arrival. Either expand scope (add consumer-side branching to the checklist) or defer the symbol until the consumer materializes.

Check 2 — Docstring-vocabulary scan

Grep the plan body and proposed docstrings (case-insensitive):

not yet honored | currently restricted | social contract | deferred (mitigation|consumer-side|to a later)
documented limitation | for future use | in preparation for | analogous to ... cascade
in a future PR | follow-up issue tracks | when consumers ... | until consumers ...

Each hit admits an out-of-scope dependency. Each must resolve into a Depends on #N link (carried in Inconclusive / Deferred items), a scope expansion, or a defer / close decision. Hits without a resolution route → return to Step 1 and rescope.

Check 3 — Local-closure vs contract-closure distinction

Restate the plan's claim in one sentence. Would it still be true if every line of consumer code outside the plan were arbitrary?

• Local closure: "constructor stores the data correctly and propagates the order tag" — true regardless of consumers.
• Contract closure: "constructor produces a tensor that downstream operations interpret correctly under the declared order" — only true if consumers honor the tag.

If the user-visible value rests on contract closure and contract closure is out of scope, the plan is mis-scoped. Bring contract closure in or step back to the upstream design decision.

Check 4 — Shared-scope config reach

When the plan enables a lint / setting / config entry at a shared scope (Cargo [workspace.lints] or package [lints], a workspace / package / global config file, a compiler-wide flag, any setting inherited by more than the one unit being changed), enumerate every unit the scope mechanically binds and confirm the intended target matches the actual reach.

For Cargo, a package [lints] table — including [workspace.lints] inherited via [lints] workspace = true — binds every target kind of that package: lib, bins, integration tests, benches, examples, and the build script (build.rs). Each is a separate compilation unit, not just the library. ([workspace.lints] binds only member packages that opt in with [lints] workspace = true.)

• Reach matches intent → proceed.
• Reach exceeds intent (the setting is meant for the library but the scope also binds test / bench / example / build-script units) → resolve one of two ways, never by silent acceptance: (a) narrow the scope to a per-unit attribute (e.g. per-lib #![deny(...)]); or (b) bring every bound unit into the Step 3 impact / test plan and verify each satisfies the setting. A bound unit that is neither narrowed out nor verified is an unresolved item, not an accepted one.

Check 5 — Verification-config representativeness

When the plan's safety rests on a probe — "it builds", "the tests pass", "the cycle compiles" — and the same source is compiled under more than one non-interchangeable configuration (Rust --cfg test vs the non-test build, a feature-gated vs ungated build, C / C++ translation units compiled with macros that change a type's layout or ODR identity, a distinct target / arch), a passing probe under one configuration does not certify a sibling. The configurations look interchangeable but can produce distinct type instances / ABIs, so an obligation that binds in configuration B is untouched by a probe that ran configuration A.

Identify the configuration where the new obligation binds and confirm the probe exercises THAT configuration:

• Probe runs the binding configuration → proceed.
• Probe runs only a sibling ("does it build", an integration target linking the non-test build, the ungated build) while the obligation binds elsewhere (the crate's own --cfg test unit tests, the gated build) → not certified. Name the binding-configuration probe and add it to the Step 3 test plan, or step back to a structure that keeps the obligation inside one configuration.

Check 6 — Benchmark-reach check

When the plan cites a benchmark (existing or new) as evidence for a performance claim, confirm the benchmark provably executes the changed code — inputs that hit the changed branch, not a fast-path that bypasses it. A benchmark that misses the changed path reads as coverage but certifies nothing about it — worse than no benchmark, because "benches pass" looks like confirmation. A component-level microbenchmark is not an end-to-end reach: it proves the component win, not that any operation dominated by the changed path improved.

• Benchmark provably reaches the changed path → proceed.
• Benchmark misses it (fast-path bypass, inputs that never enter the changed branch), or the only evidence is an isolated-component microbench → not certified. Add an end-to-end benchmark that reaches the path to the Step 3 test plan, or name the different public operation — one dominated by the changed path — that will serve as the perf probe.

Output: clean (proceed to Step 5) or flagged (list firings + proposed resolution + surface to user).

Step 5 — Plan review gate (mandatory offer)

After Step 3 produces a plan and before Step 6 collects user approval:

1. Always offer codex-plan-review — never silently skip. Phrase it as a recommendation, not a question:

   "Plan ready. Recommend running /codex-plan-review before approval; type skip to bypass, or anything else to run it."

2. If review runs: triage the findings; a finding the triage closes is a concern of neither kind below, and one it holds as opens-a-question is a premise concern, whichever kind the distinction below would give its content.

   • Implementation concerns (algorithm details, error handling, test coverage gaps, naming): patch the plan in place and proceed to the loop gate below.
   • Premise concerns (the assumed root cause may be wrong, the described mechanism doesn't match how the code actually fails, a fixture's claimed properties may not hold, an "obvious" derivation is unproven): return to Step 1. Do not patch the plan in place — the hypothesis set itself is suspect, and incremental edits perpetuate the bad premise across iterations.

   Distinguishing the two: an implementation concern asks "given the plan's assumptions, is the proposed approach sound?"; a premise concern asks "are the plan's assumptions actually true?". If the reviewer would have given a different answer with empirical evidence in hand, it's a premise concern.

3. Loop gate: after patching, re-run codex-plan-review per its Step 4 re-run rule. Exit the loop when the last valid verdict is approve or approve with conditions. Cap: 3 iterations within the same premise. If the cap is reached, or if the loop sits at reject with no further re-run warranted, surface the verdict and outstanding findings to the user and ask whether to proceed as-is, patch further manually, or escalate. Premise concerns return to Step 1 and reset the counter — iteration count is per-premise, not lifetime.
4. The plan that exits this step is the contract. Step 7 posts that plan once and does not revise it afterwards; there is no "post then revise" loop. Every revision — this step's, the user's at Step 6, a discharge, a gh-body-audit fix — happens before posting.

Step 6 — User approval

Discharge the plan's evidence claims per gh-body-conventions § Evidence claims.

Then run gh-body-audit on the plan body with artifact kind issue. Any ⚠ blocks presenting the plan on gh-body-audit step 4's terms.

Present the plan and ask for approval before posting to GitHub.

If the user requests changes, revise, re-discharge the plan's evidence claims, re-run gh-body-audit, and re-show.

Step 7 — Post plan to GitHub

Route the plan as last approved at Step 6 based on what $ARGUMENTS resolves to:

• Existing single-scope issue → gh-post issue comment $ARGUMENTS (per file-issue step 6) with the plan as body.
• Existing umbrella issue (the body contains a Phases table or sub-tasks list) → spawn a new sub-issue whose body IS the plan, following file-issue's Variants > Umbrella sub-issue shape: Parent: #<umbrella> on the first line, Phase N: <topic> title, Goal / Scope / Out of scope / Acceptance derived from the plan. After creation, append the new sub-issue's number to the umbrella's Phases table row. Do not also post the plan as an umbrella comment.
• New task → gh-post issue create (per file-issue step 6) with the plan in the body; report the new issue number.

Where the routed body is derived from the plan rather than posted verbatim — an umbrella sub-issue's Goal / Scope / Out of scope / Acceptance, or one of several issues a multi-commit plan splits into — discharge that body's evidence claims and run gh-body-audit against it with artifact kind issue; any ⚠ blocks filing on gh-body-audit step 4's terms. Show the derived body for approval before filing it; if the user requests changes, revise, re-discharge, re-run the check, and re-show.

When ambiguous, ask the user. Umbrella sub-issue is the D1 default.

Issue creation rules (research-specific; body shape and the language / reference / evidence-claim / exclusion rules come from gh-body-conventions via file-issue):

1. Split issues by commit unit. Each issue corresponds to one atomic, independently committable change. Multi-commit plans become multiple issues with Depends on #N links.
2. No "rejected alternatives" sections unless explicitly requested. The Hypotheses section is not one.