skills.rest
maxlainz
maxlainzCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

futurefin-debugging-playbook

Diagnose FutureFin symptoms by mapping errors to root causes and discriminating experiments.

1|Updated May 2, 2026
Search Tags:#debugging#Docker#postgresql#rust#runbook#triage#axum
One-click install
npx skills add https://github.com/maxlainz/FutureFin --skill futurefin-debugging-playbook-maxlainz
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: futurefin-debugging-playbook
Source: https://github.com/maxlainz/FutureFin/tree/main/.claude/skills/futurefin-debugging-playbook
Command: npx skills add https://github.com/maxlainz/FutureFin --skill futurefin-debugging-playbook-maxlainz

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Debugging the FutureFin self-hosted finance app (Axum API, Rust projection engine, React/Vite SPA, embedded PostgreSQL 16) is hard because many failures are silent: plausible-but-wrong projection numbers, login loops with no server error, or charts wrong only at one density. This Skill maps each known symptom to a first move, a likely cause, and a discriminating experiment so you find the mechanism before patching. ## Core Features & Use Cases - Symptom-to-cause triage table: Covers wrong projection/FIRE numbers, HTTP 409/422/413/403/401 responses, migration checksum failures, stale projection caches, hybrid-density chart bugs, dark-mode visual defects, table layout breakage, unhealthy Docker containers, and MCP connection failures. - Discriminating experiments: Each trap includes concrete commands (curl, psql, docker compose, cargo/npm test) that distinguish between candidate root causes, such as comparing monthly vs hybrid projection densities to separate serving bugs from engine model bugs. - Session discipline rules: Enforces reproduce-before-fix, root-cause-before-patch, and checks across both view scopes, both densities, and both themes before declaring a bug fixed. - Use Case: A user reports the FIRE target in the Jubilación form preview disagrees with the chart. The playbook directs you to run the server and client fire-parity test suites against the canonical fixture to identify which side drifted. ## Quick Start Load this skill at the start of any FutureFin debugging session and ask it to triage the symptom you are seeing, for example a 403 on every data endpoint after login.

Frequently Asked Questions about futurefin-debugging-playbook

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

FAQPage Schema
How do I debug wrong projection numbers in FutureFin?▼

First rule out serving bugs by comparing monthly and hybrid density responses at matching month_index values with curl. If both densities and both views agree and are still wrong, reduce the model bug to a deterministic unit test in crates/engine since the engine is pure.

Why does FutureFin return 403 on every data endpoint after login?▼

A 403 on all data endpoints usually means the user is pending: registered but lacking a row in installation_memberships. Query the users and installation_memberships tables via psql; a NULL role confirms the owner must approve the user.

Why is the FutureFin Docker container unhealthy?▼

Since version 3.0.0 the healthcheck probes /v1/ready, so unhealthy means the embedded PostgreSQL is genuinely down or the API process died. Check /v1/ready versus /v1/health with curl and read the interleaved entrypoint and PostgreSQL logs.

How do I fix a login loop where the session cookie is not sticking?▼

A login loop with 200 on login but 401 afterward is typically COOKIE_SECURE=true while accessing the app over plain HTTP, so the browser silently drops the Secure cookie. Inspect Set-Cookie in devtools and disable cookie_secure for non-HTTPS deployments.

When should I not use this debugging playbook?▼

Do not use it for deep projection-model redesign, writing new tests, environment setup from scratch, or deploy/upgrade/backup operations. Those belong to the projection-realism, validation-and-qa, build-and-env, and run-and-operate skills respectively.

Related Skills

Explore More Software Engineering Skills→
blockblock
49

docker-compose-dev

Orchestrate Proto Fleet development with Docker Compose base and override files.

Official
Intermediate
peppone-choipeppone-choi

verify-implementation

Execute sequential verification checks for project implementation parity and standards.

Community
Advanced
HarshodaiHarshodai

tayari-failure-archaeology

Document root causes and lessons from past technical failures in the Tayari Skill Boost repository.

Community
Advanced
mlevisonmlevison
13

critical-thinking-genai

Tests model-generated text with eleven probes that verify claims against external sources.

Community
Intermediate