write-that-shit-down

write-that-shit-down

A no-bullshit project memory system. You forget why decisions were made. Future-you (and Claude) need that context. Write it down.

When to activate

Activate proactively when the user does any of these:

• States a decision: "let's use X", "going with Y", "switching to Z"
• Picks between alternatives: vendor choice, library, hosting, schema design
• Makes a trade-off: cost vs perf, security vs UX, simple vs flexible
• Renames or restructures something irreversibly (DB columns, API contracts)
• Adds infra: new AWS service, new container, new bucket, new domain
• Closes a session that changed architecture, deps, hosting, or external services
• Asks: "why did we...", "what was the reason for...", "remind me why..."
• Says: "track this", "document this", "ADR this", "write this down"

Activate explicitly when the user says: /write-that-shit-down:track, "write that down", "log this decision", or asks you to set up a vault.

What to do

1. Initialize the vault (first time)

If vault/ does not exist at project root, create the structure:

vault/
├── INDEX.md                    # link directory, "read this first"
├── _adr-template.md            # decision record skeleton
├── _session-template.md        # session note skeleton
├── services/                   # one note per runnable service
├── infra/                      # one note per cloud resource
├── db/                         # schema, migrations, RLS / access control
├── decisions/                  # YYYY-MM-DD-<slug>.md ADRs (immutable)
├── sessions/                   # YYYY-MM-DD.md session notes
└── patterns/                   # conventions, gotchas, "how we do X"

Use templates/_adr-template.md, templates/_session-template.md, and templates/INDEX-template.md from this skill as starting content. Customize the INDEX to the project's actual services, infra, and DB.

Add vault/.obsidian/ to .gitignore so personal Obsidian config stays local.

2. Capture a decision (ADR)

On any non-trivial decision, write vault/decisions/YYYY-MM-DD-<slug>.md using _adr-template.md. Required fields:

• Context — what problem, what constraints, what was tried
• Decision — the actual choice in one paragraph
• Consequences — what becomes easier/harder, what this locks in
• Alternatives considered — at least 2, with the reason each was rejected

Required frontmatter for queryability:

• area — single bucket: backend | frontend | infra | db | auth | build | ops | product
• components — concrete names that appear in code/infra (e.g. [users-table, billing-service])
• tags — decision flavor (e.g. [vendor-choice, schema, cost, security, migration])
• keywords — extra search terms not in the title (vendor names, libs, error codes)
• related — wikilinks to prior ADRs touching the same area/components

Append the ADR link to INDEX.md under ## Decisions.

ADRs are immutable. To change a decision, write a new ADR that supersedes the old one, link both ways via supersedes / superseded_by.

2a. Query existing decisions (before writing a new one, or when answering "why did we...")

Two queries work on any vault, legacy or new:

1. Free text: Grep -i "<term>" vault/decisions/ -l
2. Wikilink graph: Grep "related:.*<name>" vault/decisions/ -l, then traverse related, supersedes, superseded_by one hop.

Filter sugar on ADRs written with the current template: ^area: <x>, components:.*<x>, tags:.*<x>. These return zero on legacy vaults. Use them as refinements after free-text, not as entry points.

Don't bulk-read. If a query returns more than 3 hits, list filenames and titles only and ask which to open. Skip status: superseded unless tracing history.

Cite any related ADRs in the new ADR's related: field and reference them from Context ("supersedes [[...]]" or "extends [[...]]"). When the user asks "why did we..." or "what did we pick for Y", answer with links to the ADRs found, not from memory.

3. Update touched notes

When a decision changes a service / infra / DB fact, diff-edit the matching note in vault/services/, vault/infra/, or vault/db/. Don't let the vault drift from reality.

4. End of session (mandatory if anything changed)

Before ending a session that touched architecture / files / deps / hosting:

1. Write vault/sessions/YYYY-MM-DD.md summarizing architectural changes and links to new ADRs.
2. Write any new ADRs in vault/decisions/ for non-trivial decisions made.
3. Diff-edit affected service / infra / db / patterns notes.
4. Update INDEX.md to link new notes.

If nothing architectural changed, still write a one-line session note saying so. Cadence matters.

Conventions

• All notes have YAML frontmatter: type, status, last_verified, related.
• Wikilinks use bare names: [[my-service]], not paths. Obsidian resolves them.
• Dates in filenames: YYYY-MM-DD-<slug>.md. Lowercase, hyphenated.
• "Verify before write" — cite code paths, commit SHAs, or config. Don't fabricate metrics.
• ADRs are immutable. Patterns notes are diff-edited. Service/infra/db notes are diff-edited.
• Keep notes short. Link aggressively. The graph is the value.

What this skill is NOT

• Not a replacement for ARCHITECTURE.md or README.md. Those describe current state. The vault preserves why.
• Not a ticket tracker. Use issues for tasks.
• Not a journal. Notes are atomic, topic-scoped, and link to each other.
• Not auto-generated. You write it yourself, in your words. Claude assists.

Reference templates

See templates/ in this skill:

• templates/_adr-template.md
• templates/_session-template.md
• templates/INDEX-template.md

Copy these into vault/ when initializing, then customize.

Why "write that shit down"

Because three weeks from now you will not remember why you picked Lightsail over ECS, or why a column is text NULL instead of varchar(50) NOT NULL. The vault makes that recoverable in one search. Future-you will thank you. Future-Claude will thank you.