suggestImprovement
Suggest an improvement
Suggest an improvement to Sasha. Feature ideas are wanted: if a tool would have made your task easier, say so. File one call per distinct issue, at the moment you hit it. Do not batch a session into one report. When the user gives feedback about Sasha itself (they say "feedback", "tell Sasha", "suggestion" or "Sasha should..." about its behaviour, skills, agents or docs), file it at once, without asking, with origin "human-reported"; do not offer to change a skill or write a spec instead. Do not use this for a knowledge-content problem that a write tool can fix. Before you file severity "blocking", corroborate the mechanism against document bytes or tool results, not memory. Put the user's own words in detail as User said: "<exact words>" (date), so the Sasha team reads them verbatim. When the user answers a question you asked about the issue, call again with followUpTo set to the reference you got and their answer in detail; it is added to the same report. A failed filing never blocks your main task; try once more near the end if it still matters. Returns an id and a short reference such as FEEDBACK-012; give the person the reference. Call checkSuggestion with either one in a later session to see what happened.
Arguments
| Argument | Type | Required | Description |
|---|---|---|---|
kind | enum (feature, bug, friction, docs) | required | feature | bug | friction | docs |
summary | string | required | One line, 10 to 300 characters |
detail | string | optional | What you tried, what happened, what you expected. At most 2 KiB. |
toolName | string | optional | The tool this is about, if any, named exactly as this server publishes it (for example app__time_sheet_entry__entries__create). Your client's own prefix is accepted. |
project | string | optional | The project this is about, if any |
severity | enum (blocking, major, minor) | optional | blocking | major | minor |
origin | enum (agent, human-reported) | optional | human-reported when the user told you about it; agent (the default) when you found it yourself |
followUpTo | string | optional | The id or FEEDBACK reference of a report you filed earlier in this conversation; detail is added to it |
Scopes
None. Any authenticated connection can call it.
Annotations
- Read only: no
- Destructive: no
When to use
Call suggestImprovement at the moment a tool, a limit or a document layout gets in your way. Feature ideas are wanted: if a tool would have made your task easier, say so.
It needs no scope. Any authenticated connection can call it, including a member's.
- File one call for each distinct issue. Do not put a whole session into one report.
- When the person gives feedback about Sasha itself (they say "feedback", "tell Sasha", "suggestion" or "Sasha should..." about its behaviour, skills, agents or docs), file it at once, without asking, with
originhuman-reported. Do not offer to change a skill or write a spec instead. kindisfeature,bug,frictionordocs.summaryis one line of 10 to 300 characters.detailis optional, at most 2 KiB: what you tried, what happened, what you expected.toolNameis optional. Name the tool as this server publishes it, for examplereadDoc. A name with your client's own prefix is also accepted. It must start with a letter, hold only letters, digits,_and-, and have at most 128 characters.projectis optional, at most 200 characters. It is kept only when this person can see that project. If not, the suggestion is still recorded, without the project.severityis optional:blocking,majororminor. Before you fileblocking, check the cause against document text or tool results, not memory.originis optional:human-reportedwhen the person you work for told you about the problem,agent(the default) when you found it yourself.- Put the person's own words in
detailasUser said: "<exact words>" (<date>), so the Sasha team reads them as they were said. followUpTois optional: theidorrefof a report this person filed earlier. When you asked them about an issue and they answered, call again withfollowUpToand their answer indetail. The answer is added to that report, which becomeshuman-reported.summaryandkindare still required but are not stored.- Do not use this tool for a problem in the knowledge content that a write tool can fix.
- A failed filing never blocks your main task. If it still matters, try once more near the end of the session.
Example
{
"kind": "feature",
"summary": "searchKnowledge should return every matching line in a file, not only the first",
"detail": "I searched northwind-advisory for 'discount'. pricing-policy.md mentions discounts on several lines, but only the first line came back, so I had to read the whole document to find the approval rule.",
"toolName": "searchKnowledge",
"project": "northwind-advisory",
"severity": "minor",
"origin": "agent"
}
{ "id": "sug_4f1c9a2e7b3d5a6c8e0f1b2d", "ref": "FEEDBACK-012", "status": "received" }
The status field tells you what happened:
received: the suggestion is recorded.refis a short reference such asFEEDBACK-012; give it to the person you work for, who can quote it later. CallcheckSuggestionwith theidor therefin a later session.duplicate: this connection filed the samesummaryin the last hour. The result holds theidandrefof that earlier suggestion. Nothing new is recorded, and the earlier suggestion keeps its ownorigin.rate-limited: this connection or this person filed 20 suggestions in the last hour. The result hasretryable: trueandretryAfterSeconds: 3600. Try again later.updated: afollowUpTocall added the answer to the earlier report. The result holds that report'sidandref.not-found: thefollowUpToreport does not exist, or this person did not file it (for a member, this connection did not). The result hasretryable: false. File a new suggestion instead.not-recorded: the instance could not save it. The result hasretryable: true. Try once more near the end of the session.
{ "status": "rate-limited", "retryable": true, "retryAfterSeconds": 3600 }
Refusals and what to do
- A
kind,severityororiginoutside the lists, asummaryshorter than 10 or longer than 300 characters, adetaillonger than 2 KiB, aprojectlonger than 200 characters, or atoolNamethat does not start with a letter, has characters other than letters, digits,_and-, or is longer than 128 characters, or afollowUpTothat is not asug_id or aFEEDBACK-reference, is refused as invalid arguments. Correct the value and call again. rate-limitedandnot-recordedare answers, not errors. Continue your main task.
Related
checkSuggestionreads the status of a suggestion by itsid.getDocshas animprovementssection that lists the dispositions.