# Loopx Auto Research

> Use when a LoopX worker is operating an auto-research lane, demo pane, frontier item, evidence packet, promotion/retirement decision, or visible tmux/Codex auto-research rehearsal. Identity must come from the LoopX role profile and quota/frontier packet; this skill only provides role-specific execution checklists, artifact contracts, and stop conditions.

- Skill: `huangruiteng/loopx-auto-research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add huangruiteng/loopx-auto-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/huangruiteng/loopx-auto-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: huangruiteng (https://skillmd.com/u/huangruiteng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/huangruiteng/loopx-auto-research

---


# LoopX Auto Research

This is a worker-local role playbook for auto-research panes. It is packaged
with the auto-research capability and should be injected or referenced by the
worker launcher; it is not a global LoopX skill for ordinary project agents.

## Routing Boundary

Use this skill after a LoopX auto-research worker has a role profile,
frontier item, launcher packet, or user-visible demo pane. The skill is the
role playbook. It is not the source of truth for identity, authority, current
frontier, or merge/publication permission.

Identity comes from LoopX control-plane metadata:

- `auto_research_role_profile_v0` in the launcher/frontier/bootstrap packet;
- `quota should-run --goal-id ... --agent-id ...`;
- todo claim, capability token, write scope, and protected scope;
- repository or workspace `AGENTS.md` rules, which can only make the boundary
  stricter.

No role owns the full graph. Do not infer role from pane title, branch name,
tmux window name, or the section of this skill that happens to be visible.

## Pane Tick Contract

The generic multi-agent kernel owns the default LoopX project/doc-registry
skills and the fixed A2A wake prompt. This skill should stay role-specific:
use it after the pane-local tick has resolved identity, quota, and frontier
from LoopX.

Compact frontier command: `loopx --format json auto-research frontier --goal-id "$LOOPX_GOAL_ID" --agent-id "$LOOPX_AGENT_ID"`. Also honor `quota should-run`.

If the launcher exported `LOOPX_ROLE_ID`, `LOOPX_ROLE_PROFILE_REF`, or a profile
JSON path, compare those values with the quota and frontier packets. Stop when
they disagree. Do not guess the intended role.

If the role profile includes `successor_todos`, treat those declarations as the
only role-local way to create the next agent todo. A successor declaration must
name the target agent and include a `todo_command_template` such as
`loopx todo add ... --claimed-by {target_agent_id_shell}`. In visible
auto-research, the pane-local tick is a guard/frontier read, not a research
writer. Render and run a successor todo only after the visible role has authored
real public-safe evidence or notes that satisfy the declared condition. Do not
invent an extra continuation plan in prose, and do not ask a leader pane to pick
the next role.

Before completing with no follow-up, compare the evidence summary with
`role_profile.continuation_policy`. When the target is still unmet and a
declared successor condition is satisfied, create or link that successor first.
No-follow-up is only valid after the target is reached, a projected blocker or
user gate stops the lane, or evidence-backed retirement closes the frontier.

For a visible demo rehearsal, `auto-research demo-supervisor` is read-only by
default; use `--execute` only when the user opted into starting visible local
panes. The default rehearsal must not start Codex, write LoopX state, or spend
quota by itself.

## Role Resolution

Map the role profile to one of these sections:

| Role id or lane | Skill section | Authority source |
| --- | --- | --- |
| `research_curator` | Research curator | role profile, quota packet, contract todo |
| `hypothesis_proposer` | Hypothesis proposer | role profile, frontier packet, hypothesis todo |
| `research_executor` | Research executor | role profile, selected frontier item, write scope |
| `evaluator_promoter` | Evaluator/promoter | role profile, evidence packet, promotion policy |
| `research-narrator`, `product_narrator` | Projection narrator | read-only projection packet and first-screen gate |
| `control-plane-guard` | Control-plane guard | quota/status/check packet and repository rules |

The current demo may render fewer or differently named panes than the four
logical research roles. That is only a host layout choice. Every durable
record should still name the logical role or transition duty that produced it.

## Shared Stop Conditions

Stop and report the exact blocker when any of these are true:

- quota says `should_run=false`, `delivery_allowed=false`, or a user/operator
  gate is open;
- the selected todo is missing, claimed by another agent, or not compatible
  with the profile's `capability_token`;
- the next edit touches `protected_scope`, credentials, private material, raw
  logs, raw evaluator data, or unapproved publication surfaces;
- the profile, frontier, `AGENTS.md`, and this skill disagree;
- the work would require a leader/coordinator agent to select, promote, or
  rewrite the whole graph.

## Benchmark Workspace Hints

When the role profile or workspace exposes a benchmark contract, use that
contract before writing research claims. For KNN-style demos this means:

- read `research_contract.public.json`, `README.md`, and the editable solver;
- edit only the declared editable scope, such as `solution.py`;
- run the declared dev command before proposing promotion;
- run the declared held-out command before claiming a validated improvement;
- summarize mechanism, command, score, and protected-scope cleanliness.
- pass the contract and eval JSON outputs to `loopx auto-research evidence`
  rather than hand-authoring an evidence packet.

The pane-local tick can point at a todo; it cannot count as benchmark evidence.

## Research Curator

Use when the role owns the original research wish, objective, required
artifacts, acceptance criteria, metric, editable scope, protected scope,
budget, and gates.

Allowed actions:

- create or refresh `auto_research_delivery_contract_v0`, embedding the
  existing `research_contract_v0`;
- make protected boundaries explicit;
- write user/operator gate todos when promotion or publication needs judgment;
- request read-only projections from existing evidence.

Useful command:

```bash
loopx --format json auto-research frontier \
  --goal-id "$LOOPX_GOAL_ID" \
  --agent-id "$LOOPX_AGENT_ID"
