foolproof-product

Foolproof product — non-skippable code invariants

The release-readiness skill prevents shipping a release without evidence. THIS skill prevents writing code that misbehaves once shipped. The two are complementary; both must be enforced.

v2.0.0 shipped with 23 bugs (A–O) because individual code changes satisfied "the function returns a value" but violated the product invariants below. This skill makes those invariants explicit and checkable.

The 10 principles (P1–P10)

For every code change you make in mcp_server/ or indexer/, walk through this checklist. Skipping any P is a discipline breach.

P1 — No silent failures, ever

For every code path that does work:

• Returns >0 results → succeeds with concrete counts in the response
• Returns 0 results → MUST emit a clear "no results because " message with a fix_command field

Anti-pattern (the v2.0 bug pattern):

def index() -> dict:
    matched = [f for f in files if matches(f)]
    if not matched:
        return {"chunks": 0}   # ← silent zero. NEVER.
    return {"chunks": len(matched)}

Correct:

def index() -> dict:
    matched = [f for f in files if matches(f)]
    if not matched:
        return {
            "chunks": 0,
            "warning": f"No files matched. watched_dirs={watched_dirs} "
                       f"file_extensions={extensions}",
            "fix_command": "codevira configure",
        }
    return {"chunks": len(matched), "files": [str(f) for f in matched]}

P2 — Self-diagnose on startup

Every long-running entry point (MCP server boot, watcher start, indexer process) must run startup health checks:

• Database files openable + expected tables present
• Schema version matches (migrate forward OR halt with error)
• Required dependencies importable (chromadb, sentence-transformers)
• File system permissions on data dir

On any failure: halt with a clear remediation hint. Never start in a degraded state without telling the user.

P3 — Atomic state mutations