Repository assumption audit

The repository audit turns assumptions implied by routes, gates, pricing, empty states, recovery paths and product copy into one local ux-assumptions.md file. It reuses a coding-agent runtime you already control. Every entry is a draft with a falsifiable question, measurable signal, numeric threshold and real file-and-line receipt. Code can reveal the assumption; customer evidence is still needed to answer it.

Run the audit

Run the public package from the root of a Git repository. It requires Node.js 20 or later and does not require a Sightspool account, workspace, analytics connection, MCP key or SDK installation.

npx sightspool audit

Automatic selection succeeds only when exactly one supported direct runtime is available. If both Claude Code and Codex CLI are installed, the command stops and asks you to choose rather than silently preferring one provider.

npx sightspool audit --agent claude
npx sightspool audit --agent codex

Audit one app or package

Pass one directory when the consequential user-facing surface lives inside a larger monorepo. The agent reads that scope, while the register remains at the Git repository root so the product has one durable assumption file rather than a competing file per package.

npx sightspool audit apps/web --agent codex

Use another coding agent

Claude Code and Codex CLI have direct adapters. For Cursor, Copilot, Windsurf, Replit or another terminal-capable agent, export the complete host-neutral protocol and give it to that agent. Prompt export itself writes nothing. The receiving host is responsible for applying the protocol's read, evidence and single-file-write boundaries; it does not receive the direct adapters' independent CLI validation step.

npx sightspool audit --agent prompt
npx sightspool audit --agent prompt > /tmp/sightspool-audit-prompt.md

What the agent reads

• Routes, screens and the order a new user meets them.
• Signup, authentication, onboarding, required setup and activation.
• Pricing, checkout, upgrades, trials, usage limits and gates.
• Empty, loading, error, permission, retry and recovery states.
• Core value paths, reminders, saved work and other return loops.
• Support, approval, consent and human-service handoffs.
• README, CLAUDE.md, AGENTS.md, local product copy and recent local Git subjects when available.

The protocol looks across activation, comprehension, value, pricing, retention and service experience. It asks what must be true about people for the product to work as built. Engineering properties such as whether a database will scale are outside this audit unless they create a specific customer-facing assumption.

What a valid draft contains

• An assumption naming a cohort, behaviour or understanding, and the relevant product surface.
• A yes-or-no falsifiable question containing a concrete number.
• A measurable signal and its source. If capture is missing, the entry says not currently instrumented and names where it would need to be added.
• A numeric threshold shaped as at least or at most, with a unit.
• High, medium or low severity, ordered by likely consequence if the assumption is wrong.
• At least one real repository-relative file: path:line provenance receipt.
• Verdict: untested, with no invented observed result.

The direct-adapter safety model

In direct Claude and Codex modes, the coding agent cannot write to the repository. It returns one candidate document outside the repository; deterministic CLI code parses and validates that candidate before performing the only write. Claude receives only local Read, Glob and Grep tools, no persisted session and a strict empty MCP configuration. Codex runs in a read-only, ephemeral sandbox with browser, web-search, app, computer-control, remote-plugin and multi-agent features disabled.

Before accepting a candidate, the CLI checks the frozen v1 format, sequential ids, severity order, concrete questions and thresholds, untested verdicts, absence of observed data, and at least one real file-and-line receipt per entry. A receipt must resolve inside the repository to a file and line that exist; absolute paths, parent traversal, outside-repository symlinks and invented line numbers fail validation. A failed candidate exits non-zero and leaves the repository unchanged.

Safe re-runs

The register is client-owned product knowledge. If ux-assumptions.md already exists, the CLI parses it before spending model-provider time. A safe rerun preserves every existing entry's id, text, notes, observations and verdict, then appends only genuinely new assumptions above the historical maximum id. An empty valid candidate is a successful unchanged result.

If the existing file lacks the v1 marker, contains malformed sections or duplicate ids, or cannot be parsed without risking client content, the command stops. It does not overwrite the file, recycle an id or create a second ux-assumptions.new.md register.

Privacy and provider processing

The CLI sends no repository content, account data, telemetry or audit result to Sightspool. The selected coding-agent provider may process repository context under that provider's terms and the account configuration you already use. Running npx may contact the npm registry to obtain the package. Those are different boundaries, so this audit should not be described as nothing leaving the machine.

The audit protocol itself forbids fetching product URLs, calling APIs, using hosted search or invoking remote MCP tools. Local file reads, local search and local Git history are allowed. There is no covert CLI telemetry; package-registry aggregate download counts and an explicit later import that you approve are the only intended adoption signals.

Machine-readable results

Use JSON when a local workflow needs a stable result rather than terminal prose. Runtime progress goes to stderr and the schema-version-1 envelope goes to stdout. Its status is completed when entries were added, unchanged when no new assumption survived, prompt_ready for prompt export, or error for a non-zero failure. The envelope also carries the selected agent, repository root, audited scope, register path, entry counts, up to three highest-risk drafts and the provider disclosure.

npx sightspool audit --agent codex --json

{
  "schemaVersion": 1,
  "command": "audit",
  "ok": true,
  "status": "completed",
  "agent": "codex",
  "targetPath": "/path/to/repository",
  "scope": ".",
  "registerPath": "/path/to/repository/ux-assumptions.md",
  "entryCount": 8,
  "addedCount": 8,
  "topRisks": [
    {
      "id": "A-001",
      "title": "New signups reach first value",
      "severity": "high"
    }
  ],
  "providerDisclosure": "Sightspool receives no repository content, telemetry, account data, or audit result. Codex CLI may process repository context under the configured provider's terms.",
  "nextStep": "https://www.sightspool.com/for-coding-agents"
}

Fields are additive within schema version 1; existing fields do not change meaning. An error result keeps the same envelope shape, sets ok to false and adds error with a code, message and optional actionable hint.

What the audit cannot establish

• It cannot know what customers understood, valued, expected or why they behaved as they did.
• It does not read deployed behaviour, analytics, customer conversations or live service outcomes.
• It cannot prove causality or rule that an assumption holds or has been refuted.
• Its suggested thresholds and severity are reviewable drafts, not objective facts.
• It does not install the Sightspool SDK, connect MCP, create an account or import the file automatically.
• Prompt export carries the same written protocol, but only the direct Claude and Codex adapters return through the CLI's independent validation and write path.

Use the file on its own or continue

The local register is useful without Sightspool: it gives a team one reviewable record of the consequential assumptions already encoded in the product. If you later want to investigate one with approved evidence, read Optional: import an assumptions audit. Coding-agent access (MCP) is a separate, authorised workspace connection for checking existing product knowledge during a coding session; it is not required to run this unauthenticated audit.