Agent Phases

Phase 1: Researcher Agent

The Researcher is Testonaut's context-gathering phase. Its job is to turn a raw Jira issue key into a rich, validated ContextPack that the Test Architect can trust — the Test Architect should not be guessing from a short ticket summary.

It reads the story, comments, linked tickets, attachments, Confluence references, development links, and already-linked Xray tests. It normalizes all of that into one schema, adds traceability through an evidence graph, optionally enriches attachments with text extraction and vision analysis, and records warnings instead of silently dropping partial failures.

Researcher sequence: build ContextPack, BM25 index, bounded LLM retrieval loop — The high-level flow: build a base ContextPack and BM25 index, then optionally run a bounded LLM retrieval loop to add citations and related tickets.

What the Researcher produces

The Researcher emits a Zod-validated ContextPack — the contract between context gathering and test design.

Section	What it contains	Why it matters
`ticket`	Key, title, type, status, assignee, reporter, labels, components, links	The identity and metadata of the story under test.
`description`	Structure-preserving ticket description text	The primary requirement source.
`comments`	Paginated Jira comments, normalized and deduplicated	QA notes, dev clarifications, edge cases — often the real acceptance detail.
`attachments`	Metadata plus optional extracted text or vision summaries	Screenshots, mockups, feature files, JSON examples, logs.
`relatedTickets`	Expanded bodies of non-test linked tickets	Epic, parent, subtask, related story, or bug context.
`xrayTestCases`	Already-linked Xray Test issues	Lets the design phase avoid duplicate test cases.
`development`	Branch and pull request links from Jira development information	Shows existing implementation activity around the story.
`confluencePages`	Linked Confluence pages, hydrated when credentials are available	Pulls in deeper specs and design notes.
`evidenceGraph`	Typed nodes and edges connecting all evidence	Traceability from requirement to evidence source.
`retrievalCitations`	Optional citations from deep research	Focused evidence selected by the tool-using researcher.
`provenance`	Which tools/methods were called and whether they succeeded	Auditability and debugging.
`warnings`	Non-fatal failures and caps	Makes partial context visible instead of hidden.

Source integration model

The Researcher talks to context sources through a single ContextProvider interface. Today the primary implementation is AtlassianRestSource, which wraps Jira Cloud and Confluence REST APIs. The provider seam matters because future or interactive sources — such as Rovo/MCP-style providers — can be added without rewriting the Researcher.

ContextProvider interface fronting AtlassianRestSource with Jira and Confluence endpoints — A single ContextProvider interface fronts AtlassianRestSource (Jira REST v3, Jira GraphQL, Confluence REST, Xray-linked tests), leaving a seam for future Rovo / MCP providers.

The Jira source gathers:

the issue itself using Jira REST v3;
comments, with pagination;
attachments and issue links;
development information through Jira GraphQL, including branches and pull requests;
remote links that point to Confluence pages;
linked Jira Test issues that represent already-existing Xray coverage.

Every external call records tool provenance: method, tool name, timestamp, success/failure, and message when available.

ADF to Markdown fidelity

Jira and Confluence content often starts as Atlassian Document Format rather than plain text. Flattening that content loses important test detail, especially when acceptance criteria are inside tables or panels. The context layer converts rich Atlassian content into structure-preserving Markdown, keeping headings, lists, tables, panels and callouts, code blocks, inline links and smart-card references, and inline formatting.

Why it matters

The Test Architect sees the actual requirement structure — not a lossy text blob.

Linked-ticket expansion

A user story rarely contains all of the requirement detail by itself. The Researcher expands non-test linked tickets so the design can account for parent, epic, subtask, bug, or related-story context.

Decision flow for classifying linked issues as Xray tests or related tickets — Each linked issue is classified: Xray Tests populate xrayTestCases, everything else is fetched into relatedTickets.

Expansion is bounded. The default is direct linked tickets only, controlled by context.linkedTicketDepth. The Researcher also caps how many related tickets it expands in a run — if there are too many, the extras become a warning rather than triggering an unbounded crawl.

Attachment understanding

Attachments are treated as first-class evidence. The Researcher keeps attachment metadata by default and, when enabled (context.attachmentUnderstanding, default on), downloads and understands supported attachment content.

Attachment processing flow: download, classify, decode text or run vision, store analysis — Attachment pipeline: classify and decode text-like files or run vision on images; otherwise keep metadata — all of it flows into the ContextPack.

Text attachment analysis

Text-like files (.txt, .md, .csv, .json, .xml, .yaml, .feature, .log, config files, HTML) are downloaded and decoded as UTF-8. The extracted content is stored on the attachment as analysis with analysisSource = "text-extraction". Large text is visibly truncated so readers know there was more content.

Vision analysis for images

Image attachments are sent to a multimodal LLM only when a vision-capable client is available. The image is base64 encoded and sent with a QA-specific prompt that asks the model to describe testable details:

