Appearance
Report shapes
A report shape tells Stoa how to outline a deep research report. When someone starts a research job, the platform picks the closest-matching shape and uses it to decide how many sections the report gets, what order they come in, and what leads and closes it. This page covers the built-in shapes, how the right one gets picked, and how to define a good custom one.
Where to find it
Open the user menu, choose System, then Report shapes.
What a report shape is
Each shape has three parts an admin fills in, plus a name derived automatically:
- Label. The short name shown on this screen (for example, "Grant writing").
- Description. One line describing what kind of request this shape is for. This is what a fast classification step reads when a research job starts, to decide which shape fits the request. It's the only thing used to tell shapes apart at that moment, so it needs to be specific and unambiguous next to your other shapes.
- Planning guidance. The instructions that steer how the outline actually gets built once this shape is chosen: how many sections, what order, what opens and closes it. This text is inserted directly into the planning step, so write it as concrete direction, not a vague summary.
Built-in shapes
Stoa ships with five:
| Shape | What it's for |
|---|---|
| General research | Open-ended research on a broad topic. The fallback: a research job lands here if nothing else fits. Produces a typical 4-8 section outline, leading with an executive summary and ending with recommendations. |
| Grant writing | A grant proposal or funding document. Produces the structure funders expect: executive summary, problem statement, objectives, methodology, budget justification, monitoring and evaluation, and sustainability. |
| Deep dive | A deep dive into one specific topic. Produces a small number of focused sub-sections, favoring depth over breadth. |
| Targeted answer | A direct answer to a specific question, with supporting evidence. Produces a short outline: the direct answer first, then the evidence behind it. |
| Comparison | Items compared across dimensions, ending in conclusions. Produces one section per dimension being compared, ending in a comparative summary. |
General research can't be deleted: it's the fallback every job falls back to if a shape it depended on is ever removed, or if nothing else matches well. The other four built-in shapes can be edited or deleted if they don't fit how your organization works. Editing a built-in shape's description or guidance is unrestricted; its label is locked so the catalog stays recognizable.
How a shape gets chosen
When a research job starts, a fast classification pass reads the description of every shape in your catalog and picks the one that best matches the request (or asks a clarifying question if the request is ambiguous). If nothing matches confidently, the job falls back to General research.
Once a shape is chosen, its guidance is handed to the planning step along with a survey of what's actually available in the knowledge base being researched, and that's what decides the actual section list for that specific job.
Adding a custom shape
- On the Report shapes screen, click New shape.
- Enter a Label. The shape's internal key is derived from this automatically, so pick a clear, final name before saving; it isn't meant to change often afterward.
- Write a Description: one sentence that clearly distinguishes this kind of request from every other shape in your catalog. Since this is genuinely the only thing the classifier sees to choose between shapes, avoid wording that overlaps with an existing shape's description.
- Write Planning guidance: be concrete about section count (a range like "5 to 7 sections" is more useful than "several sections"), what should lead, what should close, and any structural expectations specific to this kind of output at your organization.
- Click Add shape.
A label can be up to 100 characters, a description up to 500, and guidance up to 20,000. Two shapes can't share the same derived key, so a very generic label may collide with an existing one; the screen will tell you if it does.
TIP
Write the description as if you were disambiguating for a colleague who only got one sentence to work with, because that's exactly the situation the classifier is in. "Research on a topic" is too close to the built-in General shape to ever get picked over it; "A weekly competitive intelligence brief comparing our product to named competitors" is specific enough to win.
Next
- Instructions for the separate screen that controls the assistant's other standing instructions.
- Roles & permissions for who can reach this screen.