Step by step

This section walks the whole pipeline, from an empty Knowledge Base to a finished, running journey. Work through it in order the first time; afterwards each part stands alone.

Part 1: Add sources to the Knowledge Base

Before Touchstone can propose anything, it needs the material to reason over.

1. Open the Knowledge Base. The Knowledge Base is in the application menu on the left at both levels: open it from within a project to work with that project's material, or from the organisation to work across all of them. If this is a new project it will be empty.

2. Know which level you're working at. There's no scope picker on upload: what you upload becomes a source of wherever you uploaded it from. Upload from a project for material specific to that application; upload from the organisation for material that spans projects, such as company-wide policy or compliance documentation. The Source level filter beside the list narrows it to organisation or project sources, and from a project you'll see both its own sources and the organisation's; the tabs above the list split sources by state instead: All, Needs review (sources that changed and have requirements waiting on a decision), Never analysed (sources no conversation has used yet) and Archived (sources taken out of use).

3. Add your sources. Upload the documents describing the area you're about to test: a functional specification, a set of user stories, an API definition, an exported diagram. Multiple files can be added at once, by drag and drop or by browsing. Note that sources are files: there's no option to point the Knowledge Base at a URL.

Images inside a document are not read

Only the text of an uploaded file is extracted and analysed. A screenshot, diagram or annotated image embedded in a PDF or Word document is ignored. Touchstone sees the surrounding text and nothing else.

This matters most for the documents people most want to upload. A user guide whose text is thin but whose annotated screenshots carry the actual behaviour will produce thin requirements, and nothing in the interface will tell you why.

The workaround is to upload the images as sources in their own right. An image uploaded as its own source is analysed and used. So export the screenshots that carry meaning, upload them alongside the document, and give each a description that says what it shows and which part of the document it belongs to.

This is a current boundary rather than a fault: a PDF can run to hundreds of pages, so analysing every embedded image is deliberately held back.

4. Wait for processing. Each item shows its own progress. It will read uploading while the file transfers, then summarising while its content is analysed, then it carries a NEW badge (UPDATED if you replaced the file on an existing source). Once the badge appears, the source can be used in a conversation. A source that can't be processed is marked failed and kept so you can inspect it.

If a source fails to upload or process

Retrying rarely helps, because the cause is almost always the file rather than the transfer. Three explanations cover most failures:

• The document is a scan. A PDF whose pages are page images, a signed contract, a photocopied manual, anything produced by a scanner or a phone camera, holds no text to extract, so there is nothing for Touchstone to read and the source is rejected. Run the file through any OCR tool (Acrobat, Google Drive, Preview on macOS) and upload the searchable version it produces, or upload the original digital document if you still have it.
• The format isn't supported. Check the file against the list of supported formats above. Sources are files, so a link to a wiki page or a cloud drive won't upload: export the page first.
• The document is very large. Very large files can fail during the summarising stage. Split the document into sections and upload each separately: it's the reliable route, and it improves retrieval as well, because a chapter-sized source is easier to match to a request than a four-hundred-page manual. Handling of large sources is being improved.

A file that uploads successfully but produces a thin or generic summary is a different problem, and usually means a document whose meaning lives in its images. See the note above on images inside documents.

5. Check the generated title, description and summary. Open a source and it slides out in a panel with three tabs: Source, Projects and Requirements. The Source tab holds what was generated for you. Read the summary: it's what gets searched when Touchstone looks for relevant material, so a source that's been misread may not surface when it should. The full document is fetched on top of it where the summary doesn't go far enough. It's written as a structured breakdown (classification, content scope, entities, operations, business rules, actors, test considerations), which makes it fast to check for anything misread.

6. Correct anything wrong. Title and description are editable in place. The summary has its own Edit Summary editor. Saving a revised summary re-indexes the source and takes it out of use for a moment while that runs, so make your corrections in one pass rather than several. This matters more than it looks: the summary is what gets searched, so it decides whether the source surfaces at all.

7. Tag your sources. Tags make sources easier to find and filter as the Knowledge Base grows. Tagging is available at project level only: organisation-level material isn't tagged.

