Research
What Heimdall is told before it reads the web for a project, what it searches for, how its notes and suggestions are shaped and filtered, why a dismissed idea never returns, what a run costs and where it stops: it never writes to the record.
By the end of this page you will know how Heimdall's researcher thinks: what it is given, what it searches the web for, how its answer becomes notes and suggestions, why the same idea is never proposed twice, and the lines it never crosses. The task itself, pressing Research the domain on a project's overview and keeping or dismissing what comes back, is on the project overview page.
Why research exists
A client's brief says what they want and rarely what the world will hold them to: the data protection rules of their country, the payment and identity integrations their customers expect, the features every product of the kind ships as a baseline, the accessibility standard a public site is measured against. An analyst who starts from the brief alone finds these out one meeting at a time. Heimdall reads the web for them once, at the start, and writes them down with the pages it read, so the planning record starts from what the domain demands rather than from what the brief remembered to say.
What Heimdall is given
The researcher is told about the project in one brief, written the same way every time:
- The project: its name, key, tagline or description, and the client with its industry and country, which decide which laws and which market apply.
- What the record already holds: the titles of the project's epics, requirements, business rules and glossary terms, so Heimdall proposes what is missing rather than what is there.
- The ideas people already dismissed, by title, with the instruction never to propose them again. A dismissal on the overview is remembered for the life of the project.
- The latest brief imported, when there is one: the opening of the text the brief import read, cut to a few thousand characters, so the research starts from the client's own words.
- The house stack, so a finding that lands on the code (a payment gateway's SDK, an accessibility test) is said in terms of what the team builds with.
Anything the person asking may not read on the project (a list of rules on a project where their role cannot see rules) is left out rather than refused.
What it searches for
Heimdall may run up to eight web searches in a run and is told to use them for facts, not opinions, and to cite what it read. It looks, in this order, for:
- what products of this kind commonly do and what their users expect;
- the laws, regulations and standards that apply in the client's country and industry: data protection, payments, accessibility, sector rules;
- the integrations such a client will expect: payments, identity, messaging, shipping, accounting, analytics;
- what the leading products in the space offer as a baseline;
- the security and accessibility expectations the client will be held to.
How it must answer
The researcher answers with one JSON object and nothing else: a list of notes and a list of suggestions.
A note is what Heimdall learned on one topic: the topic in a few words, two or three plain paragraphs, and the web addresses it read. Notes hang under the run, at most eight, the most useful first; the project overview shows the newest finished run's notes under What Heimdall learned, and the research endpoint returns every run's.
A suggestion is one thing the analyst should do about what was learned, in the same shape as the brief import's suggestions so the same cards, decisions and events serve both:
- kind Research for a fact the project must honour: a regulation, an integration the client will expect, a baseline feature;
- kind Improvement for a gap in the project's own record that the research exposed.
Each carries a title, a summary of what to add and why, the sources it rests on, a confidence from 0 to 1 and a one-sentence rationale. At most twelve are kept per run.
How the answer is filtered
Before anything is written, the answer is cleaned the same way every time:
- A note without a topic or a summary is dropped; a source that is not a web address is dropped; the same address is kept once; at most six sources stay on a note or a suggestion.
- A suggestion of any kind other than Research or Improvement is dropped, as is one without a title. A confidence outside 0 to 1 is pulled back into the range.
- A suggestion whose title matches, letter for letter and case aside, one the project already holds as a research suggestion (pending, kept or dismissed) is dropped, so a second run adds to the first rather than repeating it. The run's suggestion count is the number that survived.
Summaries are turned into sanitised HTML paragraphs and shown as text on the cards; nothing in a page Heimdall read reaches your browser as markup.
One run at a time, on the queue, as you
Pressing Research the domain writes a run as Queued, puts the work on the queue and answers at once; the rail polls while the run is Researching and refreshes itself when the notes land. The work runs as the person who asked, with their permissions, inside the same metered window every other Heimdall feature uses, so what Heimdall may read is what you may read. A second ask while a run is queued or researching is refused with a toast; wait for it to finish or fail.
A run Failed when the model did not answer, when its answer held nothing that could be read, when the team's monthly budget had no room, or when the person who asked is no longer a member of the team. The reason is kept on the run and shown on the rail; nothing is written, nothing is charged, and Research again starts a fresh run.
What a run costs
One call to the model configured for research, which thinks longer than the inline assists do and may search the web up to eight times, filed in the team's AI ledger under Research and counted against the month's budget on Settings → AI. The budget is checked before the call, the usage is filed right after, and only then are the notes and suggestions written with the ledger row they cost, so a run never exists as ready without its cost and a failed call never costs anything. A team at its cap is refused before the model is asked.
A run is worth repeating when the project moved: a new client country, a brief imported, a round of requirements written. Repeating it on an unchanged project mostly repeats the cost, since the ideas already held are filtered out of the answer.
Where it stops
- It never writes to the record. A kept suggestion stays a note on the overview for everyone to read; nothing becomes an epic, a requirement or a rule unless a person writes it, through the editor, an inline assist or the brief import.
- It never proposes a dismissed idea again. Dismissals are read into every later brief.
- It never runs for a client guest, who sees neither the rail nor the suggestions.
- It never runs where assists are off, per project, under Settings → AI.
- It never runs unmetered. The same guard that stops any model call outside a budgeted window stops the researcher.
Research notes are read by the features that come after them: the standards step of the intake wizard, the test generator and the release writer will draw on what Heimdall learned here as those modules land.
Related
The project overview
Research the domain, read the notes, keep or dismiss the suggestions.
Brief import
The other way Heimdall fills a planning record: from the client's own words.
Improvement sweep
The cards beside the research notes: the gaps in the project's own record.
Research endpoints
List a project's runs with their notes, ask for a run, list the suggestions research left.
research.* events
A run started, ready or failed, for the systems that follow a project.
Usage and budgets
Where every run is filed and what stops it.
Safety and permissions
The rules every Heimdall feature keeps.
How is this guide?
Last updated on
Brief import
What Heimdall is given before it reads a brief, how it fills each kind of suggestion from one uniform row, how it judges its own confidence, why it runs on the queue as you, what it costs and where it stops.
The Council
Heimdall's council: seven named voices, each a lens, convened on a story, a requirement, a rule, a brief import or a project Heimdall scaffolded in conversation; how the voices research the ground, read the record, answer one another and refine the plan Heimdall drafts, how Heimdall rules, what accepting a finding writes, what a sitting costs and where it stops.