feat(brainstorming): research prior art before design

[Jonksar]

Summary

This PR adds a conditional, tooling-agnostic prior-art research step before
brainstorming proposes design approaches. It addresses the research portion of #2093, follows up on #386, and implements the maintainer's requested direction:
avoid coupling the workflow to GitHub or gh, and explicitly delegate the
research to a subagent.

When a decision depends on unfamiliar or current external knowledge, the skill dispatches one focused, read-only research subagent, asks it to inspect implementation source and tests, and uses the resulting APIs, patterns, edge cases, boundaries, and evidence gaps in the approach comparison. Self-contained work skips the step.

Who is submitting this PR? (required)

Field	Value
Your model + version	OpenAI Codex, GPT-5.6 Sol
Harness + version	Codex desktop with Codex CLI 0.146.0
All plugins installed	documents@26.805.11740; pdf@26.805.11740; spreadsheets@26.805.11740; presentations@26.805.11740; template-creator@26.805.11740; sites@0.1.31; browser@26.721.41059; chrome@26.721.41059; computer-use@1.0.1000502; visualize@1.0.15; frontend-design@local; superpowers@claude-plugins-official 6.2.0; ponytail@4.9.0; gmail@11c74d6b; slack@11c74d6b; figma@11c74d6b; superpowers@openai-curated 11c74d6b; granola@11c74d6b
Human partner who reviewed this diff	@Jonksar — reviewed the complete one-file diff and explicitly approved submission

What problem are you trying to solve?

In a background-job architecture brainstorming session, the untreated agent recommended pg-boss over BullMQ and SQLite from model recall. It dispatched no research subagent, inspected no external implementation or tests, and presented unattributed compatibility and durability claims for a difficult-to-reverse infrastructure choice.

The existing workflow asks for 2–3 approaches but has no conditional point that grounds those approaches in current library/API behavior. PR #386 identified the same gap, but remains GitHub/gh-specific, targets main, has no before/after behavioral evaluation, and has not implemented the maintainer's requested subagent revision.

What does this PR change?

It adds one conditional step after clarifying questions in the checklist, process graph, and detailed guidance in skills/brainstorming/SKILL.md. Research uses the tools available in the current harness, must be delegated to one read-only subagent, and is skipped when project context is sufficient.

Is this change appropriate for the core library?

Yes. The behavior applies to any project making decisions about external technology, APIs, libraries, established practices, or difficult-to-reverse architecture. It is provider- and domain-agnostic, adds no dependency, and
does not promote a third-party service.

What alternatives did you consider?

• Explicit GitHub/gh searches: rejected because it couples core behavior
  to one provider and was the specific concern raised on feat(brainstorming): add research existing solutions step #386.
• A separate benchmarking skill: rejected because research belongs inside
  the brainstorming decision flow and separate invocation was unreliable in
  the untreated eval.
• Inline research: rejected because the maintainer requested explicit subagent delegation and a focused subagent preserves the main design context.
• Research on every brainstorm: rejected because the self-contained control showed that conditional skipping keeps trivial decisions proportionate.

Does this PR contain multiple unrelated changes?

No. The complete diff is one behavior change in one file: 33 additions and 10 deletions in skills/brainstorming/SKILL.md.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• Related PRs:
  • #386 — directly related. This PR implements the maintainer-requested tooling-agnostic, delegated design, targets dev, and supplies RED/GREEN plus task-completion evals.
    GitHub reports maintainerCanModify: true, but that permits obra maintainers to edit the contributor branch; it does not let this contributor take over Vincent-lkm's fork.
  • #1512 — grounds comparisons in named dimensions but does not research current implementation evidence.
  • #724 — proposes a separate multi-agent research skill rather than a conditional brainstorming step.
  • #1911 — closed general open-source reuse guidance; it did not alter or evaluate brainstorming.

Environment tested

Harness	Harness version	Model	Model version/ID
Codex CLI	0.146.0	OpenAI Codex	gpt-5.6-sol
Pier + Codex CLI	Pier 0.3.0 / Codex 0.146.0	OpenAI Codex	gpt-5.6-luna

New harness support (required if this PR adds a new harness)

Not applicable. This PR does not add or modify harness support.

Evaluation

The initial human request was: add the research step described in #2093 to brainstorming, base it on implementation benchmarking, follow the contribution guidance, and validate it with evals.

Three behavioral candidate/control sessions were run after the initial change:

• an initial docs-only attempt
• the refined direct-source/test treatment,
• and a self-contained control.

Three task-completion treatment sessions were also attempted; two produced valid paired comparisons and one was excluded for violating the read-only protocol.

Behavioral evals

Scenario	Research behavior	Result
External baseline	No research subagent	Fail
Initial treatment	One subagent, but docs/issues only	Indeterminate
Refined treatment	One subagent inspected source and tests	Pass, 7/7
Self-contained control	Correctly skipped research	Pass, 5/5

Task-completion evals

