no-stubs

No Stubs

Never create stub implementations, placeholder functions, mock returns, or TODO-laden skeletons that pretend to work. Every function, CLI command, API endpoint, MCP tool handler, and AI prompt template MUST contain real, working logic that performs its documented purpose end to end.

Why This Matters

In law enforcement and digital forensics work, a tool that says it did something but actually did nothing is worse than a tool that admits it cannot help. A stubbed-out CSAM hash check that quietly returns "no matches" misses real evidence. A stubbed-out audit logger that returns success but writes nothing leaves an investigator unable to prove what happened during examination. A stubbed-out CASE/UCO export that returns empty JSON-LD breaks interoperability with every downstream tool — silently.

Stubs are technical debt that masquerades as progress. In this domain, they are also a defensibility risk.

The Rules

• If a function is defined, it must do what its name and docstring say.
• If a CLI command is registered, running it must produce its documented output (or a clear, actionable error explaining why it cannot).
• If an API endpoint is wired up, calling it must return the real result — not {"status": "ok"} with no work performed.
• If an MCP tool descriptor is published, the tool MUST execute the action an AI agent would expect from reading the schema.
• If a dependency, model, hash database, or external service is not yet available, surface an actionable error (e.g., "VICS hash database not loaded — run 'tool init --vics-path PATH' first") instead of returning a fake "acknowledged" response.
• Test with realistic synthetic data, not with values that bypass the logic. A test that hard-codes assert classify(image) == "category-1" without actually running the classifier proves nothing.

What Counts as a Stub (and Is Forbidden)

• pass or return None in a function body that is documented to do work
• return {"results": []} from a search endpoint that has not been implemented
• raise NotImplementedError shipped in a release branch (acceptable on a feature branch only when the spec explicitly defers the function to a later milestone and the deferral is documented)
• # TODO: implement left in code that has been committed past the design phase
• An ingest module registered in the module registry that does not actually parse anything
• A CASE/UCO export function that emits the @context but no @graph content
• A "validation" step that always returns "valid" because the validator hasn't been wired up