research-design-helper

research-design-helper

Stage 3a (sharp problem framing) and front-of-Stage 4 (model design) helper. Part of the research-hub skill pack — works alongside Zotero, Obsidian, and NotebookLM workflows but does not require any of them. Domain-agnostic Socratic guide that walks a researcher through 5 short segments and saves the result as .research/design_brief.md.

The skill does not invent your research question or model design. Like research-context-compressor, it leaves blanks rather than guess. Its value is structured prompting: forcing you to articulate what you'd otherwise leave implicit, before you spend weeks coding.

When to use

Trigger phrases:

• "Frame this research question."
• "Design my study before I start coding."
• "Help me think through what model to build."
• "Sharpen my hypothesis."
• "Walk me through the design."
• "Build a design brief."

Not for:

• Writing actual model code (that's the user's work, optionally with codex-delegate for boilerplate).
• Project context manifests (that's research-context-compressor).
• Literature comparison (that's literature-triage-matrix).
• Manuscript writing (that's academic-writing-skills).

Inputs

In priority order:

1. .research/project_manifest.yml if it exists — for project context (research_question may already be partially filled).
2. .research/topic_dossier.gaps.yml if it exists — Stage 2 handoff from gap-to-topic (plugin v0.3.12+). Inspect candidate IDs/names/verdicts to identify eligible options; after the user's actual selection, read only that gaps[] entry plus top-level open_questions[], NOT the whole corpus. go and conditional-go are eligibility assessments, not proof of selection. Use a clear prior user choice without asking again; if absent or ambiguous, ask even when only one candidate is eligible. The workflow §0 then pre-fills segment 1 (RQ) from gaps[].statement and segment 5 (risks) from open_questions[] + gaps[].feasibility. If supplied, also read that selected candidate's optional .research/topic_dossier.direction-review.json record and applicable resource records as described below; its absence does not block the legacy dialogue.
3. .research/design_brief.md if it exists — for refresh, not first-run.
4. .research/literature_matrix.md if it exists — for prior-art context when discussing identifiability.
5. The user's free-text answers during the conversation.

Do NOT scan code, data, or PDFs. This is a conversational skill.

Workflow

§0 — Detect Stage 2 handoff (gap-to-topic)

Before starting the Socratic dialog, check whether .research/topic_dossier.gaps.yml exists.

• If absent → behave exactly as before (skip to the 5-segment table below; no regression for users who run this skill standalone).
• If present → filter gaps[] to entries with verdict in {conditional-go, go} as assessed eligible options. A no-go is an assessment, not a user's decision to reject it. Preserve actual user choice; do not infer it from a verdict, a single option or packet validity. Then:
  • Filtered list has exactly one entry → it is eligible, not automatically chosen. If no clear prior user selection exists, ask "Would you like to design this candidate, or revisit the options?" before writing a brief. Only after the user selects it, auto-pre-fill:
    • Segment 1 (RQ) ← write gaps[].statement verbatim into the Sharpened RQ field, replacing the template's _TODO_ placeholder. Do not add any _PRE-FILL_-style annotation inside the file content — the chat message below is where you signal "this is pre-fill, sharpen me". Keeping the file content clean means segment 1 dialog can simply overwrite the statement with the sharpened RQ; no later cleanup step is needed. The Falsification condition and Smallest answerable version sub-fields stay _TODO_ — those only get filled during segment 1 dialog.
    • Segment 5 (Risk register) ← one row per entry in open_questions[], plus a row for the specific concern indicated by gaps[].feasibility (e.g. feasible-with-effort → a "binding constraint" risk row).
    • Tell the user (chat message, not in the file): "I pre-filled segment 1 (RQ) from gaps[<id>].statement and segment 5 (risks) from open_questions[] + the feasibility: <value> hint. Segment 1's Sharpened RQ is a starting point — segment 1 dialog will sharpen it into an answerable form appropriate to your field. Review and revise as we walk through."
  • Filtered list has 2+ entries → use an actual prior user selection if clear; otherwise ask "Which candidate are we designing for?" before pre-filling. Do not invent a selection or choose by score/order.
  • Filtered list is empty → explain "No viable candidate has been assessed in this dossier yet." Give the reasons and a bounded revision/reassessment path; do not treat unknown as a demonstrated scientific failure or claim the user rejected every idea. Do not auto-start a design brief.
  • Explicit user choice names a no-go option → preserve that actual choice and surface the blocking assessment; discuss revision/reassessment before treating it as design-ready. Never silently substitute another candidate.
• Segments 2 (mechanism), 3 (identifiability), 4 (validation) are NEVER pre-filled. The .gaps.yml doesn't carry that material; pre-filling those segments with non-content corrupts the Socratic dialog. Leave them blank → _TODO_ until the segment runs.
• Provenance. When you write .research/design_brief.md, fill the frontmatter source: field with topic_dossier.gaps.yml#<gap-id> (e.g. topic_dossier.gaps.yml#G2) and the gap_verdict: field with a frozen snapshot of verdict + the first 60 chars of verdict_reason. This makes the brief self-contained — a future reader sees which dossier candidate this design was framed for.
• Optional direction-review handoff. For the selected candidate, preserve the supplied candidate_version, reviewed candidate-content hash, review path, and unresolved material/resource limitations in the brief's Notes. Missing versions stay unknown; do not assume version 1. A missing review leaves the standalone/legacy dialogue available. A stale candidate version/content binding or changed source bytes requires rechecking the affected assessment before relying on it; keep the old record and do not silently carry supported forward. Carry unknown/contradicted items, their reasons and bounded next checks into the risk discussion; a justified not-applicable is valid for work that does not need that prerequisite. If binding has not been checked, say so rather than treating a matching ID as verification. The checker only checks supplied records, source-byte bindings and resource estimates: it does not establish semantic support, select the candidate, authorize execution or prove scientific feasibility. within-estimate is not verified runtime spending. See docs/direction-review-contract.md in the research-hub repository for the optional checker contract.

§1 to §5 — the 5 Socratic segments

Run the 5 Socratic segments in order, one at a time. For each, ask the listed questions, capture the user's answer, then save verbatim to the corresponding section of .research/design_brief.md. If the user can't answer a segment yet, write _TODO: <reason>_ and move on; do not fabricate.

Adapt the prompts to the research type. Do not require an empirical study, hypothesis, causal mechanism, predictive model or LLM; a justified not-applicable is preferable to inventing one. Preserve the five section headings, using field-appropriate questions about evidence or argument where needed. An unresolved answer is _TODO_, not not-applicable. Explicitly record the intended claim and time boundary, a matched-information comparison where applicable, the researcher's minimum worthwhile gain, and the smallest answerable version with its nonclaims. Narrowing countries, periods, populations or objectives requires the user's choice. Only describe a reduced design as expected executable when its necessary materials, essential comparisons and resource needs fit confirmed available resources; otherwise record the constraint and next check. A fixed duration or successful prototype is not a universal feasibility threshold.

Segments + their prompts: references/socratic-segments.md.

#	Segment	What it produces
1	Research question sharpening	answerable RQ + claim/time boundary + smallest answerable version and nonclaims
2	Expected mechanism	mechanism or argument + uncertainty annotations, as applicable
3	Identifiability check	discriminating evidence + alternative explanations + missing-material plan
4	Validation plan	assessment criterion + matched-information comparator + minimum worthwhile gain + control, as applicable
5	Risk register	3–5 risks each with early-warning + mitigation

Output: .research/design_brief.md

Use the template at references/design_brief_template.md (sibling file in this skill). Fill the 5 sections with the user's answers verbatim. Frontmatter is required:

project: <from project_manifest.yml or asked at start>
last_updated: <ISO date>
stage: design
status: draft     # draft | reviewed | locked

If the file already exists, update don't replace: keep human-edited sections intact, only fill blanks unless the user explicitly says "regenerate from scratch".

Provenance protection (v0.3.12+). If the existing design_brief.md has frontmatter source: topic_dossier.gaps.yml#<old-id> and a different gaps[] entry is now being chosen (different id, OR .gaps.yml generated: date differs), ASK the user before refreshing — do not silently overwrite provenance. Phrasing: "This brief was originally framed for <old-id> (<old-verdict>). You have now chosen <new-id> (assessed <new-verdict>) from the current .gaps.yml. Refresh and replace the provenance, or keep the old brief and start a new one?"

Apply the same protection when a recorded candidate version or candidate-content hash changes. Preserve human-edited answers and the previous review limitations; ask before replacing provenance, and leave affected design claims unresolved until the revised materials have been checked. Do not silently change the research question to fit a budget or an available outcome.

Placeholder marker (v0.3.15+). When any segment is filled with test-fit / dogfood placeholder content (e.g. an AI-generated stub written to exercise the Stage 3a → 3b wire without a real Socratic dialog), record those segment numbers in the frontmatter placeholder_segments: list. Example: placeholder_segments: [2, 3, 4] means segments 2–4 are placeholders, not from the researcher's actual answers. Downstream tools should refuse to gate real research on a brief with non-empty placeholder_segments. When all 5 segments are filled by genuine Socratic dialog, leave the list empty ([]). This pattern was added after the v0.3.12 dogfood, where segments 2–4 were written as test-fit content to validate the wire — a future reader needs a machine-checkable signal that those segments aren't advisor-ready.

After saving, print a short report:

[research-design-helper]
  Wrote: .research/design_brief.md
  Sections completed: 4 / 5 (Risk register marked _TODO_ — circle back)
  Strongest spot: Identifiability check — clear discrimination via negative control.
  Weakest spot: Validation plan — baseline not yet specified.
  Suggested next: refine the validation baseline, then re-run with "regenerate from scratch" to lock the brief.

Generate .docx (optional, plugin v0.3.14+)

After writing .research/design_brief.md, an optional Word version can be generated via the sister script at scripts/brief_to_docx.js. The .docx is a convenience for sharing the brief with advisors / committee members who prefer Word — it is NOT part of the contracted Stage 3a output and is not consumed by downstream skills (Stage 3b reads design_brief.md frontmatter + §1 directly).

# From the directory that contains design_brief.md:
node /path/to/skills/research-design-helper/scripts/brief_to_docx.js design_brief --no-toc

# zh-TW variant (auto-selects Microsoft JhengHei):
node /path/to/skills/research-design-helper/scripts/brief_to_docx.js design_brief.zh-TW --no-toc

Prerequisite: npm install -g docx (one-time). The --no-toc flag is recommended for design briefs — they're typically short enough that Word's auto-generated empty TOC field is more distracting than useful.

The script is a near-byte copy of the gap-to-topic scripts/dossier_to_docx.js generator (same Markdown → Word logic, same font auto-selection, same separator-row skip). The dossier's verdict-colour regex is inherited verbatim but does not fire on design brief content — see scripts/README.md for the rationale.

Token-saving behavior

• Don't repeat the user's answers back at length — quote in the written brief, summarize one sentence in chat.
• Don't dump the whole template into the chat — write the file, then report which sections were filled.
• Skip segments the user can't answer; record _TODO_ and move on. The point is not to complete every section in one session — it's to surface the gaps.

What NOT to do

• Do NOT invent the research question. If the user is vague, surface the vagueness; do not fill it in for them.
• Do NOT propose model architectures or technologies. That's Stage 4 implementation work, owned by the user with help from codex-delegate for boilerplate. This skill stops at the spec.
• Do NOT write to .paper/ — that's paper-memory-builder.
• Do NOT touch .research/project_manifest.yml — that's research-context-compressor. The two are complementary; the manifest captures STATE, the brief captures DESIGN INTENT.
• Do NOT skip segments silently. If a segment is blank, the brief must say _TODO_ so future sessions (or the orienter) can flag it.

See also

• references/socratic-segments.md — full prompts for each of the 5 segments
• references/design_brief_template.md — Markdown template for the output file