8. Decide which projects a source reaches. Open a source and switch to its Projects tab. The default is permissive: a source with no projects selected is available to every project. Selecting projects narrows it to those. So assignment is how you restrict a source, not how you release it; if a document should only reach one team, select that project explicitly rather than leaving it unassigned.

9. Check what a source has produced. The Requirements tab lists every requirement traced back to this source, with the coverage reached for each and the version of the source it was drawn from. It's the quickest way to see whether a document is actually earning its place, and, after you replace a source, which requirements were built on the older version.

10. Archive what you're no longer using. Archiving takes a source out of use without losing it. Archived sources can be restored to active use, or deleted outright once you're sure. Archive rather than delete when a document has been superseded but its history still matters.

TIP

Resist the urge to upload everything at once. Retrieval works on relevance, and a Knowledge Base padded with material unrelated to the feature under test makes the relevant content harder to surface. Add what the feature needs, and add more as you widen coverage.

Part 2: Set up Directives

Directives are optional, but setting them up before your first generation saves reworking the output afterwards. Skip to Part 3 if you'd rather see default behaviour first.

1. Open the directives lists. Directives live under Requirements, as three tabs alongside the requirements themselves: Analyst directives, Architect directives and Autopilot directives. Each is managed independently, at organisation and project level.

2. Create a directive and give it a name. The name identifies it within its scope, and it matters more than it looks: a project directive replaces the organisation directive that shares its name. Two directives with different names both apply. Name deliberately: reuse a name when you intend a project to override the organisation default, and pick a distinct one when you intend to add to it.

3. Choose what it applies to. The target is the list you create it in, so start from the right tab. An Analyst directive has no effect on journeys, and neither has any effect on Autopilot: the three sets are applied at different stages and don't reach across.

• Analyst directives. How requirements are analysed and written.
• Architect directives. How journey structures are generated from those requirements.
• Autopilot directives. How Autopilot implements a journey when it runs.

4. Choose the type.

• Instruction. Shapes how the analysis reasons. Domain context, strategy, what to prioritise.
• Convention. Shapes the surface of the output. Naming, titling, tagging, field formatting.
• Template. Shapes the structure of a requirement: which sections exist and in what order. Analyst directives only; the Architect and Autopilot lists offer instructions and conventions.

The three targets and three types are explained in more depth in Directives.

5. Write the content. Be specific and self-contained: the directive is read without the context of the conversation you had when you wrote it. "Requirement titles must start with the module name in square brackets" works; "follow our naming standard" doesn't.

6. Set the priority. Priority orders directives of the same type against each other. It does not decide which directive wins an overlap. That's determined by name, as in step 2.

7. Preview what will be injected. Preview prompt, at the top of the list, shows exactly what the analysis will receive for this target: every enabled directive assembled in order, not just the one you're editing. Use it to confirm your directive appears, reads as you intended, and doesn't contradict another one.

8. Save and enable it. A directive only applies once enabled. Disabling it takes it out of effect immediately, without deleting it: the fastest way to test whether a directive is responsible for something in the output.

Part 3: Generate requirements

1. Start a generation. There are two routes. Run Analyst on any row of the Knowledge Base starts from that source directly: the quickest way in when you know which document covers the area. Or open the Analyst chat from the Requirements list and select sources yourself, which is what the rest of this walkthrough follows, because it gives you control over the source set and room to refine.

2. Select the sources for this generation. Choose only the sources covering the feature you're about to specify. This is the single highest-leverage decision in the whole process: selecting everything dilutes retrieval and produces broad, shallow requirements.

3. Or let Touchstone choose them. Auto-select works from your prompt instead of your selection: it searches the Knowledge Base, scores what it finds, and brings in the best-matching handful of documents or extracts. Useful when you don't yet know which sources cover the area, but where you do know, selecting manually gives a better result.

4. Describe what you want. State the feature, the behaviours that matter, and any cases you already know you need. "Generate requirements for the checkout flow, covering payment failure and expired-session handling" produces markedly better output than "generate requirements for checkout".

5. Watch the progress indicator. The interface reports what it's doing as it works: Extracting information while it retrieves from the Knowledge Base, then Generating response while it writes. A generation that never reports extracting didn't consult your Knowledge Base, which usually means the request was answerable from the conversation or needs to be more specific. Expect a generation to take a minute or two; the proposals appear together when it finishes, not one at a time.