```

Artifact contract:

- objective is public-safe and bounded;
- the original wish, assumptions, non-goals, and contract reference are
  public-safe and explicit;
- every required artifact and acceptance criterion has a stable public-safe id;
- metric direction and protected evaluator are explicit;
- write scope and protected scope are named;
- promotion policy says what evidence is sufficient.
- failure policy names fallback artifacts and the conditions for re-entering
  research when the current contract cannot be fulfilled.

Must not:

- pick winners;
- run experiments;
- present unsupported metrics as product value.

## Hypothesis Proposer

Use when the role turns ideas into todo-backed hypotheses, refinements,
successors, or retirements.

Allowed actions:

- create `research_hypothesis_v0` records with `todo_id`, `claimed_by`,
  mechanism family, parent link, and grounding refs or no-grounding rationale;
- retire duplicates, exhausted retries, or contradicted directions while
  keeping negative evidence visible;
- add the next bounded agent todo.

Before writing:

- confirm the idea is not claiming novelty from the same source used to ideate;
- confirm the hypothesis can be attempted inside allowed write scope;
- keep todo order and rationale in LoopX state, not only in chat.

Must not:

- delete failures;
- select a winner;
- hide contradictory evidence by replacing a hypothesis with a cleaner story.

## Research Executor

Use when the role runs exactly one selected hypothesis in an isolated
workspace/worktree and records attempt evidence.

Allowed actions:

- claim the current frontier item selected for this agent;
- edit only allowed solution or experiment scope;
- run dev or holdout evaluation only when the contract permits it;
- build an `auto_research_evidence_packet_v0` or equivalent public-safe event;
- create only the role-declared successor todo, such as a holdout validation
  todo or post-holdout verifier summary todo, when the profile's
  `successor_todos.condition` is satisfied.

Successor routing belongs here, not in a central projector: the role profile
must name the target agent and provide the `todo_command_template`, typically a
normal `loopx todo add ... --claimed-by {target_agent_id_shell}` command. The
kernel only validates the target agent and executes the normal LoopX todo
writer.

Evidence writeback should use an explicit lane-authored evidence packet or
normal LoopX todo/evidence commands exposed by the current state. Append only
after reviewing packet boundary, then capture compact live evidence from the
lane-authored packet when visible lanes are accepted. Do not use worker-turn to
manufacture dev or holdout metrics.

After a real append/capture succeeds for the selected frontier todo, close out
that selected todo with compact public-safe evidence. Dependent evaluator or
successor lanes usually resume from `todo_done:<selected_todo_id>`; leaving the
executor todo open after supported evidence strands the next round.

Must not:

- edit protected evaluator/data scope;
- promote results;
- omit failed, inconclusive, or guardrail-failed attempts.

## Evaluator/Promoter

Use when the role reads evidence and classifies it as supported,
contradicted, retry-needed, promotion-ready, or retirement-ready.

Allowed actions:

- run held-out validation only when the selected frontier action is
  `run_holdout_eval` and the contract permits that split;
- apply the contract's metric and promotion policy to scored or unscored
  evidence;
- request retry with a bounded reason and resumable ref;
- create promotion, retirement, or gate candidates;
- write compact validation notes for the next worker;
- add only the role-declared successor todo when evidence needs another bounded
  split, using the profile's `todo_command_template`.
- do not close with no-follow-up while `continuation_policy` still reports an
  unmet target and a role-declared successor condition is satisfied.

Verification checklist:

- split label and metric direction are explicit;
- dev evidence is not represented as held-out proof;
- boundary says protected scope stayed clean;
- negative evidence remains queryable.

When evidence reaches a terminal boundary:

- use `loopx auto-research decide` to record `promoted` or `retired`; a
  promotion candidate is not a terminal result;
- bind the decision to the current evidence graph revision and keep the
  decision evidence refs public-safe;
- use `loopx auto-research review --require-independent` only from a different
  registered peer than both the hypothesis producer and decision agent;
- treat self-review as visible review evidence, never as independent review;
- when the curator supplied `auto_research_delivery_contract_v0`, run
  `loopx auto-research artifact-receipt --contract <contract-file>` after the
  terminal decision and required review;
- return every non-verified receipt to the user with its failure kinds,
  verified boundary, fallback artifacts, and reentry conditions; do not turn
  one failed attempt into a terminal impossibility claim;
- use `loopx auto-research project-results` after decisions and reviews so
  exact `loopx auto-research results` queries can verify Explore readback.

Example terminal path:

```bash
loopx auto-research decide \
  --goal-id "$LOOPX_GOAL_ID" \
  --hypothesis-id "<hypothesis-id>" \
  --outcome promoted \
  --reason holdout_validated \
  --agent-id "$LOOPX_AGENT_ID" \
  --execute

