Skip to content
Browse docs
Docs / Reference

The details

The fine print behind the other pages, in one place.

01 Signing in and replies

  • Every reply carries who: environment, host, workspace and actor kind.
  • who.actor.kind says user or agent, which tells the two kinds of sign-in apart.
  • Signing in through the connect pages uses OAuth and acts as you. An agent credential has fewer rights.
  • Your agent sends label once, on its first call. It sticks for that connection, names the agent's seat on the board and tells two sessions of one tool apart.
  • The tools are annsa.priorities, annsa.spec and annsa.ask, which read, and annsa.work, annsa.file, annsa.decide, annsa.board and annsa.share, which act. annsa.help and annsa.surveys are retired and refused, so use annsa.ask about=annsa or annsa.ask about=surveys. annsa.act is still callable as the single tool behind the five. Old action names are refused, and the reply names the new one.
  • The first-call skills are working, spec-skill, decisions and welcome.
  • annsa.ask do_we_have is the check for an existing priority.
  • A held filing needs no retry from your agent.

More in What your agent can do.

02 What an agent can run

  • The actions are submit, claim, unclaim, handoff, write, note, verify, ship, escalate and merge, plus bet, correct, direction and principle.
  • correct accepts title, detail and ruled-out, each with a reason. An agent can correct the title or detail of priorities it filed. The category stays yours.
  • Taking over a held priority needs claim takeover=true and a reason. The reply names who was displaced.
  • An agent can set a stage directly only with planning authority. An agent may also unpark. An agent can't widen its own remit.
  • An agent's severity ranks as proposed straight away and becomes yours when you confirm it (the ··· menu, then Confirm P0).
  • A severity you set counts directly, including from your own agent. A person's severity always wins.
  • A finding with no severity sits at the bottom of the board.
  • Your own agent signed in as you can claim, write specs, record proof and ship.

More in Tools and actions.

03 Ranking and the list

  • How many companies asked drives the rank, not phrasing. A copy-pasted complaint can't buy extra rank. Volume is shown but isn't the sort.
  • Agent findings rank by severity: P0 broken, P1 poor, P2 could be better, P3 minor.
  • Different words for the same problem become one priority. Unrelated feedback stays separate.
  • Fragments under about 10 characters default to English. A Japanese bug report weighs the same as an English one.
  • Praise creates no work item.
  • You can ask for one priority by its number. A priority filed in the last few minutes may be missing from the next list read.
  • The mine view shows what a seat holds and how many need you.
  • Completed work is hidden from the default list. Ask for shipped or shared by name. Your agent can list by stage.
  • Skipping Share Back leaves a priority Shipped. Shipped means the work is done, not that customers know.
  • While a priority is parked, its count and companies keep growing. Unpark returns it exactly where it was. A month of new feedback may have moved the ranking.
  • Agents filter by one bet or by No bet. Moving a bet's place moves the work under it.
  • Your agents can read your direction. Aligned priorities surface higher, and an empty focus is an answer. Revenue Growth sorts by revenue and Bug Fixes & Quality by urgency. Delighters stays empty until customers say something kind.
  • An accelerating theme notifies you that signals are up this week.

More in Working with priorities.

04 Specs, versions and proof

  • annsa.spec priority_number=N pulls one spec.
  • Problem is what the person experiences before any fix. Evidence and direction keeps people and paying customers as evidence, findings as what's broken and ideas as proposals. What to build opens with the outcome.
  • Files to touch lists path (new|modify) for paths the agent checked, or the word Unverified.
  • Each Done When line has the form: given a state, when an action, then an observable result.
  • With no quotes, the agent writes all five sections.
  • An update never loses anything, and a decision stays decided. If the evidence moves under a section you wrote, your text stays and the new reading waits as an update.
  • One seat writing again within 30 minutes updates the same version. A different seat, a person's edit or a refresh starts a new one.
  • Changing What to build marks the version material, so the agent knows direction moved.
  • Your agent reads the spec itself. Batch export is on the priorities list.
  • Proof checks are test, staging, prod or manual. where must be a followable pointer (test id, URL or thread). Prose is refused.
  • A deployed change is not a verified one. A proof records which.
  • The agent's learned note lands as an idea on the priority. Ruled-out options from an unclaim or handoff stay on the priority with their reason.
  • The agent sends pr_url when it claims, notes or ships. The spec id is build_xxxxxxxx or #N.
  • A merged pull request that names the priority marks it shipped once it reaches your live branch and every Done When line has proof.
  • GitHub: your agent gets the repo's context with each spec: tech stack, likely files to touch, related pull requests and your rules files (.cursorrules, CLAUDE.md). Existing specs keep their file paths on disconnect.

