# User Interaction

> Defines the checkpoint protocol for the elegant-researcher-skill pipeline. Use at major research transition points to summarize artifacts, show options, apply mode-specific defaults, and continue without blocking routine decisions.

- Skill: `ttawdtt/user-interaction` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ttawdtt/user-interaction`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ttawdtt/user-interaction/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: MIT
- Author: ttawdtt (https://skillmd.com/u/ttawdtt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ttawdtt/user-interaction

---


# User Interaction

This skill controls how the elegant-researcher-skill pipeline involves the user.

## Principles

1. Never ask about routine decisions.
2. Present a short decision summary, not raw files.
3. Every checkpoint has a default route.
4. Defaults depend on the selected mode.
5. If the user says "keep going", follow the default.
6. In autonomous modes, do not wait unless there is a true blocker.

## Modes

| Mode | User Interaction Behavior |
|---|---|
| `quick-cycle` | Minimal checkpoints; use defaults quickly |
| `deep-cycle` | Present checkpoints, but continue with defaults when user gives no direction |
| `paper-ready` | Ask only when full results, venue, or citation status affects claims |
| `theory-only` | Skip experiment handoff; focus on theory and proposed experiments |
| `human-in-loop` | Wait for user decisions at checkpoints |

## Checkpoint Format

Each checkpoint response should include:

```text
## [Checkpoint Title]

Status: [one sentence]
Mode: [mode]
Evidence level: [highest relevant level]

Key artifacts:
- [path] - [what it contains]

Summary:
- [key point 1]
- [key point 2]
- [key point 3]

Options:
A. [default option] - [route]
B. [alternative] - [route]
C. [alternative] - [route]
D. [alternative] - [route]

Default: A unless mode-specific rules say otherwise.
```

Do not include long raw file contents.

## Checkpoint 1: Literature Map Confirmation

Trigger: literature search and `literature/gap-analysis.md` are complete.

Present:

- field overview,
- method evolution,
- contradictions,
- implicit assumptions,
- candidate gaps.

Options:

A. Continue with the recommended gap.
B. Deepen a specific gap.
C. Adjust literature direction.
D. Switch to theory-only framing.

Default:

- autonomous modes: A.
- `human-in-loop`: wait for user selection.

## Checkpoint 2: Hypothesis Selection

Trigger: candidate hypotheses and `hypothesis-tree.md` are complete.

Present:

- 2-5 hypotheses,
- recommended starting point,
- feasibility and expected information gain.

Options:

A. Start with the recommended hypothesis.
B. Select a different hypothesis or multiple hypotheses.
C. Add a user hypothesis.
D. Brainstorm again.

Default:

- autonomous modes: A.
- `human-in-loop`: wait for user selection.

## Checkpoint 3: Experiment Ready

Trigger: protocols, code, micro-validation, and handoff package are ready.

Present:

- experiment list,
- protocol locations,
- code locations,
- micro-validation result summary,
- handoff instructions,
- evidence level.

Options:

A. Use micro-validation as proof-of-concept and proceed to writing.
B. User will run full experiments; wait for results.
C. Modify or fix experiments, then re-run micro-validation.
D. Switch to theory-only or proposed-experiments path.

Default by mode:

- `quick-cycle`: A.
- `deep-cycle`: A.
- `paper-ready`: B if user has compute and wants empirical claims; otherwise A with full claims marked pending.
- `theory-only`: D.
- `human-in-loop`: B.

This checkpoint must not silently stall autonomous runs.

## Checkpoint 4: Draft Review

Trigger: first draft or research note is complete.

Present:

- artifact type,
- section status,
- figure count,
- evidence levels,
- unresolved citations,
- pending results.

Options:

A. Polish and finalize.
B. Strengthen a section.
C. Integrate new user results.
D. Rethink contribution.

Default:

- autonomous modes: A.
- `human-in-loop`: wait for user review.

## Checkpoint 5: Final Confirmation

Trigger: final artifact is ready.

Present:

- final artifact path,
- key findings,
- evidence levels,
- figure count,
- citation status,
- limitations,
- next recommended cycle.

Options:

A. Mark cycle complete.
B. Deepen a specific aspect.
C. Convert to LaTeX or venue-specific submission.
D. Start a new research question.

Default:

- autonomous modes: A.
- `human-in-loop`: wait for user decision.

## Handoff Package

When full experiments are needed, produce `HANDOFF.md` with:

- exact commands,
- expected runtime,
- required hardware,
- output paths,
- result schema,
- metrics to report,
- common failure fixes.

## Final Response Requirements

At the end of a cycle, the agent must include:

- completion status and mode,
- key findings,
- evidence level per finding,
- output paths,
- reliable vs. preliminary claims,
- limitations,
- next step,
- citation status,
- automation status.