loopx auto-research review \
  --goal-id "$LOOPX_GOAL_ID" \
  --hypothesis-id "<hypothesis-id>" \
  --reviewer-agent-id "$LOOPX_AGENT_ID" \
  --verdict approve \
  --require-independent \
  --execute

loopx auto-research artifact-receipt \
  --contract "<delivery-contract-file>"
```

Must not:

- bypass an owner/operator gate;
- certify a showcase claim;
- rewrite the hypothesis graph to make the result look cleaner.
- label the same producer or decision agent as an independent reviewer.

## Projection Narrator

Use when the role is read-only product narration over accepted projections. This
is a transition duty in v0 and may become a separate role later.

Allowed actions:

- render `research_evidence_graph_v0` from promoted, retired, and retry
  evidence;
- update public-safe docs or Frontstage surfaces only from projection refs;
- preserve failed and retired directions as useful learning.

Useful command:

```bash
loopx --format json auto-research project-results \
  --goal-id "$LOOPX_GOAL_ID" \
  --execute

loopx --format json auto-research results \
  --goal-id "$LOOPX_GOAL_ID" \
  --include-history
```

Must stop before:

- inventing metrics;
- reading private source bodies;
- changing first viewport, hero, primary CTA, or opening nav without the
  first-screen review gate.

## Control-Plane Guard

Use when the role checks whether a visible demo, frontier, evidence append,
merge, or publication action is safe and interruptible.

Allowed actions:

- run quota/status/check packets;
- validate public/private boundary;
- confirm attach/stop/takeover controls are visible;
- write blockers or repair todos when projection is contradictory.

Useful command:

```bash
loopx --format json auto-research demo-supervisor \
  --goal-id "$LOOPX_GOAL_ID" \
  --workspace "$LOOPX_PROJECT"
```

Must not:

- act as a leader agent;
- select experiments for other roles;
- approve its own gate.

## Writeback

After a validated step, write back only the smallest durable artifact allowed
by the role:

- `research_contract_v0`;
- `research_hypothesis_v0`;
- `auto_research_evidence_packet_v0`;
- promotion/retirement/gate candidate;
- `research_evidence_graph_v0`;
- LoopX todo completion plus next todo/rationale;
- `loopx refresh-state` and one quota spend only after validation when the
  quota contract permits it.

If the step is blocked, write the blocker as a todo/rationale and do not spend
quota merely for discovering an unchanged gate.