6. Read the response before the proposals. Touchstone explains what it did: which existing requirements it reviewed, what gaps it found, and why it proposed what it proposed. If it misread your request, this is where you'll see it first.

7. Review the proposed requirements. They appear in the Proposals preview panel beside the conversation, one at a time, with a selector at the foot of the panel for moving between them and a count in the heading. Each carries its name, tags, a Risk assessment you can change, and the requirement itself.

8. Open one and check its traceability. Confirm the cited sources actually support the requirement. This is the check that catches a requirement inferred from testing convention rather than from your documentation.

9. Refine in the Chat. Refine the proposal by submitting further Agent Instructions within the Chat: ask for what's missing, tighten scope, correct a misreading. Each refinement creates a new version of the affected proposal rather than a duplicate alongside it.

10. Edit directly where that's quicker. The pencil beside Requirement opens Edit requirement details: a markdown editor over the proposal itself. Your edit is fed back to the analysis, so subsequent output follows your correction rather than repeating the original.

11. Roll back if a refinement went the wrong way. Once a proposal has been edited or refined, its version history shows how it reached its current state, and you can return it to an earlier version.

12. Approve what's right. Approving marks a proposal ready and tells Touchstone to stop re-proposing it. Nothing has reached your project yet, and you can undo an approval if you change your mind.

13. Reject what isn't. Rejecting marks the requirement and moves you on to the next one; it isn't included when you create. You aren't asked for a reason, so if the rejection needs explaining for anyone else, say so in the Chat before you reject: that also tells the analysis what to avoid next time.

14. Create the approved requirements. This is the step that writes them into your project as real Virtuoso assets: a separate, deliberate action from approving.

15. Open them from the Requirements list. Created requirements are project assets: they appear in the Requirements list and can be worked on from there like any other. They also stay in the conversation history, but they're closed to further refinement through the Chat.

Part 4: Generate a journey structure

1. Start from a requirement. Journey generation works from requirements rather than directly from documents. Run Architect on a requirement row opens the Architect chat for it; Link journeys attaches journeys that already exist instead.

2. Ask for journeys. Name the requirements to cover and any scenarios you want represented.

3. Review the proposed structure. Each journey appears as an ordered list of checkpoints, each badged with how it got there: NEW for a checkpoint Touchstone is creating. The preview interleaves each journey with the assets it needs, so a four-journey generation shows as four journeys and their data tables in one list; the count in the heading counts journeys only.

4. Check the objectives. Each generated checkpoint carries an objective: a statement of intent that Autopilot will turn into concrete steps. Read them as a sequence and confirm they describe the flow you expect.

5. Review the test-data table. Data appears as named columns and rows, referenced from checkpoints by column name rather than hardcoded ($min_price, $product_name), so the same checkpoint runs against different data. Each journey gets its own table rather than sharing one, even where the columns are identical, each is marked with the journey that references it. Submit an Agent Instruction if you'd rather they were consolidated.

6. Adjust the data in the Chat. Submit an Agent Instruction within the Chat to adjust the proposed data: add a row for a case you want covered, rename a column, or merge two tables that should be one.

7. Set the goal and starting URL. Choose an existing goal or create one, and supply the URL each journey starts from. Put environment-specific values in environment variables rather than the data table.

8. Approve and create. As with requirements, approving marks the structure ready and creating writes it, along with its data table, into your project, ready for Autopilot. The confirmation then offers two ways to get the steps built. Start autopilot queues the new journeys as background Autopilot runs, so several can build while you get on with something else, and each posts a notification when it finishes. Go to Requirement opens the requirement's Journeys tab, which carries the same Start Autopilot button, and from there you can also open a single journey and run Autopilot on it yourself, watching it work as Part 5 describes.

9. Find them in the goal. Created journeys appear in the goal's journey list as drafts until you publish them, each showing its generated summary, its tags, and its assignee and lifecycle status. The summary Touchstone wrote for each journey is what appears here, which is a good reason to make sure it reads well. It's the line colleagues will judge the journey by.

Part 5: Build the journey with Autopilot

This part follows one run as it happens. If you queued journeys with Start autopilot at the end of Part 4, the building happens in the background instead: open a journey once its notification arrives and review what was built, from step 9 onwards. See Background autopilot runs.

