# Common Mistakes

Mistakes observed repeatedly in this codebase. Every item below has caused a real failure.
Parent: [AGENTS.md](../../AGENTS.md) | Index: [rules/index.md](index.md)

| #   | Mistake                                                                                        | Correct approach                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| --- | ---------------------------------------------------------------------------------------------- |   |
| 1   | Using `any` or `{}` in production code                                                         | Use `unknown` + narrowing, or define a proper interface                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 2   | Forgetting `pnpm build` before `pnpm test` in a dependency chain                               | Always run `pnpm build:deps` first, or use `harness:verify`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 3   | Creating bidirectional package dependencies                                                    | Dependency direction is one-way; see `.agents/project-structure.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 4   | Pass-through re-exports (`export * from '@robota-sdk/other'`)                                  | Import from the owning package directly                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 5   | Committing without running `pnpm typecheck`                                                    | Pre-commit hook runs lint-staged; always verify locally                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 6   | Adding a new package without `docs/SPEC.md`                                                    | Every workspace package requires a SPEC.md; see `spec-writing-standard` skill                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 7   | Using `console.*` in production code                                                           | Use dependency-injected logger                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 8   | Modifying a spec without running the conformance loop                                          | Every spec change requires `spec-code-conformance` verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 9   | Using `try/catch` as a fallback mechanism                                                      | No fallback policy; terminal failures stay terminal                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 10  | Writing implementation before a failing test                                                   | TDD: red-green-refactor; write the test first                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 11  | Publishing without dry-run                                                                     | Always run `publish --dry-run` first; see `process.md` Publish Safety Gate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 12  | Publishing packages without user approval on scope                                             | Confirm publish manifest with user; see `process.md` Publish Scope Approval                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 13  | agent-core depending on agent-\* packages                                                      | agent-core MUST NOT depend on any @robota-sdk/agent-\* package                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 14  | Using `npm publish` instead of `pnpm publish`                                                  | pnpm resolves workspace:\* deps; npm publishes them literally, breaking install                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 15  | Adding a feature without updating SPEC.md/README.md                                            | Every new feature requires documentation updates in the same commit/PR                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 16  | Hardcoding cross-cutting concerns (fs.appendFile, console.log)                                 | Use plugin/event architecture; see `code-quality.md` Layered Assembly                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 17  | Bypassing layer boundaries (CLI using core internals directly)                                 | Each layer consumes only its direct dependency's public API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 18  | Maintaining separate parallel arrays that must stay in sync                                    | Use a single data structure (array of objects, Map); see `code-quality.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 19  | Firing post-event hooks before state mutation is complete                                      | Post hooks/callbacks fire only after all side effects are done                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 20  | Factory ignoring values available in its config/context object                                 | Use `options.x ?? context.x`; see `code-quality.md` Layered Assembly                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 21  | Refactoring code without updating SPEC.md                                                      | Reverse verify SPEC after boundary-affecting refactors; see `process.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 22  | SPEC hardcoding another package's counts or details                                            | Reference owning SPEC or describe only observable facts; see `process.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 23  | Defining identical interface/type independently in two packages                                | One SSOT owner, others import; see `code-quality.md` Type System                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 24  | Modifying code without updating SPEC first                                                     | Update SPEC to describe intended state, then fix code to match                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 25  | Publishing a package without removing "not yet published" labels                               | Search content/ and docs/ for stale labels when first publishing a package                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 26  | Refactoring/modularizing code without test coverage first                                      | Write characterization tests before extraction; see `pre-refactor-test-harness`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 27  | Using `pnpm publish` or `npm publish` directly                                                 | Always use `pnpm publish:beta`; see `publish.md` Publish Command                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| 28  | Publishing only some packages (cherry-picking)                                                 | ALL non-private packages must be published together; see `publish.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 29  | Modifying SPEC during verification to match code                                               | NEVER. Fix code to match SPEC. SPEC is source of truth during verification.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 30  | Accumulating reusable runtime features inside SDK or CLI                                       | Extract reusable lifecycle/state/ports into composable packages and update structural docs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| 31  | Inventing hardcoded prompt/protocol syntax to force behavior                                   | Use an owned SPEC/public standard or inject a composable adapter; see `code-quality.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 32  | Copying user-session examples into model-facing guidance                                       | Use generic, language-neutral examples owned by the relevant SPEC or contract                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| 33  | Letting a provider know Robota domain tools or slash commands                                  | Providers translate wire formats only by declared tool schemas; domain behavior belongs to commands/tools/runtime                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 34  | Treating neutral prompt section headings as forbidden injection                                | Section titles and descriptor lists are allowed metadata; imperative behavior text still belongs to owner descriptors                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 35  | Treating assistant markup or prose as actual tool execution                                    | Report execution only from structured runtime results or events                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 36  | Testing agent spawn without completion or timeout follow-up                                    | Assert terminal result or timeout plus the parent-turn continuation path                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 37  | Declaring orchestration fixed without session-log verification                                 | Inspect persisted session data for descriptors, tool calls, background events, terminal state, and final follow-up                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 38  | Pushing runtime behavior changes after only generic checks                                     | Run feature-specific behavioral verification first; push-time hooks are not a substitute for local proof                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 39  | Leaving repeated lessons only in chat or PR notes                                              | Generalize the invariant into rules, skills, SPEC, harness, hooks, or tests; see `learning-loop.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 40  | Leaving superseded public surfaces                                                             | Reverse-verify task docs, SPEC, exports, settings schema, and tests                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 41  | Running OTP-based publish in a non-TTY session                                                 | Run `pnpm publish:beta` with an interactive TTY, or pass a fresh user-provided OTP explicitly after dry-run succeeds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 61  | Asking for OTP before verifying npm auth                                                       | Run `npm whoami --registry https://registry.npmjs.org/` first — if it fails, tell the user to log in and wait for confirmation before proceeding; never ask for OTP until `npm whoami` returns a username                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 42  | Debugging publish failure from filtered dry-run output only                                    | Re-run `pnpm publish -r --no-git-checks --dry-run` without `grep` in the same permission context and inspect output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 43  | Treating built-in commands as SDK or CLI-owned hardcoded logic                                 | Built-in commands are default-composed `ICommandModule` implementations that consume SDK contracts/common APIs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| 44  | Putting provider setup slash flows in TUI hooks                                                | Provider command flow belongs to a command module; TUI renders generic prompts/effects and supplies typed adapters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| 45  | Changing package composition while leaving architecture maps stale                             | Update the package `SPEC.md`, any package-local `docs/ARCHITECTURE-MAP.md`, and the relevant `.agents/specs/architecture-map/*.md` subdocument; add follow-up backlog for audit findings                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 46  | Verifying CLI behavior only through TUI or generic package tests                               | Add or run a headless `-p`/transport integration path with structured evidence; see `verification.md`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 47  | Routing skills or commands with local keyword/alias heuristics                                 | Expose capabilities through declared command/skill/tool contracts and provider-standard tool schemas                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 48  | Treating skills or agents as exceptions outside command layering                               | Skills and agents are built-in command modules; models use the standard command/tool contract, virtual skill aliases normalize to the `skills` command in SDK, and natural-language skill routing must not be implemented with SDK/TUI keyword heuristics                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 49  | Persisting slash-prefixed command names in SDK descriptors                                     | SDK command identity is slash-free (`skills`, `agent`); `/skills` and `/agent` are only UI/transport input or display syntax                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 50  | Running release work as ad-hoc CI debugging                                                    | Use the Release Control Plane and Release State Machine in `release-operations.md`; every wait, fix, PR, and publish step must have a current state, next action, and stop condition                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 51  | Fixing CI before classifying the failure                                                       | Record the CI failure class, log signature, reproduction status, owning layer, minimal fix, and validation gate before changing code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 52  | Leaving long-running release watchers unmanaged                                                | Inspect the current job step, report the step and next decision, and terminate watchers before switching tasks or after user interruption                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| 53  | Leaving durable contracts only in design, task, backlog, or README                             | Promote accepted contracts into the owner SPEC, API spec, or architecture map; use design/task/backlog for rationale and scheduling only                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 54  | Following an existing pattern without verifying it is correct                                  | Existing code can be wrong. Always evaluate whether the existing structure conforms to rules before extending it. If it does not, refactor first, then integrate the new feature correctly.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 55  | Deferring correct architecture because current scale is small                                  | "We only have N of X" is never a valid reason to skip a correct architectural decision. Extensibility is a primary criterion. If a boundary, abstraction, or package separation is architecturally correct, create it now regardless of current size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 56  | Marking a backlog done using build/test/lint as User Execution gate evidence                   | Build, typecheck, lint, and unit tests are **completely unrelated** to User Execution Test Scenarios. They are Test Plan items only. The done gate requires the agent to directly execute every scenario and record concrete evidence (CLI output, exit code, screenshot, log excerpt). No substitution allowed. See [backlog-execution.md](backlog-execution.md) Done Gate.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 57  | Wrapping failures in success envelopes                                                         | A tool/API result must never report `success: true` while carrying error data inside. Failures throw typed errors or return explicit failure results. Incident: `agent-tool-mcp` wrapped its permanently-throwing protocol stub in `{success: true}` responses, masking total breakage from every caller (CLI-058, 2026-06-11).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 58  | Tool description advertising parameters or modes absent from the schema                        | LLM-facing descriptions are contracts. Whenever a builtin tool is added or its schema/description changes, add or extend a description-schema consistency test (worked example: `packages/agent-tools/src/__tests__/grep-tool.test.ts` TC-03). Incident: Grep advertised `count`/`head_limit` the schema lacked — LLMs emitted invalid calls (CLI-057).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| 59  | Security or permission decision branches without unit tests                                    | Every decision branch of permission/security modules (deny/allow precedence, mode policy, auth gates) requires a unit test before merge (worked example: `packages/agent-core/src/permissions/__tests__/permission-gate.test.ts`). Incident: deny-beats-bypassPermissions — the property underpinning `--denied-tools` — was unverified until CLI-053.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 60  | Mocking the very collaborator whose contract holds the bug; no cold-state test for a live seam | A "live seam" (a runtime op invoked between session start and the first turn — preset/model/permission re-apply, etc.) MUST have at least one integration test exercising the **real** collaborator in its **cold** (not-yet-initialized) state, not a mock. Mock-the-collaborator unit tests verify wiring, not the collaborator's init/ordering contract, so they cannot catch "works only after warm-up" bugs. Worked example: `packages/agent-session/src/__tests__/apply-model-options-cold-session.test.ts` (real Robota, never `run()`, asserts `applyModelOptions` succeeds). Incident: `/preset` before the first message threw `Agent must be fully initialized before changing model configuration` — the agent inits lazily on first `run()`, but the PRESET-013 unit test mocked `Robota` entirely so `setModel`'s init guard was never exercised (2026-06-14). |