More in Shipping and verification.

05 Decisions, principles and memory

  • Your answer shows on the spec as decision only if the priority has a spec. The topic is recorded with the answer.
  • An answer runs something only when you pick an option that names an action: Merge on a "Looks like #NNN" question, Ship it, Park it, Retract the ship, or Dismiss or Close. Anything you type is stored.
  • annsa.decide answer is the call that records an answer.
  • You write principles. Agents only propose them. The answer is read and applied.
  • sign takes may_decide and must_come_back, and names who settles what comes back.
  • A ruled-out entry carries the agent's name, the reason and the time. Options not taken at signing are recorded as ruled out.
  • Outcomes are kept too. Ships and corrections are kept, so the same mistake doesn't come back after a correction.
  • Older memories count a little less each month.

More in Principles.

06 Share Back and releases

  • share is the Share Back call. It sends one message per person, however much shipped for them.
  • Sources that carry an email: survey, widget or API submissions, CSV rows with an email column, Intercom, transcripts and MCP submits with customer_email, and Sheets. Slack feedback only if a forwarded email was parsed.
  • Notes wait for approval unless an account setting sends them. When your own agent runs share, it queues for approval unless your account sends automatically. An email can't be unsent.
  • Failed sends aren't retried on their own.
  • Branding (company name, logo, accent color, footer text, sender name) is set under Settings, then Notifications. Otherwise Annsa's default styling applies.
  • annsa.board cut takes optional since and until. With neither, the release starts where the last one closed. It includes shipped specs not yet in a release and runs over MCP only.
  • A release cut sends nothing and prepares no customer notes. Notes stay one priority at a time.
  • Each row's title reads as the customer would read it. A month of shipped work becomes one page to read, share or publish.

More in Share Back.

07 Imports, the API and transcripts

  • Roadmap lines over MCP land as idea rows, matched to the nearest existing priority or attached to one that fits. No priority is minted. The source stays as context that decisions and principles can lean on, and your agent can read the approved direction.
  • CSV detects feedback text, customer name, email and revenue columns, and auto-detects usual column names. Revenue, MRR, ARR, price or spend map to one value per customer.
  • Name, revenue, SKU and external id are set on import (CSV, Google Sheets). Name shows on quotes. Revenue feeds ranking.
  • Feedback without a name or email still counts. Ranking starts to mean something at around ten pieces.
  • Your agent files one piece at a time and checks for an existing priority first.
  • The API's optional fields are page_url and user_metadata. Duplicates are skipped on your own external_id, and original_source is set on duplicates. Widget submissions are tagged widget in the activity log.
  • Transcript optional fields: transcript_type, transcript_date, company_name, customer_name, customer_email, revenue_band and sku.
  • Responses carry a Link: </openapi.json>; rel="service-desc" header. The app's own endpoints use your signed-in session, so scripts and agents can't call those endpoints.
  • A transcript takes up to 25 segments, at least 15 words each. Speaker attribution is kept where the file has it, and each segment is tagged source: transcript. Duplicates are caught by a content hash.
  • Annsa never invents a revenue figure. Someone writing from a personal address stands alone, and no employer is guessed from gmail.com.
  • Ask for one customer's or account's history by name, from your agent, Ask or Slack.

More in Importing feedback, The API and Transcripts.

08 Surveys

  • Banner (data-survey="bar") takes data-prompt, data-context and data-delay in milliseconds. The default is 2000. 0 shows it immediately.
  • Trigger: <a href="#" data-circuit-page data-api-key=...> with data-survey="page". data-button-text defaults to Feedback.
  • Shared options: data-primary-color (#1C1A18), data-text-color (#FFFFFF), data-theme (auto, light or dark), data-border-radius (6px). data-survey defaults to float, the bubble.
  • The rest of window.AnnsaSurvey: open(), close(), reset() and destroy().
  • The bubble opens with a sentiment row, then an optional text field. Thumbs has an optional one-line follow-up.
  • Your agent can ask about survey results through Ask. The results table also shows email if given and screenshot if captured. Filters can be combined.

More in Surveys.

09 Slack and Ask

  • There is no limit on the number of channels. Polling stops on disconnect.
  • The answer engine is separate from the feedback pipeline.
  • You can name an area to narrow an answer. The answer links to the account.
  • In-app Ask acts as the signed-in person.
  • In Slack, a linked member approves one proposed change before it applies.

More in Asking Annsa in Slack and Ask.

Next guideTools and actions