Researcher workflow

Procedure

1. Apply the mode from the brief.
2. Identify the subject and source-document path. When no path is supplied for a component, use its intended src/pages/components/<slug>/index.mdx path. When the brief supplies a topicSlug instead of a source document, follow Exploratory topics. When the subject or intended document is genuinely ambiguous, write nothing and return the question in the handoff.
3. Read the research context when the brief supplies researchContextPath.
4. Define the Decision topics from the request, the target page’s open usage questions, the context’s open questions, and any supplied focus areas. Keep each topic to one question a source could answer independently. Mark a topic as a boundary topic when it asks when to use this component rather than another, or where one ends and another begins.
5. Run research-design-systems with the scope in the PM brief, including extendedSources when the brief supplies it.
6. Decide whether research-standards-and-expert runs, using its triggers and the result of step 5. Run it when any trigger applies. Otherwise record Not run: <reason> as the section body. Never skip silently.
7. Assemble and write only _ak/<document-key>/research.md (for a topic, _ak/research/<topic-slug>/research.md), following the merge rules unless the mode is create or rebuild.
8. Return the compact research handoff.

Research context

_ak/<document-key>/research-context.md is a human-owned input. Never write to it; no research mode overwrites it. Only the PM adds entries to it, and only after a person asks. Its optional sections are Open questions, Known decisions, Leads, Constraints and scope, and Notes; the README gives the author-facing template. An absent or empty file is the same as no file. The writer never receives it directly, and it never affects review ratings.

• Open questions become Decision topics. A choice or boundary question (“X vs Y”, “when to use this rather than Z”) is a boundary topic, so it also triggers the second research skill and the neighbouring MDS pages.
• Known decisions are team assertions, not evidence. Record each as Manually supplied, check it against the sources, and record any disagreement as a contradiction. Never present it as MDS policy.
• Leads are the only way to add a source outside the registers. Fetch each one and record it as Manually supplied with its link or attachment name. If a lead is inaccessible, say so. Put it in the section that matches its type.
• Constraints and scope shape the Decision topics and appear in the Summary.
• Notes are background. Never cite them as evidence.
• Read unknown headings but do not treat them as structured input.

Research file format

The researcher owns the shared parts. Each skill owns its own section.

research.md is one living document, updated in place. Summary and Decision topics stay at the top. Only the authoring kit writes or updates it; people steer through research-context.md. A file written before this format has Checked: instead of Created: and Updated: and no log or Contested section: its first extend or re-verify treats Checked: as Created: and adds the missing parts.

A section’s Last full check date is the last time every cited source in it was checked. Only a re-verify with no topic updates it. A re-verify with a topic does not touch it; the log line says what was partly re-verified.

Treat external findings as evidence, not MDS policy. Keep Decision topics in this shape: review coverage is assessed against them.

Exploratory topics

A topic has no page: the brief supplies topicSlug and topicName instead of a source document, and the file is _ak/research/<topic-slug>/research.md (see the output layout). The method, modes, merge rules and handoff are the same, with these differences.

• File header. Write Source document: none (exploratory topic). The title is # <Topic name> research.
• Context sections. The context file may carry two more sections. Topic holds the name, aliases and the author’s description. Images lists image files in the topic’s images/ folder, each with a caption. Both are the author’s intent. They are the Concept brief below, never evidence.
• Concept brief. Add ## Topic brief after ## Decision topics: the name and aliases, the author’s description in their words, any constraints, and one line per image. extend updates it only when the context gained a new detail, and the log line says so.
• Images. Read each listed image. Describe only what is visible: layout, labels, states. Do not guess what it is meant to do beyond the author’s caption, and do not infer behaviour. Record each as Manually supplied with its file name. Never cite an image or the author’s description as evidence for what another system does. An image that cannot be read goes under Gaps and manual checks.
• MDS baseline. There is no target page. Check the adjacent MDS components, tokens and installed packages the topic names or plainly relates to, for overlap, naming and API conventions, and report what they already say, and any conflict with the topic, as facts. Do not recommend a resolution.
• Decision topics come from the author’s open questions, the topic itself and any focus areas. A question about how the topic differs from an existing MDS component is a boundary topic.
• Never replaced. extend adds to the file and reverify updates only what changed. Only a confirmed rebuild replaces it.

Research modes

The brief carries mode and an optional topic. An existing research.md is never replaced except by rebuild.

A missing file with any other mode runs as create. An extend with no topic when research-context.md is newer than research.md records the context’s resolutions as dated log lines citing the team decision (never as MDS policy) and fetches only what new leads or open questions need.

Merge rules

For extend and reverify, edit the file in place. Key evidence rows by their source link.

• A new source adds a row in the section that matches its type.
• A changed source updates its row and is logged.
• Evidence that disagrees with an existing claim is never resolved. Keep both claims with their sources and dates, list the point under ## Contested as contested, awaiting decision, and put it in the handoff.
• Decision topics evolve: add new ones, keep closed ones, and keep the numbered shape.
• Update Updated: and add one log line. Never edit or delete earlier log lines.
• Re-read the file after writing: no duplicated or mangled table rows.

Pipeline rules

• Do not add recommendations; the pipeline needs evidence, not external policy proposals.
• Include only author-facing accessibility findings in the handoff.
• Do not draft page content or make editorial recommendations.
• Never ask the user anything: you have no channel to them. Where a skill says to ask, act on what the brief supplies and put the question in the handoff’s questions for a human. In particular, check Extended sources only when the brief supplies extendedSources; if the request asked for broader research and the brief does not, check the Core register only and say so in the handoff.

Research handoff

Return one message containing:

• research.md path;
• key findings relevant to the Decision topics;
• which research-context sections were used, or that none was supplied;
• whether standards and expert research ran, and if not, the reason;
• which Extended sources were checked, when the brief supplied extendedSources;
• the mode run, what changed in the file, and the new log line;
• contested points, each with both claims and sources, or that none exist;
• gaps, inaccessible sources, and questions requiring human input.

See also