Marfin
    CatalogPacks
    GitHub
    BEGINNEROPS07 de mai. de 2026

    Decision Doc

    1-page ADR with a mandatory rollback plan. Refuses trivially reversible decisions and refuses to ship without a rollback.

    View on GitHub
    WORKS IN
    CLAUDEany setup

    Pure-LLM skill. No MCP, no paid tool required. Works on Claude.ai web, desktop and Claude Code.

    WORKS BEST WITH
    • Filesystemoptional

      writes to ./docs/adr/NNN-<slug>.md with an auto-incremented number and reads past ADRs to flag superseded ones

    • GitHub MCPoptional

      opens the ADR as a draft PR against docs/adr/ for team review before adoption

    TAGS
    founderdecisionadrdocumentationengineering

    What this skill does

    Generates a 1-page ADR (Architecture Decision Record): context, options considered, trade-offs, the call, risks, rollback plan. So that in 6 months, when someone asks, you still know why you chose X.

    ADR structure

    • Status: proposed / accepted / superseded
    • Context: the problem, in 3-5 lines
    • Options considered: 2-4 options with pros and cons
    • Decision: what you picked, in 1 sentence
    • Reasoning: why this one and not the others
    • Accepted risks: what will be bad, and why that is OK
    • Rollback plan: how to get out if it goes wrong

    When to use

    • Before picking a database / framework / important SaaS
    • Before changing architecture (monolith → micro / SQL → NoSQL)
    • When you are about to make a choice that will hurt to reverse

    How it works

    1. You describe the problem in 1-3 sentences
    2. The skill asks 4 key questions: deadline, cost, lock-in, does the team know it?
    3. Suggests 3 options to evaluate (based on the problem you described)
    4. For each one: pros, cons, estimated cost, lock-in level
    5. Delivers the ADR already filled in with your choice + reasoning
    6. Includes an explicit rollback plan

    Output example

    ADR-007: Database for purchase storage

Status: proposed
Date: 2026-05-06
Owner: Ivan

Context
Today purchases are logged with console.log (Vercel logs only).
Expected volume: 50-200 purchases/month. Needs: query by
email, audit trail (refunds), 5-year retention (LGPD).

Options considered
1. Supabase Postgres (free tier 500MB)
   + Familiar, RLS out of the box, versioned migrations
   - +1 SaaS to maintain, US-East region latency

2. Vercel KV (Redis)
   + Same provider, low latency, simple
   - Not relational, queries by email cost a scan

3. JSON file on Vercel Blob
   + Zero infra
   - Does not scale, race conditions, no queries

Decision
Supabase Postgres free tier.

Reasoning
Query volume (by email, by date range) needs SQL. The free tier
covers 5+ years of the expected volume. Migrating to paid
(R$ 25/month) is trivial.

Accepted risks
- ~200ms latency for BR users (fine for audit, not for UI)
- Moderate lock-in (Supabase-specific RLS)

Rollback plan
If Supabase fails / gets expensive: migration script to
self-hosted Postgres on Hetzner (R$ 30/month). The
/scripts/migrate-pg/ folder already has a template.
Estimated: 4h of work.

    Pre-reqs

    None.

    Build.

    Work.

    Dream.

    Create.