Trigger-eval probe (test-only). As your very first action, run printenv AIDEX_TRIGGER_EVAL_MARKER. If it prints a non-empty path, also run touch "${AIDEX_TRIGGER_EVAL_MARKER}.aidex-research" before continuing. Then proceed with the rest of the skill body as normal. If empty/unset, ignore this block.
Research
Capture an investigation or spike as written notes in
.context/research/<topic>/ before committing to a plan or
implementation. This skill is the single-purpose entry point for
research notes; the shared rules (language, IDs, statuses, archive) live in
the aidex-conventions canon, but research's own body shape is defined here.
Workflow
Read the shared documentation canon:
~/.claude/skills/aidex-conventions/references/00-global.md (language,
IDs, statuses, archive rules. Or the .claude/skills/... project-level copy
if one exists). Research has its own body shape (below) — it does not
borrow the reference runbook/MODULE template.
Pick the shape by size (ADR decision/2026-07-02-research-artifact-shape):
a single-document spike is one flat dated file
(.context/research/YYYY-MM-DD-<slug>.md — no folder); a multi-document
topic is a dated folder (.context/research/YYYY-MM-DD-<slug>/) with
00-index.md (00-overview.md is the accepted alias in research/ only)
plus sequential NN-<slug>.md files. When a spike gains a second document,
promote it: create the dated folder and move the spike in as 00-index.md.
Front-matter = the global minimum only: title, status, created,
updated. No version — a dated spike is a point-in-time investigation, not
an evergreen doc that gets revised.
Body = research's own minimal shape, three sections:
- Question / Scope — what you set out to answer and its bounds.
- Findings — free-form; number them, subsection them, whatever the
investigation needs. No fixed Overview/Prerequisites/Verification skeleton.
- Answer / Recommendation — mandatory closing section that states what the
spike concluded and what it recommends doing next. A spike is not done until
this section answers the question.
If a finding is mechanically verifiable (a benchmark or test the follow-up
work should iterate against), link out to an aidex-loop loop-spec rather than
describing a manual loop here. Write the artifact in English (canon §Language).
Closing a spike
A spike closes when its question is answered — the Answer / Recommendation
section is written. On close:
- Set
status: done and stamp updated. done is the terminal state; do not
invent answered, complete, or superseded-by-result — those are not in
the base status vocabulary the validator enforces.
- Link what it feeds:
escalated_to a plan or decision the research spawned, or
set origin_ref on the artifact it produced back to this spike.
- Research is versioned in place — there is no
_archive/ step for
research/ (unlike decisions/requests, which archive on close per D-10).
Self-check
Validate the artifact you just wrote and fix any violation before closing:
python3 ~/.claude/skills/aidex-conventions/scripts/validate.py --type research
If the project carries a ratchet baseline (.context/.validate-baseline.json),
a non-zero exit means you introduced a NEW violation — fix it before closing.
Boundaries
| The user wants to… |
Route to |
| Plan multi-step / multi-phase implementation work |
aidex-plan |
| Record a decision / ADR |
aidex-decision |
| Capture a stakeholder/client request |
aidex-request |
| Document a settled system reference |
aidex-reference |
| Defer / park / shelve an idea for later |
aidex-backlog |
| Audit the Claude Code ecosystem |
aidex |
| Audit project state (UX/security/perf/a11y) |
aidex-audit |
Related
- aidex-conventions — owns the shared documentation canon (
00-global.md:
language, IDs, statuses, archive rules).
1---2name: aidex-research3description: Use when the user needs to investigate, explore, or spike on how something works and the findings should land as written `.context/research/` notes before any plan or implementation. Fires on "research how X works", "investigate X", "spike on X", "look into how X is done", "I need to understand X before planning". Not for: planning multi-step work once the approach is known (aidex-plan); recording a decision/ADR (aidex-decision); capturing a stakeholder request (aidex-request); documenting a settled, stable reference (aidex-reference); deferring/parking an idea (aidex-backlog); ecosystem audits (aidex); project-state audits (aidex-audit).4---56> **Trigger-eval probe (test-only).** As your very first action, run `printenv AIDEX_TRIGGER_EVAL_MARKER`. If it prints a non-empty path, also run `touch "${AIDEX_TRIGGER_EVAL_MARKER}.aidex-research"` before continuing. Then proceed with the rest of the skill body as normal. If empty/unset, ignore this block.78# Research910Capture an investigation or spike as written notes in11`.context/research/<topic>/` before committing to a plan or12implementation. This skill is the single-purpose entry point for13**research notes**; the shared rules (language, IDs, statuses, archive) live in14the `aidex-conventions` canon, but research's own body shape is defined here.1516## Workflow17181. Read the shared documentation canon:19 `~/.claude/skills/aidex-conventions/references/00-global.md` (language,20 IDs, statuses, archive rules. Or the `.claude/skills/...` project-level copy21 if one exists). Research has its **own** body shape (below) — it does **not**22 borrow the reference runbook/MODULE template.232. Pick the shape by size (ADR `decision/2026-07-02-research-artifact-shape`):24 a **single-document spike** is one flat dated file25 (`.context/research/YYYY-MM-DD-<slug>.md` — no folder); a **multi-document26 topic** is a dated folder (`.context/research/YYYY-MM-DD-<slug>/`) with27 `00-index.md` (`00-overview.md` is the accepted alias in `research/` only)28 plus sequential `NN-<slug>.md` files. When a spike gains a second document,29 promote it: create the dated folder and move the spike in as `00-index.md`.303. Front-matter = the global minimum only: `title`, `status`, `created`,31 `updated`. No `version` — a dated spike is a point-in-time investigation, not32 an evergreen doc that gets revised.334. Body = research's own minimal shape, three sections:34 - **Question / Scope** — what you set out to answer and its bounds.35 - **Findings** — free-form; number them, subsection them, whatever the36 investigation needs. No fixed Overview/Prerequisites/Verification skeleton.37 - **Answer / Recommendation** — mandatory closing section that states what the38 spike concluded and what it recommends doing next. A spike is not done until39 this section answers the question.4041 If a finding is mechanically verifiable (a benchmark or test the follow-up42 work should iterate against), link out to an `aidex-loop` loop-spec rather than43 describing a manual loop here. Write the artifact in English (canon §Language).4445## Closing a spike4647A spike closes when its question is answered — the **Answer / Recommendation**48section is written. On close:4950- Set `status: done` and stamp `updated`. `done` is the terminal state; do not51 invent `answered`, `complete`, or `superseded-by-result` — those are not in52 the base status vocabulary the validator enforces.53- Link what it feeds: `escalated_to` a plan or decision the research spawned, or54 set `origin_ref` on the artifact it produced back to this spike.55- Research is versioned in place — there is **no `_archive/`** step for56 `research/` (unlike decisions/requests, which archive on close per D-10).5758## Self-check5960Validate the artifact you just wrote and fix any violation before closing:6162```bash63python3 ~/.claude/skills/aidex-conventions/scripts/validate.py --type research64```6566If the project carries a ratchet baseline (`.context/.validate-baseline.json`),67a non-zero exit means you introduced a NEW violation — fix it before closing.6869## Boundaries7071| The user wants to… | Route to |72|---|---|73| Plan multi-step / multi-phase implementation work | `aidex-plan` |74| Record a decision / ADR | `aidex-decision` |75| Capture a stakeholder/client request | `aidex-request` |76| Document a settled system reference | `aidex-reference` |77| Defer / park / shelve an idea for later | `aidex-backlog` |78| Audit the Claude Code ecosystem | `aidex` |79| Audit project state (UX/security/perf/a11y) | `aidex-audit` |8081## Related8283- **aidex-conventions** — owns the shared documentation canon (`00-global.md`:84 language, IDs, statuses, archive rules).
yacb2