Docs › Skills › Research Design

Research Design

From investigation to implementation plan. Maps paper equations to code components, assesses regression risk, and fires Gate 2 before any implementation begins.

Overview

The Research Design skill bridges the gap between understanding a problem (investigation) and building a solution (implementation). It reads the investigation README and paper notes, then produces a concrete implementation plan with explicit paper-to-code mappings and regression risk assessment.

Requires Completed Investigation

This skill refuses to proceed without a completed investigation in scratch/ that has passed Gate 1. If no investigation exists, Claude will redirect: "I need to investigate before I can design."

Property	Details
Trigger	"propose how to", "design the implementation", "plan the architecture", "how should we implement"
Active Modes	Engineer
Prerequisite	Investigation with Gate 1 completed
Output	`scratch/{investigation-name}/design.md`

Design Process

The design process follows five sequential steps, each building on the previous.

Step 1: Read Context

Read the investigation README including "Design Decisions (Human-Approved)"
Read any referenced paper notes from scratch/paper-notes/
Read any relevant registry entries from scratch/registry/

Step 2: Paper-to-Code Mapping

Create an explicit mapping for each new component (see format below).

Step 3: Regression Risk Assessment

Identify what existing behavior must remain unchanged (see details below).

Step 4: Design Proposal

Write the full design with component order, paper references, and explicit "will NOT change" statements.

Step 5: Gate 2 G2

Present the plan to the user and ask design questions before proceeding to implementation.

Paper-to-Code Mapping

For each new component, create an explicit mapping between the paper reference and the code it will become. This table is the contract between the paper and the implementation.

Paper Reference	Code Component	Files Affected	New/Modified
Eq. 3 (commitment loss)	`compute_commitment_loss()`	model/losses.py	New
Fig. 2 (encoder architecture)	`ResidualEncoder` class	model/encoder.py	Modified
Alg. 1, line 5 (codebook update)	`update_codebook()`	model/vq.py	New

This mapping serves two purposes: it ensures every paper element is accounted for in the implementation, and it gives the paper-alignment-auditor a checklist to verify against after implementation.

Regression Risk Assessment

Before proposing any changes, identify what existing behavior must remain unchanged:

Which existing configs must produce identical results?
Which code paths are shared between old and new functionality?
Where are the coupling points between new and existing code?
Config flags for new features — new features are opt-in, existing configs unchanged

Component Ordering

Order components to minimize regression risk: new code paths first, then modifications to existing paths. This way, if something goes wrong during implementation, existing functionality is still intact.

Gate 2: Post-Design Checkpoint

Gate 2 is the mandatory checkpoint before any implementation begins. Claude must present the plan and ask questions.

## Implementation Plan Summary

### Components (in order)
1. [Component] — maps to paper eq. [X] — touches files [Y, Z]
2. ...

### Regression Risk Assessment
- [What existing behavior could break, and
  how we're protecting against it]

### What I'm Uncertain About
1. [Specific uncertainty + two options +
   why I can't decide without your input]
2. ...

### Estimated Scope
- [N] components, [M] files modified, [K] new files
- [Which components are independent vs. sequential]

Gate 2 Question Guidelines

Gate 2 questions must be about specific, actionable concerns:

Implementation order: "I've ordered to minimize regression risk, but the most interesting part comes third. Do you want to see the core component first instead?"
Uncertainty resolution: "The paper doesn't specify [X]. I see two options: [A] or [B]. [A] is [trade-off]. [B] is [trade-off]. Which do you prefer?"
Scope confirmation: "This plan modifies [N] files. I've kept [these files] untouched. Should any of the modified files also be off-limits?"

Gate 2 Rules

The plan must be specific enough that the user can reject individual steps
Claude must explicitly state what it will NOT change
If the plan is more than ~10 tasks, ask whether to split into multiple sessions
User approves the plan (possibly with modifications) → proceed to writing-plans for micro-task breakdown, then to implementation