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.