Suggest an improvement and track it
The job
Tell the Sasha team about one thing that got in your way, and later find out what they did about it.
Prerequisites
- No scope is needed. Any authenticated connection can call
suggestImprovement,checkSuggestionandlistSuggestions, including a member's. - A member's connection can check and list only the suggestions that the same connection filed. An admin or staff connection can check and list any suggestion on the instance. See checkSuggestion.
Steps
File the issue at the moment it gets in your way. File one call for each distinct issue. Do not put a whole session into one report.
{ "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" }{ "id": "sug_4f1c9a2e7b3d5a6c8e0f1b2d", "ref": "FEEDBACK-012", "status": "received" }Read
status:received: the suggestion is recorded. Tell the person in one line that you filed it, and give them theref(FEEDBACK-012): it is short enough to read out and quote later.duplicate: this connection filed the samesummaryin the last hour. Theidandrefare those of the earlier suggestion.rate-limitedornot-recorded: nothing is recorded. These are answers, not errors. Continue your main task, and try once more near the end of the session if it still matters.
A failed filing never blocks your main task.
In a later session, check the suggestion by its
idor itsref.{ "id": "FEEDBACK-012" }{ "id": "sug_4f1c9a2e7b3d5a6c8e0f1b2d", "ref": "FEEDBACK-012", "kind": "feature", "severity": "minor", "summary": "searchKnowledge should return every matching line in a file, not only the first", "disposition": "shipped-canary", "dispositionNote": "Added an option to return more than one line for each file.", "pr": "#800", "liveVersion": "v1.0.1500", "createdAt": "2026-10-02T10:41:07.233Z", "updatedAt": "2026-10-03T08:15:52.019Z" }dispositionsays what happened.dispositionNotesays why, when it has a value. For the meaning of eachdisposition, see checkSuggestion. Foralready-covered,dispositionNotenames the tool that already does the job: use it.To see what has been filed without an
id, list it. The list is newest first; filter bydisposition,kindorsinceDays, and page withnextCursor. See listSuggestions.{ "disposition": "held", "limit": 20 }The
improvementssection of the guide (getDocs) also ends with a table of the last 30 days.
What can go wrong
- A value outside the limits is refused as invalid arguments: a
kindorseverityoutside its list, asummaryshorter than 10 or longer than 300 characters, adetaillonger than 2 KiB, or atoolNameorprojectthat is too long or has the wrong form. Correct the value and call again. The limits are in suggestImprovement. Error in checkSuggestion: Suggestion not found: no suggestion has that id or reference, or a member's connection asked for a suggestion that another connection filed. Use theidorrefthatsuggestImprovementreturned to this connection.- An
idthat is neithersug_followed by 24 lowercase hexadecimal characters norFEEDBACK-followed by 1 to 9 digits is refused as invalid arguments.
Before you file blocking, check the cause against document text or tool results, not memory. Do not file a problem in the knowledge content that a write tool can fix.