1. Open the journey structure. Start from any journey whose checkpoints carry objectives rather than steps: one you created at the end of Part 4, or an existing journey you have added objectives to.

2. Start Autopilot. Check the journey's URL and environment variables are right for the environment you're pointing at. Autopilot drives a real browser against a live application, and if it can't reach the starting page the run stops there.

3. Read the plan. Before touching your application, Autopilot proposes how it will approach the work. The plan is your main point of influence over the run, so read it against the journey you expect.

4. Adjust the plan in the Chat. Submit an Agent Instruction within the Chat to adjust the Autopilot plan: add anything Autopilot can't infer from the structure: a precondition ("open the filter panel before interacting with the filters"), a warning about an awkward control, or a scope correction. Autopilot won't act on guidance that contradicts the structure, such as deleting a checkpoint.

5. Approve the plan. Execution begins only once you've approved.

6. Watch the preview. The preview shows each page as Autopilot sees it, with its intended target highlighted and its reasoning alongside. It's view-only.

7. Follow the steps appearing in the journey. Generated steps are written into the journey as standard Virtuoso steps as each checkpoint completes. This is where you'll notice a checkpoint being satisfied in a way you didn't intend.

8. Answer if Autopilot asks. When Autopilot hits something it can't resolve, it pauses and asks rather than guessing. You can pick one of the options it offers, but you can also type a reply in the message box, and often that's what's needed. A reply here is an Agent Instruction like any other. In the example below, a slider couldn't be set to an exact value, and Autopilot asked which trade-off to take rather than settling for the wrong number. The run continues from your reply.

9. Review anything flagged. Where a step needs manual attention, Autopilot flags it with an explanation. This is usually a minor adjustment rather than a failed build.

10. Let the validation run finish. On completion, Autopilot re-runs the whole journey in a fresh browser with no AI involvement. The authoring session ran in a browser whose state and timing differ from a clean run, so this is the execution that shows the journey behaves deterministically in normal use.

TIP

The validation run is not a Virtuoso execution: it won't appear in the journey's execution history or count towards its health score. Only executions you run yourself do.

11. Read the completion summary. Autopilot reports what it did and what it asserted, and tells you if the re-run didn't pass: The automatic re-run did not pass — start another Autopilot run on this journey to repair it. A build that authored successfully and then failed validation is a normal outcome; the repair path is Part 6.

12. Inspect the generated steps. They're ordinary Virtuoso steps, so open a few and check the targeting. Expect wait durations that look arbitrary, such as Wait 19 seconds for heading "Hammer". They aren't measured from your application. Each wait is derived from how long Autopilot took to author that step, because the page carries on loading while Autopilot is thinking, and padding the wait stops the finished journey failing on timing that only worked because the model was slow. The same checkpoint generated twice will produce different numbers, and a journey can carry longer waits than it needs, so trim them where you know the real timing.

13. Verify with a regular execution. The journey is now standard, so publish it if it is still a draft and execute it as you would any other, then schedule it or add it to your pipeline.

Part 6: Repair a failing journey

1. Start Autopilot on the failing journey. When a journey's most recent execution failed, Autopilot enters fix mode and analyses that execution. You don't need to open it first. Only the latest execution is considered, so run the journey again first if the failure you want fixed isn't the most recent.

2. Read the root-cause analysis. Autopilot classifies the failure before acting, and shows you its reasoning.

3. Check what it concluded. The distinction that matters: where the application has changed but the behaviour is still correct (a renamed control, a moved element), Autopilot updates the journey to match. Where the change looks like a genuine defect, it stops and reports rather than papering over a real failure.

4. Handle any library checkpoint separately. If the failure is in a library checkpoint, Autopilot stops and reports it. Library checkpoints are shared with other journeys, so it won't modify one unilaterally. That fix is yours to make.

5. Review the proposed repair, then confirm it. Check the updated steps target what you'd expect before accepting them. A repaired journey is re-executed to confirm it passes; if it doesn't, apply the fix yourself or adjust the objective and guidance, then run Autopilot again.

Part 7: Work through your notifications

Use this when returning to a project rather than starting one. It's how you pick up what happened while you were away.

