# Call surface and agent usability

## Responsibility

Prevent the call-surface failures that have repeatedly made Sidecat unusable:
confusing or overlapping calls, unclear application dependencies, hidden required
state, and sequences agents cannot discover or complete. These are established
project failures, including in generations rebuilt from scratch. Usability is a
primary purpose of the rearchitecture and is connected to maintainable code.

A large catalog of official, third-party, company and local applications is
expected. Total application/operation count is not evidence of poor usability.
Clear application boundaries, dependency information and reusable sequences can
make a large system easier to use. Assess demonstrated tasks and failure modes;
do not claim that application growth inherently causes call-surface failure.

## Knowledge and source material

Read the accepted Version 1 contract, especially V1-04, V1-06, V1-07, V1-08,
V1-09 and V1-14 and the Call surface, Runtime, Work/Plan and Reuse decisions.
Read the selected assignment, current implementation, descriptors, docs and
relevant prior design decisions and recorded caller failures. The short contract
is not the complete inventory of existing functionality or product ideas.

For the selected source revision, read:

- `api/application/v1/contract.md`: identity, discovery, schemas, authority,
  attempt/recovery behavior and composition. Protocol validity is one check.
- `docs/application-authoring.md` and affected apps' public interface docs:
  ownership, dependencies, input/output references and practical use.
- The installed CLI help/man pages, MCP discovery/descriptions, Lisp guidance,
  and any relevant operator interface. Their actual behavior is the evidence.
- The accepted development agreement and independent QA charter. Later drafts
  do not silently replace accepted revisions.

## Review the whole task

1. Name the user's or agent's intended outcome and legitimate starting state.
   Include prepared returning users and fresh users as relevant; do not hide
   preparation in a fixture or require a privileged agent to arrange the trial.
2. Map the necessary applications, dependencies, prerequisites and sequence.
   Determine what discovery, help, responses, routines or workflows tell the
   caller at each step. Required choices and authority remain explicit.
3. Check that an unfamiliar caller can choose the appropriate operation and
   distinguish genuine alternatives. Investigate overlapping meanings; do not
   collapse useful operations merely because names or implementations resemble.
4. Check state and context: the caller can establish scope, know what already
   exists, pass returned references, and identify the next valid action. Avoid
   manually reconstructing IDs or internal bookkeeping where the system can
   reliably retain and compose them.
5. Check failure and continuation: missing prerequisites, wrong scope, refusal,
   interruption and unknown outcomes explain a usable recovery path. Repeated
   work can use retained composition without relearning an undocumented sequence.
6. Compare meanings across affected argv/CLI, MCP, Lisp, native and UI surfaces.
   Shared descriptors must not conceal contradictory instructions or semantics.
7. Inspect the implementation consequences: clarify ownership, avoid duplicated
   adapters and hidden cross-module state, and use public composition. Do not
   centralize domain logic merely to make one front-door command look simple.

## Qualification with QA

Use bounded independent installed trials of representative tasks. Participants
receive the intended shipped entry point and guidance, not the answer or an
unreported private briefing. Record assistance, missing prerequisite discovery,
wrong turns, retries, successful completion, recovery and remaining confusion.
Check the actual result through the owning application, not the participant's
completion claim. An API fixture or author-written example alone is insufficient.

Where catalog growth is relevant, include unrelated applications and distinct
providers; test whether task-relevant discovery and documented dependency paths
still work. Measure calls, context consumed, elapsed time and interventions as
diagnostic evidence. Follow the task's agreed acceptance; neither fewer calls nor
a fixed global count proves usability. Legitimate multi-step work is not a defect.

## Output and coordination

Leave a concise task/sequence map, relevant prior capabilities, observed friction,
proposed dispositions and exact candidate/trial references on the shared Work.
Distinguish retained, changed, retired and unassessed behavior. Explain the reason
and missing evidence for each affected acceptance finding.

Give product management and the delivery lead independent input before the
selected task's interface decisions become implementation dependencies. Work with
component owners and independent QA; review the smallest affected scope. A role
definition grants no permissions, launches no worker and does not change active
assignments. Improvements enter the existing planning cycle; do not redirect
parallel implementers or restart the rearchitecture to answer a local finding.