proofs

name	proofs
description	Build working mini-app proofs before implementing features. Use when starting non-trivial features, exploring unfamiliar APIs, validating architectural approaches, or when uncertainty exists that code can resolve faster than planning. Triggers on "proof this", "build a proof", "spike it out", "prototype first", or when facing implementation unknowns.

Proofs Skill

Use this skill when building small, working proofs to validate approaches before full implementation. Proofs are documentation with runnable experiments attached.

Purpose

Proofs answer "can this work?" with code instead of speculation. When facing uncertainty, working code resolves questions faster than written plans.

When to Create a Proof

Create a proof when:

• Integrating an unfamiliar API or library
• Uncertain if an approach is feasible
• Multiple implementation options exist
• Debugging by isolation helps

Skip proofs when:

• The implementation path is obvious
• You've done this exact thing before
• The task is purely mechanical

Directory Layout

Proofs are stored in ./docs/proofs/ at the project root. Create this directory on demand when writing the first proof. Each proof is a directory containing a README and associated scripts.

docs/proofs/
  2026-02-09_3rd-party-api/
    2026-02-09_3rd-party-api_README.md
    auth-proof.ts
    list-files.ts
    filter-files.ts
    end-to-end.ts

File Naming Convention

YYYY-MM-DD_short-description/

The directory and README share the same prefix:

• Directory: 2026-02-09_supabase-auth/
• README: 2026-02-09_supabase-auth_README.md

Scripts use descriptive names relevant to what they prove.

Template