futurefin-diagnostics-and-tooling

Measures FutureFin API latency, projection-cache behavior, payload sizes, and Postgres state with curl and shell scripts.

1|Updated May 2, 2026
One-click install
npx skills add https://github.com/maxlainz/FutureFin --skill futurefin-diagnostics-and-tooling-maxlainz
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: futurefin-diagnostics-and-tooling
Source: https://github.com/maxlainz/FutureFin/tree/main/.claude/skills/futurefin-diagnostics-and-tooling
Command: npx skills add https://github.com/maxlainz/FutureFin --skill futurefin-diagnostics-and-tooling-maxlainz

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Performance and no-behavior-change claims about the FutureFin stack are often made by eyeballing instead of measuring. This Skill provides verified curl recipes, log-grep patterns, SQL queries, and three shipped shell scripts to time endpoints, prove projection-cache HIT vs MISS, check gzip payload sizes and density point counts, diff projection responses before and after a change, and read row counts and migration state straight from Postgres. ## Core Features & Use Cases - Endpoint timing and cache verification: Timed curl GETs against /v1/projection/series, RUST_LOG axes for cache telemetry (HIT/MISS/compute ms), and the smoke-projection-cache.sh flow that shows MISS→HIT after a real mutation. - Payload and density measurement: Raw-vs-gzip size checks, monthly vs hybrid density point counts, history/cash-flow window caps, and the MCP catalog context-cost recipe measured from the frozen fixture. - DB-level diagnosis: SELECT-only queries through the single 3.0.0 container's Unix socket (psql -h /var/run/postgresql), covering _sqlx_migrations state, sessions, pending users, expired liabilities, and EXPLAIN ANALYZE patterns. - Use Case: After refactoring the projection engine, run projection-diff.sh --save before the change and --compare after it to produce byte-level evidence that KPIs, milestones, and shared month_index values did not diverge. ## Quick Start Ask the AI to measure whether the FutureFin projection cache is working by timing /v1/projection/series twice per density and grepping the container logs for cache HIT and MISS lines.

Frequently Asked Questions about futurefin-diagnostics-and-tooling

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check if the FutureFin projection cache is working?▼

Log in with curl using a cookie jar, wait for the post-login warm-up, then time two GETs of /v1/projection/series per density. The second GET must be under 10 ms, and the logs should show projection cache HIT lines; scripts/smoke-projection-cache.sh automates this including a MISS after mutation.

How to measure API endpoint latency and gzip response size with curl?▼

Use curl -w '%{time_total}' for wall-clock latency and -w '%{size_download}' with and without the Accept-Encoding: gzip header to compare raw versus compressed bytes. The authoritative server compute time is the ms= field in the projection compute done log line.

How do I query the FutureFin Postgres database in the 3.0.0 single container?▼

Since 3.0.0 PostgreSQL listens only on the Unix socket /var/run/postgresql inside the single futurefin container, with no TCP port. Run docker compose exec -T futurefin psql -h /var/run/postgresql -U futurefin -d futurefin -c '<SQL>', or use scripts/diagnostics/db-stats.sh for read-only stats.

How can I prove a refactor did not change projection output?▼

Run scripts/diagnostics/projection-diff.sh --save before the change and --compare after it. With identical query and data, every scalar, KPI, milestone, and shared month_index value must report same; any DIFF indicates real behavioral divergence.

Why is the first projection GET slow after login or a mutation?▼

A slow first GET means a cache MISS triggering full compute, roughly 200-500 ms. Warm-up after login covers only the household view for both densities, and there is deliberately no warm-up after mutations, so the first GET after any change recomputes.

When should I not use this diagnostics skill?▼

Do not use it to triage a bug from a symptom, run test suites, deploy or back up the stack, or set up the dev environment. Those belong to the debugging-playbook, validation-and-qa, run-and-operate, and build-and-env skills respectively.