1. Check the unread count. The bell in the top bar carries a count, so you can see there's something waiting without opening anything.

2. Open Notifications. The panel slides out from the right, newest first, with unread items marked by a dot. The expand control at the top opens it to full width, which is worth doing when the summaries are long.

3. Read what each one tells you. Every notification carries its type, a summary and a relative timestamp. Analysis notifications quote the opening of the response, and run notifications give the result ("4 completed, 0 failed out of 4 checkpoints"), so you can often tell whether you need to act without opening anything.

4. Filter to what you're working on. The type filter lists all six areas with a checkbox each, so you can narrow to just Autopilot runs, or just Analyst activity, or any combination.

5. Switch to unread only. The Unread / All toggle is the most useful view when picking up after time away.

6. Click through to the work. Most notifications carry a direct link (Go to chat, Go to knowledge base source) which takes you straight to what it concerns rather than making you find it. Where a notification has no link, the asset is reachable from the project as normal: a journey generation, for instance, is found on its requirement's Journeys tab.

7. Clear what you've dealt with. Mark all as read clears the unread state across the list in one action.

TIP

Marking read starts a 30-day clock; leaving unread keeps the notification for 90. If something matters but you can't deal with it now, leaving it unread is the safer option.

Part 8: Review a source change

Use this when a document you have already generated requirements from is updated. Change propagation is enabled per project; if the steps below don't appear for you, it isn't switched on yet. Keeping tests up to date explains the model behind the review.

Update the source

1. Replace the file on the existing source, don't add a new one. Open the source in the Knowledge Base and use the replace control beside the file name. Replacing in place is what keeps the link to the requirements already derived from the document; uploading it as a new source would create a second, unlinked source instead. Virtuoso tells you how many linked requirements may need review before you confirm.

2. Check what was flagged. Once the new version has been processed, the source shows an Updated badge and a warning marker, and moves into the Needs review filter. Hover the marker to see how many of its requirements need review. Nothing has been changed yet: the flag means a decision is waiting, not that anything was rewritten.

Review the requirements

3. Open the review from the Requirements list. The Analyst tab lists every requirement flagged by a source change. Select the ones you want to review (or all of them) and choose Run Analyst.

4. Read what changed before you ask for anything. The review opens with a plain-language summary of the difference between the two versions, a classification of how serious it is, and a count of the requirements and journeys that could be affected. This is the point to decide how conservative you want the review to be: the suggestions offer to change only what is invalidated, check what still holds, or classify conservatively.

5. Work through the verdicts. Every requirement linked to the source comes back with a verdict, including the ones the change didn't touch. Requirements that still hold are marked No change and are already approved for you; requirements the change invalidates are marked To approve and wait for your decision. The list at the bottom of the preview shows the whole set at a glance.

6. Check the proposed rewrite line by line. On a requirement marked To approve, the Changes tab shows the current text against the proposal with removals and additions highlighted, so you can see exactly what the new source version forces and what has been left alone. Approve it, edit it first, or reject it.

7. Save the proposals, No change verdicts included. Saving is what records the review as having happened. A No change verdict that isn't saved leaves the requirement flagged, so save the whole set rather than only the ones you changed. Saved changes create a new version of the requirement, and the flags on the reviewed requirements clear.

Review the journeys

8. Review the journeys that depend on a changed requirement. Saving a changed requirement doesn't touch its journeys; it flags them. Open the requirement's Journeys tab, where the linked journeys carry the same warning marker and a note that the requirement has changed, and choose Run Architect.

9. Repeat the review one level down. The journey review works the same way: what changed in the requirement, how many journeys are affected, and a verdict per journey. A journey whose checkpoints hard-coded the old behaviour is proposed for update; a journey that still holds comes back as No change.

10. Save, and confirm the flags have cleared. Once nothing downstream is lagging behind its parent, the markers disappear on their own: the journeys, the requirement's Journeys tab, and the source in the Knowledge Base. If a marker persists, something linked to that source is still unreviewed.

TIP

Nothing moves without a decision from you at each stage. The source change flags requirements; saving a changed requirement flags its journeys; saving a changed journey is the end of the line. A change that only touches two requirements out of seven still gives you seven verdicts, five of which say so in one line.