visible UI elements and labels;
enabled, disabled, selected, loading, empty, and error states;
validation messages and implied flows;
data shown on the screen;
constraints or rules visible in the design.

The prompt explicitly asks the model to stay factual and not invent behavior that is not visible. The output is stored as analysis with analysisSource = "vision", so the Test Architect can treat the image summary as another evidence source.

Attachment guardrails

Guardrail	Behavior
Same-origin credential guard	Jira credentials are attached only when the attachment URL shares the configured Jira origin. Redirected or external URLs do not receive the token.
Text cap	Text analysis is capped by number of attachments and characters per attachment.
Image cap	Image analysis is capped by image count and byte size.
Non-fatal errors	Failed downloads, oversized images, missing model capability, or unsupported file types become warnings, not hard failures.

Evidence graph

The evidence graph is the Researcher's traceability backbone. It converts the context into typed nodes and edges so later phases can say exactly where a requirement or scenario came from.

The graph starts with the ticket and links it to comments, Confluence pages, attachments, related tickets, existing tests, branches, and pull requests. After the Test Architect extracts acceptance criteria, the graph is rebuilt so requirement nodes can point back to their source evidence. This is what allows downstream design artifacts to carry sourceEvidence instead of untraceable claims.

Knowledge index and deep research

For large tickets, sending all context to the LLM at once is expensive and can be less accurate. Testonaut builds a lightweight BM25 knowledge index over the context corpus — the ticket description, comments, Confluence bodies, related-ticket descriptions, and attachment analyses. BM25 is deterministic and does not require an embedding API, so it is cheap, testable, and stable in CI.

Optional `--deep` tool-using researcher

By default, the Researcher is mostly deterministic: fetch, normalize, analyze, validate. With design-tests --deep, Testonaut adds a bounded LLM-driven retrieval loop. The tool protocol is intentionally small and strict — the LLM must return exactly one JSON action at a time:

Tool	Purpose
`search_context(query, topK)`	Search the BM25 index for focused evidence.
`expand_ticket(key)`	Fetch the body of an allowed linked non-test ticket.
`finish()`	Stop once enough evidence has been gathered.

Deep research loop: build ContextPack and BM25 index, then a bounded LLM tool loop with search_context, expand_ticket, and finish — The deep retrieval loop: the LLM iterates search_context / expand_ticket within a step budget, then finish() hands the citations to test design.

The loop is bounded by a step budget. If the model cannot parse or stops late, the run records warnings and continues with the evidence gathered so far.

Where MCP fits

It is useful to separate two ideas:

Researcher context sources: the current Researcher gathers ticket context through the ContextProvider seam — primarily Jira/Confluence REST today, ready for future Rovo/MCP-style providers.
Implementation and exploration tools: configured MCP servers are passed to downstream code-agent phases. Playwright MCP can explore the running UI and collect real locators; Figma MCP can provide design context when configured.

MCP server configuration lives in .agents/testonaut.config.json under mcpServers and supports stdio, http, and sse transports. Secrets are not stored inline — values can reference environment placeholders such as ${FIGMA_TOKEN}, expanded at runtime.

mcpServers configuration combining config file and environment variables into stdio, http, and sse servers — mcpServers config: .agents/testonaut.config.json plus ${ENV_VAR} expansion wire stdio, http, and sse servers into the code-agent SDKs.

Key takeaway

Phase 1 produces the evidence pack; MCP tools are mainly consumed later to turn that evidence into grounded automation.

Failure behavior and guardrails

The Researcher is designed to degrade visibly rather than fail silently.

Situation	Behavior
Comments cannot be fetched	Continue with issue description and add a warning.
Attachments cannot be downloaded	Keep metadata and add a warning.
Vision model is unavailable	Skip image descriptions; keep attachment metadata.
Confluence page cannot be hydrated	Keep the remote-link metadata and add a warning.
Linked-ticket expansion exceeds cap	Expand what fits and warn about skipped links.
Jira development GraphQL is unavailable	Continue with empty branch/PR lists and add a warning.
Deep research hits its step budget	Keep gathered citations and warn that the budget stopped the loop.

Configuration knobs

Setting	Default	Effect
`context.linkedTicketDepth`	`1`	Controls whether direct linked tickets are expanded. 0 disables expansion.
`context.attachmentUnderstanding`	`true`	Controls whether attachment content is downloaded and analyzed.
`--deep`	off	Enables the bounded LLM retrieval loop before test design.
`mcpServers`	`{}`	Makes MCP tools available to downstream agent phases.
Jira/Confluence env vars	required	Provide credentials and base URLs for context gathering.

Why this phase matters

A poor test design usually starts with poor context. The Researcher collects the full requirement picture, preserves structure, understands screenshots when possible, links evidence together, and hands the next phase a validated artifact instead of a fragile prompt dump. Phase 1 is not just a fetch step — it is the evidence layer for the entire Testonaut workflow.