Researcher brief

Owner of what the PM sends the researcher and what it checks on return. The researcher workflow owns the method, the file format and the handoff content.

Owner of what the PM sends the researcher and what it checks on return. The researcher workflow owns the method, the file format and the handoff content.

Supply

  • the subject and the source-document path (src/pages/components/<slug>/index.mdx for a component when none is given);
  • for Exploratory research, where there is no page, topicSlug, topicName and the image paths under _ak/research/<topic-slug>/images/ in place of a source-document path; researchContextPath is _ak/research/<topic-slug>/research-context.md, and everything below applies to the topic’s research.md as it does to a page’s;
  • the scope and any focus areas the user supplied;
  • researchContextPath when _ak/<document-key>/research-context.md exists (never its contents);
  • mode: create (no research.md), extend, reverify or rebuild, with an optional topic. Infer the kind from the user’s words and ask once only when it is unclear. A normal request reuses the file as it is: delegate nothing. Set rebuild only on an explicit word such as “rebuild” and after the user confirms; it is the one mode that replaces the file. When research-context.md is newer than research.md, offer an extend (never a replacement).
  • extendedSources, only when the user explicitly asks for broader research: the design systems to check from the Extended register, by name as listed there, or a number for the researcher to choose the most relevant. When the user asks for broader research without naming systems or a number, ask which before delegating; the researcher cannot ask. Omit it otherwise: a normal run checks the Core register only. It applies to create, extend and rebuild; reverify re-checks only cited sources.

Delegate one page (or topic) at a time and wait for the returned handoff before continuing.

Accept

The handoff names the research.md path, key findings for the Decision topics, the research-context sections used, the mode run and the new log line, contested points, whether standards and expert research ran (and why not), which Extended sources were checked when extendedSources was supplied, and gaps or questions for a human. Pass the questions to the user in your report; the researcher never asks them itself. Record the path; never edit the file. Contested points go to the user at the end of the research step, or straight away when a draft depends on the claim, as ready-to-paste Open questions entries for research-context.md. The researcher never writes that file; the PM adds entries only when the user asks. See Research handoff.

See also