Task	Baseline	Research	Outcome
HTTPX cookie store	Reward 0; 1,395/1,396 tests	Reward 1; 1,396/1,396 tests	+1 exact solve
GraphQL incremental delivery	Reward 0; 826/828 tests	Reward 0; 827/828 tests	+1 feature test
Aggregate	0/2 solved; 2,221/2,224 tests	1/2 solved; 2,223/2,224 tests	Runtime +25.8%; cost -0.2%

These were one-attempt Luna smoke runs on a targeted DeepSWE subset, not an official score or statistically stable estimate. The FastAPI treatment was excluded when its subagent edited the shared worktree; Yaegi passed at baseline and therefore skipped treatment; KGateway failed during Docker image creation before the model ran.

Rigor

• If this is a skills change: I used superpowers:writing-skills and
  completed adversarial pressure testing
• This change was tested adversarially, not just on the happy path
• I did not modify carefully-tuned content (Red Flags table,
  rationalizations, "human partner" language) without extensive evals
  showing the change is an improvement

The external scenario concealed the desired research behavior and added time pressure while asking for a difficult-to-reverse infrastructure recommendation. The RED run made a confident recommendation with zero delegation. The first
GREEN wording exposed a loophole—documentation and issues were treated as implementation evidence—so the wording was tightened to require direct source and test inspection. The refined run then passed 7/7 deterministic checks. A counter-scenario verified that the conditional did not over-trigger for a self-contained wording decision.

Human review

• A human has reviewed the COMPLETE proposed diff before submission

@Jonksar explicitly confirmed review of the complete diff and approved creating
this PR after comparing it with the stalled #386.

[Jonksar]

I've used a research skill in brainstorming flow extensively since generated proposals are often not grounded in best practices and models can learn a lot by reading established code (e.g. patterns used, naming schemes, tests to write, libraries to use) reducing the amount of code agents have to invent.

The implemented change is meaningfully smaller and targeted than my typical flow, and if maintainers agree with direction we could add a separate /research-implementations skill separately that I most often use to ask the agent to refine /brainstorming questions.

[obra]

Full review done (security + code review against current dev). Direction affirmed — this is the feature @obra asked for on #386, it's built correctly on top of the v6.3.0 three-path router, and the structural work is clean (architectural-path-only insertion, correct DOT wiring, complete renumbering, disciplined scope). Requesting changes on five substantive points before it can land:

1. Re-key the trigger to an observable predicate. The step currently fires on 'unfamiliar... external knowledge' and skips when 'current project context is sufficient' — both are the model's self-assessment of its own recall, which is exactly the faculty that failed in your motivating case (the confident-but-stale pg-boss recommendation didn't feel unfamiliar). Key it to something checkable instead: the decision introduces or replaces an external dependency, is difficult to reverse, or depends on version-sensitive API behavior. Note your eval battery has no arm for 'external decision on tech the model believes it knows well' — that's the arm that would falsify the current predicate, and the one an updated battery most needs.

2. Use recipe form, not prohibition form. writing-skills ('Match the Form to the Failure') found positive recipes beat prohibition lists head-to-head for wrong-shape output — and your Indeterminate arm was a wrong-shape failure. Replace 'not only READMEs, documentation, issue threads...' with the recipe: what the subagent must report (reusable patterns, APIs, edge cases, boundaries — each with a source-file citation from the external project's implementation and tests). That also fixes an ambiguity: the current sentence never says whose source files, so an agent can satisfy it by re-reading the local repo. Same doctrine says drop the 'if subagent dispatch is unavailable...' nuance clause.

3. Measure read-only compliance instead of excluding its failure. The one treatment run where the research subagent edited the shared worktree was excluded — but that's the safety-relevant datum: observed violation rate 1 in 3. The revised eval needs a measured compliance rate at N≥10 with write detection, not an exclusion footnote.

4. One gate, one phrasing. The trigger condition appears in three different wordings (checklist item, DOT diamond, prose bullet) and the skip criterion in two ('self-contained work' — undefined vocabulary here — vs 'current project context is sufficient'). Pick the single predicate from point 1 and mirror it verbatim in all three places.

5. Eval coverage: Claude arm, and reps. All sessions were Codex-family; the shipped wording has one passing session behind it and the skill's primary consumer was never tested. Rerun RED/GREEN on current Claude Code (Gemini too if you can), N≥5 per arm, with the point-1 adversarial arm included, and re-check the runtime cost — +25.8% sits right on a documented maintainer prior (3f80f1c removed subagent loops from this skill for exactly that overhead profile).

Minor, while you're in there: spaced em-dashes (the file is 43/43 ' — '; your additions use unspaced), and tighten altitude — sibling checklist items run 6-13 words, the new one ~40.

This was already the strongest outside submission of the window; with the predicate re-keyed and a battery behind the actual wording, it gets over the line.

— Claude Fable 5, Claude Code 2.1.228, reviewing on behalf of @obra